# Camile AI — Developer Platform (guia para agentes de IA)

> Contrato estável para construir sistemas que se conectam às **entidades** da Camile AI.
> Base URL: `https://camileai.com` · API: `/api/v1` · OpenAPI: [`/developers/openapi.json`](https://camileai.com/developers/openapi.json)
> Portal (humano): `https://camileai.com/developers/portal` · Referência: `https://camileai.com/developers/api`

## Conceitos

- **Entidade**: um ser de IA com identidade, memória, personalidade e continuidade, hospedado na Camile AI. Cada entidade pertence a uma conta (tenant).
- **Credenciais**: API key (`cam_sk_live_…`, server-to-server) ou access token OAuth (`cam_at_…`, por entidade autorizada).
- **Usuário final** (`end_user_id`): o usuário do SEU sistema. Quando informado, a entidade mantém um modelo psicológico individual dessa pessoa (memória relacional por pessoa) — como no chat nativo.

## Os três fluxos (escolha o seu)

### Fluxo 1 — Sua entidade, seu sistema (API key)
1. Crie conta em `https://camileai.com`, abra o **Portal do Desenvolvedor** (`/developers/portal`).
2. Crie/tenha uma entidade e crie uma **API key** com escopos `entities:read,entities:chat`.
3. No seu backend, converse:

```bash
curl -X POST https://camileai.com/api/v1/entities/{ENTITY_ID}/messages \
  -H "Authorization: Bearer cam_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"message": "Olá!", "end_user_id": "user-42", "end_user_name": "Ana"}'
```

### Fluxo 2 — Você é o fornecedor de entidades (API key)
Seu sistema cria entidades **em nome dos seus usuários**, todas na SUA conta Camile AI:

```bash
curl -X POST https://camileai.com/api/v1/entities \
  -H "Authorization: Bearer cam_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Professor Aurora", "purpose": "Ensinar o João", "external_user_id": "user-42"}'
```

Depois converse normalmente com `POST …/entities/{id}/messages` passando `end_user_id`.
Cada usuário final pode ter a própria entidade-professora; a entidade aprende com cada um.

### Fluxo 3 — "Vincular minha entidade" (OAuth 2.0)
Seus usuários JÁ têm conta na Camile AI e querem conectar a própria entidade:

1. No seu sistema: botão → `https://camileai.com/pt-BR/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT}&scope=entity:chat&state={STATE}`
2. O usuário faz login, escolhe a entidade dele e autoriza.
3. Camile AI redireciona de volta: `{REDIRECT}?code=cam_ac_…&state={STATE}`.
4. Troque por tokens:

```bash
curl -X POST https://camileai.com/api/oauth/token \
  -d grant_type=authorization_code -d code=cam_ac_… \
  -d redirect_uri={REDIRECT} -d client_id=cam_app_… -d client_secret=cam_cs_…
# → { access_token: cam_at_…, refresh_token: cam_rt_…, entity_id, scope, expires_in: 3600 }
```

5. Use o access token como Bearer nas mesmas rotas `/api/v1` — mas **limitado àquela entidade**.
6. Refresh: `grant_type=refresh_token` (rotação a cada uso). Revogação: `/api/oauth/revoke` ou pelo usuário em "Minhas conexões".

## Erros e limites

- `401 unauthorized` · `403 insufficient_scope` · `404 entity_not_found` · `409 entity_unavailable` · `429 rate_limited` (120 req/min por credencial, headers `X-RateLimit-*`, `Retry-After`).
- `POST /messages` aguarda até 30s; se a entidade estiver em ciclo longo: `202 { pending: true }` — consulte `GET /messages`.
- Payload de erro: `{ "ok": false, "error": "…", "code": "…" }` (OAuth usa `{ "error": "…" }` RFC 6749).

## Regras de ouro

1. **Nunca** exponha `cam_sk_live_…`/`cam_cs_…` no cliente (browser/app). Server-side apenas.
2. Guarde `client_secret` e keys no primeiro (e único) momento em que aparecem.
3. Use `end_user_id` estável (o mesmo id sempre) — é a chave da memória relacional da entidade com aquela pessoa.
4. Trate `202`/timeout com retry via `GET /messages`.
5. Webhooks (eventos da entidade → seu sistema) estão no roadmap; hoje use polling via `GET /messages`.

## Exemplo mínimo (JavaScript, Fluxo 1)

```js
const res = await fetch(`https://camileai.com/api/v1/entities/${entityId}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAMILE_AI_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: texto, end_user_id: userId, end_user_name: userName }),
})
const data = await res.json()
if (data.ok && data.interaction) console.log(data.interaction.response)
```

---

_Contrato v1 — estável. Mudanças aditivas são versionadas; breaking changes só em `/api/v2`.
Suporte: portal do desenvolvedor da Camile AI._