Developer Platform

Referência da API v1

A API v1 conecta sistemas externos às entidades da Camile AI. Três fluxos suportados: sua entidade conversando com seus usuários, entidades criadas por você para os usuários do seu sistema, e conexão OAuth da entidade do próprio usuário. Contrato estável: /api/v1 · OpenAPI 3.1 (JSON) · Portal do Desenvolvedor

1. Autenticação

Todas as rotas /api/v1 usam Authorization: Bearer com uma credencial do Portal do Desenvolvedor:

API key (cam_sk_live_…) — para o seu backend. Escopos: entities:read, entities:write, entities:chat.
Access token OAuth (cam_at_…) — quando um usuário autoriza a própria entidade. Escopos por entidade: entity:chat, entity:read.

Limite: 120 requisições/minuto por credencial (cabeçalhos X-RateLimit-*; 429 com Retry-After). Chaves e tokens são armazenados apenas como hash — mostrados uma única vez na criação.

2. Endpoints v1

GET/api/v1/me

Identidade da credencial: tenant, escopos, limites. Primeira chamada recomendada.

Auth: API key ou OAuth

GET/api/v1/entities

Lista as entidades do seu tenant (paginado: ?limit=50&offset=0).

Auth: entities:read

{
  "ok": true,
  "entities": [{ "id": "ent_…", "name": "Aurora", "status": "ACTIVE" }],
  "total": 1
}

POST/api/v1/entities

Cria uma entidade completa (Protocolo de Gênese) — caso 2: entidades para os usuários do seu sistema.

Auth: entities:write

{
  "name": "Professor Aurora",
  "purpose": "Ensinar matemática para o aluno João",
  "external_user_id": "user-123"
}

{
  "ok": true,
  "entity": { "id": "ent_…", "name": "Professor Aurora", "status": "ACTIVE" }
}

GET/api/v1/entities/{id}

Detalhe de uma entidade acessível à credencial.

Auth: entities:read

POST/api/v1/entities/{id}/messages

Envia uma mensagem à entidade e aguarda a resposta (até 30s). Use end_user_id para identificar seu usuário final — a entidade desenvolve um modelo daquela pessoa.

Auth: entities:chat

{
  "message": "Explique frações para mim",
  "end_user_id": "user-123",
  "end_user_name": "João",
  "conversation_mode": "social"
}

{
  "ok": true,
  "interaction": {
    "id": "…", "message": "Explique frações…",
    "response": "Claro! Pense numa pizza…", "ts": 1757…
  }
}

GET/api/v1/entities/{id}/messages

Histórico recente de conversas (?limit=30&end_user_id=user-123).

Auth: entities:read

3. OAuth — "vincular minha entidade" (caso 3)

Quando o usuário JÁ tem conta na Camile AI e quer conectar a própria entidade ao seu sistema:

GET/{locale}/oauth/authorize?client_id=…&redirect_uri=…&scope=entity:chat&state=…

Página de consentimento: o usuário faz login (se preciso), escolhe a entidade e autoriza. Redireciona de volta com ?code=…&state=…

Auth: Sessão do usuário (navegador)

POST/api/oauth/token

Troca o code por tokens (form-urlencoded ou JSON). Refresh com rotação.

Auth: client_id + client_secret

grant_type=authorization_code
&code=cam_ac_…&redirect_uri=https://seuapp.com/oauth/callback
&client_id=cam_app_…&client_secret=cam_cs_…

{
  "access_token": "cam_at_…", "token_type": "Bearer",
  "expires_in": 3600, "refresh_token": "cam_rt_…",
  "scope": "entity:chat", "entity_id": "ent_…"
}

POST/api/oauth/revoke

Revoga (totalmente) um grant pelos tokens. O usuário também pode revogar pela conta dele.

Auth: client_id + client_secret

Exemplo: sistema de cursos

Cada aluno autoriza que a própria entidade dele se conecte ao sistema de cursos. O sistema pode então: (a) enviar conteúdo/estímulos para a entidade, (b) ler as respostas via messages, (c) deixar a entidade — que já conhece o aluno — ensinar de volta com o material do curso. Alternativa: o desenvolvedor cria uma entidade-professora por aluno (caso 2) e o aluno conversa com ela sem nunca ter conta na Camile AI.

4. Erros

HTTP	code	Quando
401	unauthorized	Credencial ausente, inválida ou revogada
403	insufficient_scope	A credencial não tem o escopo necessário
404	entity_not_found	Entidade inexistente ou fora do seu acesso
409	entity_unavailable	Entidade pausada/arquivada
429	rate_limited	Mais de 120 req/min
202	pending	Mensagem enfileirada, resposta ainda em processamento

OAuth segue RFC 6749/7009: erros em { "error": "…" } — invalid_client, invalid_grant, access_denied.

5. Exemplo rápido (caso 1)

# 1) Valide a credencial
curl https://camileai.com/api/v1/me -H "Authorization: Bearer cam_sk_live_…"

# 2) Converse com a sua entidade
curl -X POST https://camileai.com/api/v1/entities/ent_…/messages \
  -H "Authorization: Bearer cam_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"message": "Olá! Como você está?"}'

Para agentes de IA e devs

Contrato machine-readable: /developers/openapi.json · Guia em markdown: /developers/agents.md