> ## Documentation Index
> Fetch the complete documentation index at: https://docs.findup.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Canal API

> Consuma o agente como um endpoint HTTP a partir de sistemas de terceiros, autenticando com um token de aplicação.

O canal **API** publica o agente como um **endpoint HTTP** que qualquer sistema externo pode chamar — sites, apps, automações ou backends próprios. A autenticação é feita com um **token de aplicação** (Bearer), gerado na própria tela de Publicar.

## Ativar e obter o token

<Steps>
  <Step title="Abra o canal API">
    Em **Agent Studio → Publicar**, clique no canal **API**.
  </Step>

  <Step title="Gere o token">
    Clique em **Gerar token**. O **endpoint** e o **token** aparecem prontos para copiar.

    <Warning>
      O token é exibido **uma única vez**. Copie e guarde em local seguro — depois dele só mostramos um preview mascarado (`faa_…últimos4`). Se perder, **regenere** (o anterior é revogado na hora).
    </Warning>
  </Step>

  <Step title="Use endpoint + token nas requisições">
    Envie o token no header `Authorization: Bearer <token>` para o endpoint exibido.
  </Step>
</Steps>

### Rotacionar e revogar

* **Regenerar token** emite um novo e **revoga o anterior imediatamente** — atualize suas integrações.
* **Revogar** invalida o token e desativa o canal. Chamadas com o token antigo passam a retornar `401`.

## O endpoint

```
POST {endpoint}
```

O `{endpoint}` é o que aparece na tela, no formato `…/api/agent-api/v1/agents/<uuid-do-agente>/messages`.

**Headers**

| Header          | Valor              |
| --------------- | ------------------ |
| `Authorization` | `Bearer <token>`   |
| `Content-Type`  | `application/json` |

**Corpo da requisição**

| Campo            | Tipo    | Obrigatório | Descrição                                                                       |
| ---------------- | ------- | ----------- | ------------------------------------------------------------------------------- |
| `message`        | string  | Sim         | Mensagem do usuário.                                                            |
| `conversationId` | string  | Não         | **UUID** de uma conversa existente para continuar. Omita para iniciar uma nova. |
| `stream`         | boolean | Não         | `true` → resposta em **SSE**; `false`/omitido → **JSON** (padrão).              |

## O fluxo de conversa

A conversa é identificada por um **UUID** (nunca um id numérico sequencial — isso evita que terceiros adivinhem conversas de outros).

<Steps>
  <Step title="Primeira mensagem (sem conversationId)">
    Não envie `conversationId`. O sistema **cria uma nova conversa** e devolve o `conversationId` (UUID) na resposta.
  </Step>

  <Step title="Mensagens seguintes (com conversationId)">
    Reenvie o `conversationId` recebido para **continuar a mesma conversa**, mantendo o contexto. Sem ele, uma nova conversa é criada a cada chamada.
  </Step>
</Steps>

## Exemplos

<CodeGroup>
  ```bash Nova conversa (JSON) theme={null}
  curl -X POST "https://SEU_ENDPOINT/api/agent-api/v1/agents/<uuid>/messages" \
    -H "Authorization: Bearer faa_seu_token_aqui" \
    -H "Content-Type: application/json" \
    -d '{"message":"Qual o horário de atendimento?"}'
  ```

  ```json Resposta theme={null}
  {
    "conversationId": "b3f1c2a4-5d6e-4f70-8a91-2c3d4e5f6a7b",
    "answer": "Atendemos de segunda a sexta, das 9h às 18h."
  }
  ```

  ```bash Continuar a conversa theme={null}
  curl -X POST "https://SEU_ENDPOINT/api/agent-api/v1/agents/<uuid>/messages" \
    -H "Authorization: Bearer faa_seu_token_aqui" \
    -H "Content-Type: application/json" \
    -d '{"message":"E nos feriados?","conversationId":"b3f1c2a4-5d6e-4f70-8a91-2c3d4e5f6a7b"}'
  ```

  ```bash Streaming (SSE) theme={null}
  curl -N -X POST "https://SEU_ENDPOINT/api/agent-api/v1/agents/<uuid>/messages" \
    -H "Authorization: Bearer faa_seu_token_aqui" \
    -H "Content-Type: application/json" \
    -d '{"message":"Me conte sobre os planos","stream":true}'
  ```
</CodeGroup>

No modo **streaming**, o corpo emite eventos `data: {"type":"text-delta","delta":"..."}` seguidos de `data: [DONE]`, e o `conversationId` volta no header `X-Conversation-Id`.

## Listar mensagens de uma conversa

Recupere o histórico de uma conversa (mensagens do usuário e do agente), de forma **paginada** e em ordem cronológica.

```
GET {endpoint-base}/v1/agents/<uuid-do-agente>/conversations/<conversationId>/messages?page=1&limit=20
```

| Query   | Tipo   | Descrição                   |
| ------- | ------ | --------------------------- |
| `page`  | número | Página (1-based). Opcional. |
| `limit` | número | Itens por página. Opcional. |

<CodeGroup>
  ```bash Requisição theme={null}
  curl "https://SEU_ENDPOINT/v1/agents/<uuid>/conversations/<conversationId>/messages?page=1&limit=20" \
    -H "Authorization: Bearer faa_seu_token_aqui"
  ```

  ```json Resposta theme={null}
  {
    "data": [
      { "role": "USER", "content": "Qual o horário de atendimento?", "createdAt": "2026-06-11T12:00:00.000Z" },
      { "role": "ASSISTANT", "content": "Atendemos de segunda a sexta, das 9h às 18h.", "createdAt": "2026-06-11T12:00:01.000Z" }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
  }
  ```
</CodeGroup>

## Erros

| Status | Quando acontece                                         |
| ------ | ------------------------------------------------------- |
| `401`  | Token ausente, inválido, expirado ou revogado.          |
| `403`  | O token não pertence ao agente da URL.                  |
| `404`  | `conversationId` informado não existe para esse agente. |
| `422`  | `message` ausente ou vazio.                             |

<Tip>
  Cada token é vinculado a **um agente** e isolado por organização. Use tokens diferentes por integração para conseguir revogar uma sem afetar as demais.
</Tip>