Filtragem de tarefas

GET /public/v1/tasks retorna todas as tarefas do escopo (o mesmo conjunto da visão de tabela do projeto no aplicativo web) e as restringe com filtros de query. Esta página mostra como os filtros se combinam e traz receitas prontas para copiar.

Todos os exemplos assumem:

BASE="https://api.bordio.com/public/v1"
AUTH='Authorization: Bearer brd_sk_live_...'
PROJECT="proj_6594a1b2c3d4e5f6a7b8c9d1"

Como os filtros se combinam

Parâmetros diferentes → AND. Cada parâmetro adicionado restringe o resultado.
Vários valores em um parâmetro → OR. Os valores são separados por vírgula: priority=high,critical corresponde a qualquer um dos dois.
Parâmetros omitidos não restringem nada — sem filtros, todas as tarefas são retornadas.

Parâmetro	Valores	Observações
`priority`	CSV de `lowest`, `low`, `medium`, `high`, `critical` e/ou `none`	`none` = tarefas sem prioridade
`task_status_id`	CSV de ids `task_status_…`	Os ids vêm de Definitions
`state`	`open` \| `closed`	Agrupa os status pelo estado — não é preciso enumerá-los. Com `view=by_task`, significa “se há trabalho a fazer”
`task_type_id`	CSV de ids `task_type_…`
`assignee_id`	CSV de ids `user_…` e/ou `none`	`none` = tarefas sem responsável
`date_from`	`YYYY-MM-DD` ou datetime ISO-8601	Limite inferior (inclusivo) do dia para o qual a tarefa está agendada — o campo `date`, não a data limite
`date_to`	`YYYY-MM-DD` ou datetime ISO-8601	Limite superior do mesmo dia. Qualquer um dos limites ordena a lista por data, das mais antigas para as mais recentes
`due_date_from`	`YYYY-MM-DD` ou datetime ISO-8601	Limite inferior do intervalo de data limite (inclusivo)
`due_date_to`	`YYYY-MM-DD` ou datetime ISO-8601	Limite superior do intervalo de data limite (inclusivo)
`due_date`	`none`	Apenas tarefas sem data limite; incompatível com os limites do intervalo
`tag_id`	CSV de ids `tag_…`	Correspondem tarefas com qualquer uma das tags
`view`	`by_task` \| `by_date`	Muda o que conta como um registro — veja Tarefas recorrentes em uma listagem
`closed_since`	`YYYY-MM-DD` ou datetime ISO-8601	Apenas tarefas concluídas nesse momento ou depois; as mais recentes primeiro

Receitas

Apenas tarefas sem responsável

O valor especial none corresponde a tarefas que não têm responsável:

curl "$BASE/tasks?project_id=$PROJECT&assignee_id=none" -H "$AUTH"

Tarefas de uma pessoa específica — ou de ninguém

none pode ser misturado com ids de usuários no mesmo CSV; dentro de um parâmetro os valores se combinam com OR:

curl "$BASE/tasks?project_id=$PROJECT&assignee_id=user_6594a1b2c3d4e5f6a7b8c9d1,none" -H "$AUTH"

Tarefas sem prioridade — ou com prioridade baixa

A prioridade é opcional, então priority aceita o valor especial none para tarefas onde ela não está definida. Como qualquer valor CSV, ele se combina com OR — «sem prioridade ou low» é um único parâmetro:

curl "$BASE/tasks?project_id=$PROJECT&priority=none,low" -H "$AUTH"

Tarefas abertas com prioridade alta ou crítica

curl "$BASE/tasks?project_id=$PROJECT&state=open&priority=high,critical" -H "$AUTH"

state é a forma mais simples de separar o trabalho aberto do fechado. Se precisar de status específicos («Em andamento», mas não «Nova»), use task_status_id com ids dos endpoints de definitions.

Tarefas com data limite em julho

Ambos os limites são inclusivos; valores só de data se expandem para o início / fim daquele dia (UTC):

curl "$BASE/tasks?project_id=$PROJECT&due_date_from=2026-07-01&due_date_to=2026-07-31" -H "$AUTH"

Também é possível passar apenas um limite — por exemplo, tudo que vence a partir de hoje (due_date_from sozinho), ou uma visão de «atrasadas» — tarefas abertas cujo prazo já passou:

curl "$BASE/tasks?project_id=$PROJECT&state=open&due_date_to=2026-07-17" -H "$AUTH"

Tarefas sem data limite

Um intervalo nunca corresponde a uma tarefa sem data limite, por isso este é um filtro separado:

curl "$BASE/tasks?project_id=$PROJECT&due_date=none" -H "$AUTH"

Tarefas com qualquer uma das tags dadas

curl "$BASE/tasks?project_id=$PROJECT&tag_id=tag_65dcc9c66f2e4e001ab18859,tag_66446ff2dc01cb59f6cbf7a6" -H "$AUTH"

Tudo combinado

Abertas, de prioridade alta, sem responsável, com data limite neste mês:

curl "$BASE/tasks?project_id=$PROJECT&state=open&priority=high&assignee_id=none&due_date_from=2026-07-01&due_date_to=2026-07-31" -H "$AUTH"

Os filtros se compõem com a paginação normalmente — limit e cursor se aplicam ao resultado filtrado (veja Convenções).

Tarefas recorrentes em uma listagem

Por padrão, uma listagem devolve suas tarefas avulsas mais as ocorrências individuais das recorrentes que já existem: aquelas que alguém editou, concluiu ou reagendou. Por isso uma mesma tarefa recorrente pode aparecer como várias linhas, e uma ocorrência que ninguém tocou não aparece de forma alguma.

Passe view=by_task para listar tarefas: uma tarefa recorrente volta como uma única linha com sua regra e a ocorrência de que cuidar em seguida, e suas ocorrências não são listadas separadamente.

curl "$BASE/tasks?project_id=$PROJECT&view=by_task" -H "$AUTH"

A resposta ganha kind, series_id, series_chain_id, recurrence_summary e current_occurrence; veja Tarefas recorrentes. Sem view, o conjunto de registros não muda, então integrações existentes continuam funcionando — mas as novas devem passá-lo explicitamente.

O que acontece em um período

Passe view=by_date com um intervalo de datas para listar ocorrências: cada dia em que uma tarefa recorrente cai vira sua própria linha, ao lado das tarefas avulsas agendadas nesses dias.

curl "$BASE/tasks?project_id=$PROJECT&view=by_date&date_from=2026-09-01&date_to=2026-09-30" -H "$AUTH"

Aqui o intervalo é obrigatório e não pode passar de 31 dias, os resultados vão do início do intervalo e closed_since não se combina com esta visão (400). Detalhes e a lista completa de regras: Listando ocorrências dia a dia.

O que fazer agora

curl "$BASE/tasks?project_id=$PROJECT&view=by_task&state=open" -H "$AUTH"

Nesta visão, state responde “se há trabalho a fazer”: uma tarefa avulsa pelo próprio status, uma recorrente pelas suas ocorrências — aberta enquanto houver uma aberta, fechada quando não sobra nenhuma. Uma tarefa recorrente que ficou sem ocorrências some da listagem mesmo que o status com que suas ocorrências começam seja um “To do” perfeitamente normal.

O que foi concluído recentemente

curl "$BASE/tasks?project_id=$PROJECT&closed_since=2026-07-28" -H "$AUTH"

O que foi concluído é outra pergunta, portanto outra requisição. Cada ocorrência concluída é um registro próprio — é isso que significa “fizemos o standup na terça” —, então esta listagem não se combina com view=by_task: fazer isso devolve 400 validation_error. A ordem é por momento de conclusão, as mais recentes primeiro, e a paginação é a de sempre.

closed_since também rejeita state=open com 400, pelo mesmo motivo: a requisição se contradiz, e uma página vazia seria lida como “nada foi concluído” em vez de “você pediu algo impossível”.

due_date_from / due_date_to / due_date — por que três parâmetros?

Eles respondem a duas perguntas diferentes:

due_date_from / due_date_to selecionam tarefas cuja data limite cai em um intervalo. Use um limite sozinho ou os dois juntos.
due_date=none seleciona tarefas que não têm data limite. Nenhum intervalo consegue expressar «o campo está vazio», por isso é um parâmetro separado e não um valor mágico do intervalo.

Como «sem data limite» e «data limite em um intervalo» são mutuamente excludentes, combinar due_date=none com qualquer limite retorna 400 validation_error.

Quais erros esperar

Um valor malformado (prioridade desconhecida, id com formato inválido, não-data) → 400 validation_error.
Um id bem formado que não corresponde a nada (tag de outro workspace, status excluído) → não é um erro: simplesmente nenhuma tarefa corresponde e você recebe uma página vazia.
A exceção é project_id: um projeto fora do escopo da sua chave → 404 not_found_error.