Convenções

Padrão de maiúsculas/minúsculas dos campos

Todos os campos de requisição e resposta usam snake_case — por exemplo, due_date, task_status_id.

Envelopes de resposta

Respostas bem-sucedidas são encapsuladas em um envelope data:

{ "data": { "id": "task_6a2918cff58b0a1d387866ee" } }

Endpoints de listagem adicionam um objeto pagination:

{
  "data": [ /* … */ ],
  "pagination": { "next_cursor": "…", "has_more": true }
}

Erros usam um envelope separado — consulte Erros.

Paginação

Os endpoints de listagem usam paginação por cursor. Passe o next_cursor da resposta anterior para buscar a próxima página; has_more indica quando parar. Trate o cursor como opaco.

Idempotência

Requisições POST (criação) aceitam um cabeçalho Idempotency-Key. Envie uma chave única (até 255 caracteres — um UUID funciona bem) para que uma requisição repetida não possa criar uma duplicata:

curl -X POST https://api.bordio.com/public/v1/tasks \
  -H "Authorization: Bearer brd_sk_live_..." \
  -H "Idempotency-Key: 6a2918cf-f58b-0a1d-3878-66ee00000001" \
  -H "Content-Type: application/json" \
  -d '{ "title": "New task" }'

Como se comporta:

• Mesma chave, mesmo corpo → o resultado original é retornado; nada novo é criado.
• Mesma chave, corpo diferente → 409 conflict_error (already_exists).
• Mesma chave enquanto a primeira requisição ainda está em andamento → 409 conflict_error — faça uma nova tentativa quando a primeira terminar.
• As chaves são lembradas por 24 horas e depois expiram — reutilizar uma chave após esse período é tratado como uma requisição totalmente nova.
• Uma chave é restrita ao seu endpoint (e workspace): a mesma chave em um endpoint diferente é independente.
• Apenas POST é idempotente por meio deste cabeçalho. PATCH/DELETE não são — um PATCH é naturalmente seguro para repetir, já que define os campos com os valores que você envia.