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

# Referência da API

> Endpoints HTTP do Apollo Space para integrações programáticas — convenções de auth, paginação, datas e identificadores.

<Note>
  **API pública em construção.** O Apollo Space expõe internamente uma
  superfície HTTP completa (consumida pelo próprio app), mas a
  curadoria do que vira **endpoint público estável** está em
  andamento. Esta seção será preenchida endpoint-por-endpoint
  conforme cada um for ratificado pra integração externa. Se você
  precisa de um endpoint específico antes de ele aparecer aqui,
  fale com **[support@apollospace.ai](mailto:support@apollospace.ai)**.
</Note>

## Convenções gerais

### Autenticação

Todas as chamadas HTTP carregam **Bearer token** no header:

```http theme={null}
Authorization: Bearer <id_token>
```

O `id_token` é o token Cognito emitido após login. Tem expiração
curta (horas) — use o refresh token pra renovar.

### Identidade da organização

Como o mesmo usuário pode pertencer a múltiplas orgs, toda chamada
precisa especificar **qual org** é o contexto da operação:

```http theme={null}
X-Organization-Id: <org-uuid>
```

Sem esse header (ou com UUID que não pertence ao usuário), a
chamada é rejeitada com 403.

### Versionamento

Endpoints públicos vivem sob `/v1/...`. Mudanças incompatíveis
(breaking changes) vão pra `/v2/...` futuramente — `/v1` é mantido
em paralelo por janela mínima de 6 meses após anúncio.

### Datas e timestamps

* **Timestamps**: ISO 8601 com timezone — ex.: `"2026-06-26T17:45:13Z"`
* **Datas (sem hora)**: `YYYY-MM-DD` — ex.: `"2026-06-26"`
* **Timezone**: sempre UTC nos retornos. Em queries, você pode mandar
  com timezone (Apollo Space converte pra UTC internamente).

### Identificadores

* IDs de recursos (lead, conversation, pipeline, etc.) são **UUIDs**
  versão 4
* Não há IDs auto-incrementais expostos publicamente — sempre UUID

### Paginação

Endpoints que retornam lista usam **cursor-based pagination**:

```json theme={null}
{
  "items": [ ... ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAy..."
}
```

* Pra próxima página: `?cursor=<next_cursor>`
* `next_cursor: null` significa fim da lista
* Cursors **não são URLs estáveis** — não persista; use só pra
  navegação sequencial

### Tratamento de erro

Todos os erros retornam JSON com shape consistente:

```json theme={null}
{
  "error": {
    "code": "lead_not_found",
    "message": "No lead with the given id in this organization.",
    "request_id": "req_abc123"
  }
}
```

* `code`: identificador estável da família de erro (use no seu
  client)
* `message`: descrição legível, **não estável** entre versões
* `request_id`: id pra suporte — cole no chamado pra que o time
  ache o log

### Códigos HTTP

| Código | Significa                                           |
| ------ | --------------------------------------------------- |
| `200`  | Sucesso (resposta inclui dados)                     |
| `201`  | Criado (sucesso de POST)                            |
| `204`  | Sucesso sem resposta (típico de DELETE)             |
| `400`  | Erro do cliente (body inválido, parâmetro ausente)  |
| `401`  | Sem autenticação ou token expirado                  |
| `403`  | Autenticado mas sem permissão pra esta ação/recurso |
| `404`  | Recurso não existe (ou não pertence à sua org)      |
| `409`  | Conflito (ex.: duplicate, race condition)           |
| `429`  | Rate limit                                          |
| `500`  | Erro interno (com request\_id pra investigação)     |

### Rate limits

Endpoints têm limites por **organização + tipo de operação**. Quando
você atinge:

* Resposta `429 Too Many Requests`
* Header `Retry-After: <segundos>` indica quando tentar de novo
* Pra carga sustentada acima do limit padrão, fale com suporte —
  podemos ajustar o teto

### Idempotência

Operações `POST` cobráveis suportam header opcional de idempotência:

```http theme={null}
Idempotency-Key: <seu-uuid-único-pra-essa-operação>
```

Se a chamada falhar e você retentar com a mesma key, o Apollo Space
**não duplica** o efeito (não cobra duas vezes, não envia dois
e-mails, etc.). Recomendado pra qualquer integração séria.

## Surfaces que vão aparecer aqui

Endpoints **planejados** pra publicação (conforme estabilizam):

* **Leads**: CRUD + filtros + import em massa
* **Pipelines**: leitura + criação + reordenação de stages
* **Agentes**: invocação programática + ler traces de runs anteriores
* **Stars**: consultar saldo, histórico, configurar caps
* **Webhooks**: assinar eventos (lead criado, atividade nova, reply
  detectado)

Cada um vai ganhar página própria com schema + exemplo cURL.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Conceitos da plataforma" icon="book" href="/pt/concepts/organizations">
    Antes de integrar, entenda o modelo de orgs + agentes.
  </Card>

  <Card title="Suporte" icon="envelope">
    Endpoint que você precisa não está aqui ainda? Mande pro
    **[support@apollospace.ai](mailto:support@apollospace.ai)** com o caso de uso.
  </Card>
</CardGroup>