Dailybot | Convenções da API

Convenções que valem para todo endpoint da API do Dailybot: identificadores, timestamps, casing, paginação, busca, intervalo de datas e versionamento.

Todo endpoint da API pública do Dailybot segue as mesmas convenções para identificadores, timestamps, casing, paginação, busca, intervalo de datas 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). Dependendo do modelo, a API retorna como uuid (Form, Form Response, User) ou como id (Kudo, Check-in, Workflow) — em ambos os casos o valor é um UUID e serve como chave estável e opaca para a sua integração.

Regra: se o recurso tem uma coluna UUID dedicada separada da sua chave primária interna, a API retorna uuid; se a própria chave primária é um UUID, a API retorna id. Ambos são UUIDs.

Recurso	Campo identificador
Form	`uuid`
Form Response	`uuid`
Agent Report	`uuid` (também retorna `id` com o mesmo valor por retrocompatibilidade)
Agent Message	`uuid` (também retorna `id` com o mesmo valor por retrocompatibilidade)
Usuário	`uuid`
Kudo	`id` (UUID)
Check-in (Follow-up)	`id` (UUID)
Workflow	`id` (UUID)

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

Todo endpoint de lista /v1/* retorna o mesmo envelope de resposta:

{
  "count": 152,
  "next": "https://api.dailybot.com/v1/...?page=2&page_size=50",
  "previous": null,
  "results": [ ... ]
}

Parâmetros de query

Parâmetro	Tipo	Padrão	Máx.	Descrição
`page`	integer	1	—	Número de página (indexado a partir de 1)
`page_size`	integer	25	100	Itens por página. Valores > 100 são silenciosamente reduzidos.

Aliases legados (retrocompatíveis)

Parâmetro legado	Equivale a
`limit`	`page_size`
`offset`	Paginação por offset

Esses aliases retornam o mesmo envelope. As URLs next/previous refletem o estilo usado pelo chamador.

Paginação opt-in removida: O parâmetro de query ?paginated=true e o header de requisição X-Dailybot-Paginate: true são ignorados. Todo endpoint de lista sempre retorna o envelope.

Campos do envelope de resposta

Campo	Tipo	Descrição
`count`	integer	Total de itens que correspondem (em todas as páginas)
`next`	string \| null	URL completa da próxima página, ou `null` se for a última
`previous`	string \| null	URL completa da página anterior, ou `null` se for a primeira
`results`	array	Itens desta página (sempre um array, nunca null)

Iterar todas as páginas

PAGE=1
while true; do
  RESP=$(curl -s "https://api.dailybot.com/v1/forms/?page=$PAGE&page_size=100" \
    -H "X-API-KEY: $DAILYBOT_API_KEY")
  echo "$RESP" | jq '.results[]'
  NEXT=$(echo "$RESP" | jq -r '.next')
  [ "$NEXT" = "null" ] && break
  PAGE=$((PAGE + 1))
done

Busca

O parâmetro ?search=<termo> está disponível nos endpoints de lista que expõem conteúdo textual. Realiza correspondência de substring sem diferenciação de maiúsculas/minúsculas, aplicada após o escopo de papel. Combina com paginação e filtros de intervalo de datas.

Comprimento máximo: 256 caracteres. Requisições que excedem esse limite retornam 400 com code: "search_query_too_long".

Endpoints que suportam busca

Endpoint	Campos buscados
`GET /v1/forms/?search=<termo>`	Nome do form
`GET /v1/checkins/?search=<termo>`	Nome do check-in
`GET /v1/forms/{uuid}/responses/?search=<termo>`	Conteúdo das respostas
`GET /v1/checkins/{uuid}/responses/?search=<termo>`	Conteúdo das respostas
`GET /v1/kudos/?search=<termo>`	Mensagem do kudo
`GET /v1/kudos/organization/?search=<termo>`	Mensagem do kudo
`GET /v1/workflows/?search=<termo>`	Nome do workflow
`GET /v1/followups/?search=<termo>`	Nome do check-in (alias depreciado de `/v1/checkins/`)
`GET /v1/users/?search=<termo>`	Nome completo, e-mail

curl "https://api.dailybot.com/v1/forms/?search=retro&page_size=10" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Intervalo de datas

Um filtro de intervalo de datas com reconhecimento de fuso horário está disponível em todo endpoint paginado.

Parâmetros canônicos

Parâmetro	Formato	Descrição
`start_date`	`YYYY-MM-DD`	Início inclusivo — 00:00:00 no fuso horário do chamador
`end_date`	`YYYY-MM-DD`	Fim inclusivo — 23:59:59.999999 no fuso horário do chamador

Comportamento de fuso horário: As datas são interpretadas no fuso horário do usuário autenticado (do perfil). Usa UTC como fallback se nenhum fuso horário estiver configurado.

Também aceitos (aliases legados)

Parâmetros legados	Equivalente
`date_start` / `date_end`	`start_date` / `end_date`
`date_from` / `date_to`	`start_date` / `end_date`

Composição

Combina com ?search= e paginação:

curl "https://api.dailybot.com/v1/checkins/{uuid}/responses/?start_date=2026-07-01&end_date=2026-07-31&search=blocker&page_size=100" \
  -H "X-API-KEY: $DAILYBOT_API_KEY"

Erro: Datas mal formadas retornam 400 com code: "invalid_date_range".

Filtros sem distinção de maiúsculas

Parâmetros de query com estilo enum aceitam qualquer capitalização. Por exemplo, ?filter=kudos_received, ?filter=KUDOS_RECEIVED e ?filter=Kudos_Received resolvem todos para kudos_received. Valores inválidos retornam 400 com code: "invalid_kudos_filter".

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.

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.

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.

Convenções da API · Developers