Pular para o conteúdo principal
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.

​
Convenções gerais

​
Autenticação

Todas as chamadas HTTP carregam Bearer token no header: 
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: 
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: 
{
  "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: 
{
  "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ódigoSignifica
200Sucesso (resposta inclui dados)
201Criado (sucesso de POST)
204Sucesso sem resposta (típico de DELETE)
400Erro do cliente (body inválido, parâmetro ausente)
401Sem autenticação ou token expirado
403Autenticado mas sem permissão pra esta ação/recurso
404Recurso não existe (ou não pertence à sua org)
409Conflito (ex.: duplicate, race condition)
429Rate limit
500Erro 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: 
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

Conceitos da plataforma

Antes de integrar, entenda o modelo de orgs + agentes.

Suporte

Endpoint que você precisa não está aqui ainda? Mande pro support@apollospace.ai com o caso de uso.