Tarefas

Tarefas pertencem a um projeto e podem ser organizadas em colunas de um pipeline. A API usa assignee_ids como formato preferido para responsáveis e mantém assignee_id por compatibilidade.

GET /tasks

Lista somente tarefas cujo deleted_at é null no time autenticado.

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
`page`	number	`1`	Página atual.
`limit`	number	`20`	Itens por página, até `100`.
`project_id`	uuid	—	Filtra pelo projeto.
`pipeline_id`	uuid	—	Filtra pelo pipeline.
`assignee_id`	uuid	—	Filtra tarefas que contêm o responsável em `assignee_ids`.
`priority`	string	—	`urgent`, `high`, `medium`, `low` ou `none`.
`column`	string	—	Filtra pelo slug da coluna.
`search`	string	—	Busca em `title` e `description`.
`sort`	string	`-created_at`	Campo de ordenação; use `-` para ordem decrescente.

Os campos aceitos em sort são title, priority, due_date, position, created_at, updated_at e completed_at.

curl -X GET "https://app.usecolmeia.com/api/v1/tasks?project_id=660e8400-e29b-41d4-a716-446655440002&priority=high" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Resposta

{
  "success": true,
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440003",
      "title": "Validar briefing de implantação",
      "description": "Confirmar os requisitos antes do início.",
      "project_id": "660e8400-e29b-41d4-a716-446655440002",
      "pipeline_id": "990e8400-e29b-41d4-a716-446655440005",
      "column": "em-andamento",
      "priority": "high",
      "assignee_id": "880e8400-e29b-41d4-a716-446655440004",
      "assignee_ids": ["880e8400-e29b-41d4-a716-446655440004"],
      "reporter_id": null,
      "due_date": "2026-08-20",
      "estimated_hours": 2.5,
      "actual_hours": null,
      "position": 1,
      "tags": ["implantacao"],
      "checklist_markdown": null,
      "completed_at": null,
      "created_at": "2026-08-11T10:30:00Z",
      "updated_at": "2026-08-11T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Cria uma tarefa. title e project_id são obrigatórios. Quando pipeline_id é omitido, a API usa o pipeline padrão do projeto; quando a coluna é omitida, usa a primeira coluna desse pipeline. Se não houver coluna resolvida, usa backlog.

Campo	Tipo	Obrigatório	Descrição
`title`	string	Sim	Título da tarefa.
`project_id`	uuid	Sim	Projeto ao qual a tarefa pertence.
`description`	string	Não	Detalhes da tarefa.
`pipeline_id`	uuid	Não	Pipeline da tarefa.
`column` ou `column_slug`	string	Não	Slug da coluna.
`priority`	string	Não	`urgent`, `high`, `medium`, `low` ou `none`. O padrão é `none`.
`assignee_ids`	uuid[]	Não	Lista de responsáveis; formato preferido.
`assignee_id`	uuid	Não	Responsável único para compatibilidade.
`reporter_id`	uuid	Não	Pessoa que reportou a tarefa.
`due_date`	date	Não	Data no formato `YYYY-MM-DD`.
`estimated_hours`	number	Não	Estimativa em horas.
`tags`	string[]	Não	Tags da tarefa.
`checklist_markdown`	string	Não	Checklist em Markdown.

curl -X POST https://app.usecolmeia.com/api/v1/tasks \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "660e8400-e29b-41d4-a716-446655440002",
    "title": "Validar briefing de implantação",
    "priority": "high",
    "assignee_ids": ["880e8400-e29b-41d4-a716-446655440004"],
    "estimated_hours": 2.5
  }'

A criação retorna 201. Se o projeto não pertencer ao time autenticado, retorna 404 NOT_FOUND.

GET /tasks/:id

Retorna uma tarefa ativa do time autenticado. Tarefas excluídas logicamente retornam 404.

curl -X GET https://app.usecolmeia.com/api/v1/tasks/770e8400-e29b-41d4-a716-446655440003 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

PUT /tasks/:id

Atualiza uma tarefa ativa. project_id não é atualizável. Envie ao menos um dos campos aceitos.

Campo atualizável	Tipo
`title`	string
`description`, `checklist_markdown`	string ou `null`
`due_date`, `completed_at`	data ou data/hora ISO 8601, conforme o campo
`pipeline_id`	uuid ou `null`
`column` ou `column_slug`	string
`priority`	`urgent`, `high`, `medium`, `low` ou `none`
`assignee_ids`	uuid[]; atualiza também `assignee_id` com o primeiro valor
`assignee_id`	uuid ou `null`; mantido por compatibilidade
`reporter_id`	uuid ou `null`
`estimated_hours`, `actual_hours`	number ou `null`
`position`	number
`tags`	string[]

curl -X PUT https://app.usecolmeia.com/api/v1/tasks/770e8400-e29b-41d4-a716-446655440003 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "column": "concluido",
    "completed_at": "2026-08-20T15:00:00Z",
    "actual_hours": 2
  }'

DELETE /tasks/:id

Exclui logicamente uma tarefa ativa ao preencher deleted_at. A tarefa deixa de aparecer em GET /tasks e em GET /tasks/:id.

curl -X DELETE https://app.usecolmeia.com/api/v1/tasks/770e8400-e29b-41d4-a716-446655440003 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Resposta

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440003",
    "deleted_at": "2026-08-20T16:00:00Z"
  }
}

A API não oferece restauração de tarefas excluídas. Use o painel para restaurá-las, quando disponível para o seu fluxo.

Erros comuns

Status	Código	Causa
`400`	`VALIDATION_ERROR`	Corpo inválido, `title` ou `project_id` ausente, prioridade inválida ou nenhum campo para atualizar.
`404`	`NOT_FOUND`	Projeto ou tarefa não encontrado no time, ou tarefa já excluída.

Tarefas

Tarefas

GET /tasks

Parâmetros de consulta

Resposta

POST /tasks

GET /tasks/:id

PUT /tasks/:id

DELETE /tasks/:id

Resposta

Erros comuns

On this page