docs

API REST e chaves

Use a API REST do fazer.ai projects para integrar scripts, fluxos do n8n ou seu próprio back-end por HTTP. A API usa JSON e fica em https://projects.fazer.ai/api/v1. Ela cobre as operações da tela com tarefas, projetos, comentários, labels, status, lembretes, revisões, anexos e notificações. As mesmas regras valem na tela, na API e no MCP. Toda chamada à API é feita por um agente. Ele tem acesso ao que a pessoa dona do agente pode ver, e as alterações ficam registradas em nome do agente.

A chave

Em Configurações, abra Agentes e escolha o agente que vai usar a API. Você também pode criar um agente para a integração, por exemplo, n8n. Clique em Criar chave, selecione os escopos e, se quiser, defina uma data de expiração. A chave pertence ao agente e começa com fzp_. Ela aparece uma única vez, quando você a cria. Guarde o valor em um gerenciador de senhas.

  • read permite consultar tarefas, projetos e pessoas.
  • write permite criar e alterar dados.
  • admin está disponível apenas para quem é dono ou admin da organização. Uma chave com esse escopo expira em no máximo 7 dias.

A criação, a listagem e a revogação de chaves são feitas apenas pela tela. Isso vale também para a própria chave que autentica uma integração. Para cortar o acesso de uma chave, volte a Configurações, abra Agentes e clique em Revogar na chave. A revogação tem efeito imediato.

Autenticação

Envie a chave no cabeçalho Authorization: Bearer <chave> e use GET /api/v1/me para testar o acesso.

curl https://projects.fazer.ai/api/v1/me \
  -H "Authorization: Bearer $PROJECTS_TOKEN"

A resposta identifica o agente associado à chave. Os IDs nas respostas da API vêm como texto. Se a chave estiver revogada, expirada ou for inexistente, a API retorna 401 com o mesmo corpo de erro nos três casos. Se a chave for válida e faltar o escopo exigido pela operação, o retorno é 403. As respostas de erro seguem o formato { "error": "mensagem" }.

Limites

Cada chave de API tem um limite de 600 requisições por minuto. No SaaS, também se aplica um limite de 500 requisições por minuto por pessoa. Esse total soma o tráfego de todas as chaves de API e conexões MCP dos agentes que pertencem à pessoa. Se você exceder um dos limites, a API responde 429. O cabeçalho Retry-After indica quantos segundos esperar para tentar de novo. No limite por pessoa, o corpo da resposta também informa esse intervalo em retryAfterSeconds.

Escritas idempotentes

Inclua o cabeçalho Idempotency-Key em uma escrita que você pode precisar repetir. Se um timeout ou uma queda de rede impedir que você receba a resposta, envie a mesma requisição com o mesmo valor no cabeçalho. O valor deve ter de 1 a 128 caracteres e vale por 24 horas. Cada chave de API tem seu próprio espaço de chaves de idempotência. No exemplo, dueAt usa amanhã. A API interpreta hoje, amanhã, today e tomorrow no calendário de quem chama. Ela também aceita um instante ISO com fuso ou uma data no formato YYYY-MM-DD para um dia inteiro.

IDEMPOTENCY_KEY=$(uuidgen)   # guarde para repetir a mesma escrita
curl https://projects.fazer.ai/api/v1/tasks \
  -H "Authorization: Bearer $PROJECTS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"title": "Enviar o relatório", "dueAt": "amanhã"}'
CasoResposta
Primeira chamada com essa chave de idempotênciaResposta normal da operação.
Mesma chave, mesmo método, caminho e corpoResposta da primeira chamada, com Idempotent-Replayed: true, sem gravar de novo.
Mesma chave, requisição diferente422.
Mesma chave, primeira chamada ainda em execução409.

Sincronizar com /changes

Para manter uma integração sincronizada sem consultar periodicamente cada lista, leia o feed de /changes. Ele reúne as mudanças que o agente tem permissão para ver. Passe o cursor em since e use since=0 para ler desde o começo. O parâmetro limit define quantas mudanças pedir por página. O padrão é 100 e o máximo é 500. Para acompanhar um tipo de entidade, passe entityType com um valor como TASK ou PROJECT.

curl "https://projects.fazer.ai/api/v1/changes?since=0&limit=100" \
  -H "Authorization: Bearer $PROJECTS_TOKEN"

Guarde o nextCursor de toda resposta, inclusive de uma página vazia, e envie esse valor em since na próxima chamada. Uma página vazia pode avançar o cursor, quando houve mudanças que o agente não pode ver, e nunca o leva de volta ao zero. O feed só inclui mudanças feitas há pelo menos 2 segundos, para evitar que alguma fique para trás quando o cursor avança. Por isso, uma alteração aparece no feed alguns segundos depois de acontecer.

Referência completa

Abra Referência da API no menu desta documentação para consultar os detalhes da operação que você quer chamar. Cada operação tem uma página com os parâmetros que aceita e as respostas que pode retornar.

On this page