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.

Filtragem

GET /public/v1/tasks aceita filtros como parâmetros de consulta: priority, task_status_id, state (open / closed), task_type_id, assignee_id, due_date_from / due_date_to / due_date, tag_id. Sem filtros, retorna todas as tarefas do escopo — o mesmo conjunto que você vê na visão de tabela do projeto no aplicativo web.

curl "https://api.bordio.com/public/v1/tasks?project_id=proj_6594a1b2c3d4e5f6a7b8c9d1&state=open&priority=high,critical" \
  -H "Authorization: Bearer brd_sk_live_..."

Como os filtros se combinam:

• Parâmetros diferentes → AND. state=open&priority=high retorna tarefas abertas que também têm prioridade alta.
• Vários valores dentro de um mesmo parâmetro → OR. Os valores são separados por vírgula: priority=high,critical corresponde a qualquer uma das prioridades. tag_id=tag_a,tag_b corresponde a tarefas que tenham qualquer uma das tags listadas.
• Os ids usam sua forma pública (task_status_…, task_type_…, user_…, tag_…). Um valor malformado retorna 400 validation_error; um id bem formado que não corresponde a nada simplesmente produz uma página vazia. A exceção é project_id: um projeto fora do escopo da sua chave retorna 404 not_found_error.
• priority também aceita none — tarefas sem prioridade (priority=none,low = sem prioridade ou low).
• assignee_id aceita o valor especial none — tarefas sem responsável. Pode ser misturado com ids de usuários: assignee_id=user_6594a1b2c3d4e5f6a7b8c9d1,none (esse usuário, ou ninguém).
• due_date_from / due_date_to aceitam YYYY-MM-DD (interpretado como o início / fim daquele dia, UTC) ou um datetime ISO-8601 completo. Tarefas sem data limite nunca correspondem a um intervalo.
• due_date=none retorna apenas tarefas sem data limite. Não pode ser combinado com due_date_from / due_date_to (400 validation_error).

As receitas de consultas comuns (tarefas sem responsável, atrasadas, sem prioridade) estão em Filtragem de tarefas. A lista completa de parâmetros com esquemas está na Referência da API.

Limpeza de campos

Os endpoints PATCH distinguem duas coisas: um campo omitido permanece inalterado, e um campo enviado como null limpa seu valor — mas apenas onde «sem valor» faz sentido:

Endpoint	Campos que aceitam null	Efeito
PATCH /tasks/:id	priority, due_date, description, assignee_ids, reporter_ids, tag_ids	Limpa o valor (assignee_ids: null = ninguém; tag_ids/reporter_ids: igual a [])
PATCH /tasks/:id/subtasks/:id	assignee_id, due_date	Remove o responsável / a data limite
PATCH /scheduled-events/:id	description, location, reminder_minutes_before	Limpa o texto / remove o lembrete

Todo o resto é non-clearable: enviar null para um campo obrigatório (title, task_status_id, start_at, …) retorna 400 validation_error em vez de ser silenciosamente ignorado. Para zerar uma estimativa numérica, envie 0; para limpar o valor de um custom field específico, envie seu item em custom_fields com valor null.

Observe a diferença em relação aos filtros: nos parâmetros de consulta de GET /tasks o null do JSON não existe, então o valor especial none cumpre o mesmo papel (assignee_id=none, priority=none, due_date=none) — veja Filtragem de tarefas.

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.