API v1 · plano Pro

API do Tareflo

Leia e escreva tarefas, quadros e etiquetas do seu espaço a partir de qualquer sistema — ou de um agente de IA.

Começar

01Abra Configurações → Espaço → Chaves de API e gere uma chave.
02Confirme o contexto dela chamando /me.
03Faça a primeira chamada de verdade.

curl https://www.tareflo.com.br/api/v1/me \
  -H "Authorization: Bearer tfl_sua_chave"

Autenticação

Toda requisição leva a chave no cabeçalho Authorization. O Bearer é opcional.

A chave age como você, num espaço só.

Ela nunca pode mais do que você pode pela tela: seu papel, a regra de edição de tarefa alheia do espaço e a visibilidade de quadro privado valem igual. Se você for rebaixado ou sair do espaço, a chave para de funcionar junto.

Leitura

Consulta tarefas, quadros e etiquetas. Não altera nada.

Escrita

Tudo da leitura, mais criar, editar, mover e excluir — dentro do que seu papel permite.

O segredo aparece uma única vez, na criação. Guardamos apenas um resumo criptográfico — nem o suporte recupera a chave depois. Perdeu, gere outra.

Formato das respostas

Sucesso vem em data. Listas trazem meta com a paginação. Erro vem em error — programe em cima do code, não da mensagem: o texto pode mudar, o código não.

Sucesso

{
  "data": [ { "id": "…", "title": "…" } ],
  "meta": {
    "page": 1, "perPage": 25,
    "total": 87, "totalPages": 4
  }
}

Erro

{
  "error": {
    "code": "todo.not_editable",
    "message": "…"
  }
}

Convenções: camelCase, datas em ISO 8601 UTC, dueDate como data pura (YYYY-MM-DD) e null explícito em vez de campo ausente.

Contexto

Base: https://www.tareflo.com.br/api/v1

GET/me

Confirma a chave e diz onde ela opera.

Chame este primeiro. Ele responde qual espaço a chave alcança, com que papel e com que permissão — o que evita descobrir por tentativa e erro qual chamada vai dar 403.

Resposta

{
  "data": {
    "user":  { "id": "…", "name": "João", "email": "joao@…" },
    "space": { "id": "…", "name": "Produto", "taskEditPolicy": "EVERYONE" },
    "role":  "ADMIN",
    "token": { "name": "n8n", "scope": "WRITE" },
    "plan":  { "name": "Pro" }
  }
}

Tarefas

Base: https://www.tareflo.com.br/api/v1

GET/tasks

Lista as tarefas do espaço, paginadas.

status: `open` ou `completed`. Omitido, traz as duas.
priority: `LOW`, `MEDIUM`, `HIGH` ou `URGENT`.
assigneeId: Filtra por responsável.
tagId: Filtra por etiqueta.
flowId: Só as que estão neste quadro.
search: Busca no título e na descrição.
archived: `true` traz as arquivadas. Padrão: `false`.
page / perPage: Paginação. `perPage` vai até 100.

Resposta

{
  "data": [ { "id": "…", "title": "Revisar contrato", … } ],
  "meta": { "page": 1, "perPage": 25, "total": 87, "totalPages": 4 }
}

POST/tasksescrita

Cria uma tarefa.

Sem `assigneeId`, a tarefa fica com o dono da chave. O limite de tarefas do plano vale aqui igual à tela.

Corpo

{
  "title": "Revisar contrato",
  "description": "Cláusula 4 pendente",
  "priority": "HIGH",
  "dueDate": "2026-09-30",
  "assigneeId": "…",
  "tagIds": ["…"]
}

GET/tasks/{id}

Uma tarefa.

PATCH/tasks/{id}escrita

Altera uma tarefa.

Aceita `title`, `description`, `completed`, `archived`, `priority`, `dueDate`, `dueAt`, `startDate`, `assigneeId` e `tagIds`. `tagIds` é a lista COMPLETA: ausente não mexe nas etiquetas, `[]` remove todas.

Corpo

{ "completed": true }

DELETE/tasks/{id}escrita

Exclui a tarefa e os anexos dela.

Quadros (kanban)

Base: https://www.tareflo.com.br/api/v1

GET/flows

Fluxos que você enxerga, com as colunas.

Fluxo privado de outra pessoa não aparece — a chave enxerga exatamente o que você enxerga na tela.

GET/flows/{id}

Um fluxo, com as colunas na ordem do quadro.

GET/flows/{id}/tasks

Cartões do quadro, na ordem das colunas.

POST/flows/{id}/tasksescrita

Põe no quadro uma tarefa que já existe.

Uma tarefa vive em um fluxo só.

Corpo

{ "taskId": "…", "columnId": "…" }

Resposta

{ "data": { "cardId": "…", "task": { … } } }

PATCH/flow-tasks/{cardId}escrita

Move o cartão de coluna.

Cair numa coluna de conclusão marca a tarefa como concluída, igual ao arrasto na tela. Use o `cardId`, não o id da tarefa.

Corpo

{ "columnId": "…" }

DELETE/flow-tasks/{cardId}escrita

Tira do quadro. A tarefa continua existindo.

Etiquetas e pessoas

Base: https://www.tareflo.com.br/api/v1

GET/tags

Etiquetas do espaço.

POST/tagsescritaGestor+

Cria uma etiqueta.

Corpo

{ "name": "Urgente", "color": "#EF4444" }

GET/members

Membros do espaço.

Use para descobrir o `assigneeId` antes de atribuir uma tarefa a alguém.

Campos da tarefa

Campo	Tipo	Nota
id	string	Identificador da tarefa.
title	string	Título.
description	string \| null	Texto livre.
completed	boolean	Concluída.
archived	boolean	Arquivada.
priority	string	LOW, MEDIUM, HIGH ou URGENT. Sem informar, nasce MEDIUM.
dueDate	string \| null	O DIA do vencimento, em data pura (YYYY-MM-DD).
dueAt	string \| null	O INSTANTE, só quando há hora marcada. Ao enviar, use ISO 8601 com fuso (2026-09-01T23:00:00-03:00): é dele que sai o dia.
startDate	string \| null	Início planejado, data pura. Não pode ser depois do vencimento.
assignee	objeto \| null	Responsável: id, name, email.
creator	objeto \| null	Quem abriu a tarefa.
tags	array	Etiquetas aplicadas.
flow	objeto \| null	Onde está no quadro, se estiver. Traz columnId e columnName.
createdAt	string	ISO 8601 UTC.
updatedAt	string \| null	ISO 8601 UTC.

Erros

HTTP	code	O que fazer
401	api.token_missing	Faltou o cabeçalho Authorization.
401	api.token_invalid	Chave errada, revogada ou expirada.
403	api.token_read_only	A chave é de leitura. Gere uma de escrita.
403	api.unavailable	O espaço saiu do Pro.
403	space.insufficient_role	Seu papel no espaço não permite esta ação.
403	todo.not_editable	A regra do espaço não deixa você mexer em tarefa de outra pessoa.
404	—	Não existe, ou é de outro espaço.
422	validation.failed	Campos inválidos. Veja error.details.
429	rate_limit.exceeded	Passou de 300 requisições no minuto. Reduza o ritmo.

404 cobre “não existe” e “não é seu” de propósito: distinguir os dois confirmaria a existência de itens de outros espaços.

Limites

300 requisições por minuto, por chave — 5 por segundo. Estourar devolve 429. O limite é por chave e não por IP, então um cliente atrás de NAT não derruba o vizinho, e trocar de IP não reinicia a cota.

Não espere o 429

Toda resposta traz a cota em cabeçalhos. Leia X-RateLimit-Remaining e desacelere antes de estourar, em vez de descobrir o limite batendo nele.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 41        # segundos até a janela virar

# No 429, além dos acima:
Retry-After: 41

Os limites do plano continuam valendo: se o espaço estourar a cota de tarefas, criar pela API falha do mesmo jeito que falharia na tela.

Conectar a um assistente de IA (MCP)

O Tareflo tem um servidor MCP pronto. Aponte seu assistente para a URL abaixo com a mesma chave — não há nada para instalar, e ele passa a criar tarefas, consultar o quadro e mover cartões conversando com você.

Endpoint MCP

https://www.tareflo.com.br/api/mcp

Claude Code

claude mcp add --transport http tareflo \
  https://www.tareflo.com.br/api/mcp \
  --header "Authorization: Bearer tfl_sua_chave"

Clientes com mcp.json

{
  "mcpServers": {
    "tareflo": {
      "type": "http",
      "url": "https://www.tareflo.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer tfl_sua_chave"
      }
    }
  }
}

Ferramentas disponíveis

Ferramenta	Faz	Escopo
tareflo_whoami	Diz em qual espaço a conexão opera, com que papel.	leitura
tareflo_list_tasks	Lista tarefas, com filtros e busca por texto.	leitura
tareflo_get_task	Detalhes de uma tarefa.	leitura
tareflo_create_task	Cria uma tarefa.	escrita
tareflo_update_task	Altera, conclui ou arquiva uma tarefa.	escrita
tareflo_delete_task	Exclui uma tarefa em definitivo.	escrita
tareflo_list_flows	Lista os quadros visíveis, com as colunas.	leitura
tareflo_get_flow	Um quadro e suas colunas.	leitura
tareflo_list_flow_cards	Cartões de um quadro, por coluna.	leitura
tareflo_add_task_to_flow	Põe uma tarefa existente no quadro.	escrita
tareflo_move_card	Move o cartão de coluna (muda o andamento).	escrita
tareflo_remove_card	Tira o cartão do quadro, sem excluir a tarefa.	escrita
tareflo_list_tags	Etiquetas do espaço.	leitura
tareflo_create_tag	Cria uma etiqueta (requer Gestor).	escrita
tareflo_list_members	Pessoas do espaço, para atribuir tarefas.	leitura

Comece com uma chave de leitura.

Com escopo de leitura o assistente nem enxerga as ferramentas que alteram dados — não é que ele tenta e falha, é que elas não existem para ele. É a diferença entre um agente errar um resumo e um agente apagar tarefas do time. Passe para escrita quando confiar no fluxo.

A conexão MCP obedece exatamente às mesmas regras da API: age no espaço da chave, com o seu papel, e respeita a regra de edição de tarefa alheia do espaço. Tudo que o agente fizer aparece no feed de atividades marcado como vindo de IA.

Pronto para gerar sua chave?

A API faz parte do plano Pro. Gere em Configurações → Espaço.

Minhas chaves