Convenções da API · Developers

Todo endpoint da API pública do Dailybot segue as mesmas convenções para identificadores, timestamps, casing, paginação e versionamento. Aprenda uma vez aqui e cada página de referência se lerá exatamente como você espera.

Identificadores

Todo recurso tem um `uuid` globalmente único (RFC 4122 v4). UUIDs são estáveis, opacos e a chave segura para usar na sua integração. Alguns recursos também têm um `id` numérico por compatibilidade herdada — prefira `uuid` para o novo.

Timestamps

Todos os timestamps são ISO-8601 em UTC com precisão de milissegundos (ex. `2026-07-02T14:33:19.412Z`). Campos terminados em `_at` são timestamps; campos terminados em `_date` são só data (`YYYY-MM-DD`). Nunca emitimos strings de hora local.

Casing de campos

Todas as chaves JSON são `snake_case` (`first_name`, `created_at`). Os segmentos de path são `kebab-case` (`/pending-invitations/`, `/agent-reports/`). Os parâmetros de query são `snake_case` (`include_email`, `only_active`).

Paginação

A API traz dois estilos de paginação. `limit` + `offset` para browse clássico (users, teams, kudos). `page` + `page_size` para paginação indexada (mood, forms). Toda resposta de lista é envelopada em `{ count, next, previous, results }`; percorra `next` até ser `null`.

Versionamento

A API pública é versionada por prefixo de URL (`/v1/`). Mudanças aditivas (novos endpoints, novos campos opcionais, novos valores de enum com fallback) podem chegar a qualquer momento. Mudanças breaking chegam em um novo prefixo (`/v2/`) com uma janela mínima de sunset de 6 meses sobre a versão anterior. Veja [/pt/developers/api-changelog](/pt/developers/api-changelog).

Idempotência

Todo `GET`, `PATCH`, `DELETE` é idempotente por semântica HTTP — reenviá-los é seguro. Os `POST` que criam um recurso, no caso geral, **não** são idempotentes; um retry ingênuo após uma falha de rede pode criar recursos duplicados. Ao fazer retry após um 5xx ou erro de rede, primeiro releia o recurso pela sua chave natural (e-mail, nome, id externo) e só re-crie se a leitura retornar 404. A política de retry vive em [/pt/developers/errors#retry-policy](/pt/developers/errors#retry-policy).

null vs. ausente

Um campo definido como `null` significa explicitamente "este atributo não tem valor". Um campo ausente da resposta significa "o chamador não tem permissão de vê-lo" ou "o campo não foi solicitado via include-flag". Não os trate como iguais.