API do Dailybot Plan

O Dailybot Plan é onde um time planeja e acompanha o próprio trabalho: projetos, quadros, tarefas e metas. O app web, o CLI do Dailybot e o agent skill usam a mesma API pública em https://api.dailybot.com/v1/plan/. Não existe uma API privada por trás deles, então tudo o que qualquer um deles faz, a sua integração também pode fazer.

Esta página explica o modelo uma única vez. Todas as outras páginas do Plan apontam para cá.

Quem pode fazer o quê

Todo membro não convidado autenticado pode usar toda a API do Plan: criar e gerenciar metas, projetos, quadros, estados e associações. Uma API key pessoal age como sua pessoa e pode fazer tudo o que essa pessoa pode fazer, então a key de um membro não precisa de nenhum scope nem de um papel de administrador da organização. Convidados são recusados antes do entitlement (403 guest_not_allowed), com uma key ou uma sessão.

A privacidade é o convite / a associação, não o papel da organização. Projetos e quadros de toda a organização são um espaço compartilhado. Um contêiner members é 404 (não visível) sem um grant. Convide uma pessoa ou uma equipe para compartilhar; o último grant em um contêiner privado é 409 last_grant_cannot_be_removed. Não há papéis por projeto (lead/viewer) — associação é um grant, não uma escada de papéis.

Supervisão: administradores da organização e managers de todos os times podem ver todos os projetos. Um quadro members ainda precisa de um grant explícito.

Keys de agente e da organização não têm uma pessoa por trás: só veem quadros visíveis para a organização e são recusadas (403 insufficient_scope) nos endpoints que exigem uma pessoa. Detalhe: Autenticação e scopes para o Plan.

Por onde começar

• Conceitos: projetos, metas, quadros, colunas, responsáveis e executores, etiquetas, visões e a caixa de entrada, um parágrafo cada.
• Agentes no Plan: deixe um agente ler um cartão e escrever como uma pessoa, com o agente visível no cartão.
• CLI do Dailybot para o Plan e a agent skill: a linha de comando e o pacote público de skill.
• Início rápido: suas primeiras chamadas em menos de cinco minutos (faça login, liste quadros, crie, mova e comente uma tarefa).
• Referência da API: todos os endpoints, agrupados em Projetos, Metas, Quadros, Tarefas, Comentários e arquivos e Início e busca.
• Autenticação e scopes para o Plan: as três credenciais, o que uma API key pessoal pode fazer, scopes, convidados e a privacidade como associação.
• Convenções para o Plan: paginação, filtros, ordenação, include, limites de requisições, Idempotency-Key, If-Match e 304.
• Erros do Plan: cada código com seu status HTTP, seu significado e o que fazer em seguida, incluindo o 402 durante a Beta.
• Autenticação e Erros: as regras comuns a todas as APIs do Dailybot.

Receitas

• Mostrar um quadro e mantê-lo atualizado: snapshot, feed de mudanças e consultas no ritmo do servidor.
• Montar uma tela inicial em uma requisição: o pulse da tela inicial e suas faixas.
• Criar tarefas a partir de uma lista: criação em lote com simulação e idempotência.
• Mover uma tarefa quando um pull request é mesclado: de qualquer CI, pela chave.
• Acompanhar o progresso de uma meta: progresso, projetos e is_partial.
• Reagir a mudanças com webhooks: os 25 eventos e como verificar as entregas.

Confira se o Plan está habilitado para a sua organização

O Plan está em Beta e é habilitado por organização. GET /v1/plan/entitlements/ é o único endpoint do Plan que responde mesmo quando a sua organização ainda não está habilitada, então chame-o primeiro:

curl -sS "https://api.dailybot.com/v1/plan/entitlements/" \
  -H "Authorization: Bearer $DAILYBOT_TOKEN"

{
  "enabled": false,
  "reason": "rollout",
  "boards": { "used": 0, "limit": 3 },
  "projects": { "used": 0, "limit": 1 },
  "labels": { "enabled": true }
}

enabled: false com reason: "rollout" significa que a sua organização ainda não está na Beta. Até entrar, todos os outros endpoints do Plan respondem 402 plan_upgrade_required, e isso é o esperado. Escreva para [email protected] para participar.

O modelo: organização, projeto, quadro, tarefa

Organização
└── Projeto            o que é um conjunto de trabalho (saúde, notas de status, marcos)
    └── Quadro         onde o trabalho é acompanhado; as colunas são estados do fluxo de trabalho
        └── Tarefa     uma unidade de trabalho, identificada como ENG-142

Um quadro pertence a um projeto e uma tarefa pertence a um quadro. As tarefas podem ter subtarefas (um único nível), relações com outras tarefas (blocks, relates_to, duplicates), um responsável, participantes, etiquetas, comentários e anexos.

Os estados do fluxo de trabalho e suas cinco categorias

As colunas de um quadro são os seus estados do fluxo de trabalho. Você pode dar a eles o nome que quiser, mas cada estado tem uma de cinco categorias fixas, e é a categoria que responde “isto está concluído?” em qualquer quadro:

Categoria	Significado	Conta como
backlog	Ainda não planejada	aberta
todo	Planejada, não iniciada	aberta
in_progress	Em andamento	aberta
done	Concluída	concluída
canceled	Não será feita	concluída

O filtro state aceita dois atalhos baseados nessas categorias: open (backlog, todo, in_progress) e done (done, canceled). “Bloqueada” não é uma categoria: é derivada das relações, então filtre com blocked=true.

As metas apontam para o trabalho, não o contêm

Uma meta diz para que serve o trabalho, com um período (period_start, period_end) e um status declarado. Nada fica dentro de uma meta. Um projeto pode apontar para várias metas e uma meta pode ser atendida por vários projetos, então arquivar uma meta mantém cada projeto onde estava.

Uma tarefa pode apontar para a própria meta. Quando não aponta, herda a meta do projeto, e os filtros e os cálculos de progresso aplicam essa mesma regra.

O progresso de uma meta depende do que você vê: ele conta apenas as tarefas que você pode ver, e is_partial: true indica quando parte do trabalho da meta está oculta para você. Nunca apresente esse número como se valesse para a organização inteira.

Identificadores: uuid e KEY-n

Todo objeto tem um uuid. Uma tarefa também tem uma chave legível, KEY-n, como ENG-142: ENG é a chave do quadro e 142 é um contador por quadro. Os dois funcionam em qualquer lugar onde uma tarefa é identificada, por exemplo GET /v1/plan/tasks/ENG-142/.

A chave de um quadro pode ser renomeada e as chaves antigas continuam sendo resolvidas, então um link escrito no ano passado ainda abre o cartão. As chaves nunca são reutilizadas, nem depois que uma tarefa ou um quadro é arquivado. Ids numéricos nunca são aceitos.

Um identificador que não existe e um identificador de outra organização retornam o mesmo corpo 404, então a API nunca revela se algo existe fora da sua organização.

Ordenação: mova em relação aos cartões vizinhos

Os cartões de uma coluna são ordenados por um rank opaco. Nunca calcule um rank. Em vez disso, posicione um cartão em relação aos vizinhos: POST /v1/plan/tasks/{task_id}/move/ recebe um state de destino e no máximo um entre after / before (uma tarefa dessa coluna). Se você não enviar nenhum dos dois, o cartão vai para o final. Se duas pessoas arrastarem o mesmo cartão ao mesmo tempo, as duas produzem uma ordem válida.

Mover é a única forma de mudar o estado de uma tarefa.

Versões e edições simultâneas

Toda tarefa tem um version inteiro que aumenta a cada escrita. Para não sobrescrever a edição de outra pessoa, envie a versão que você carregou no header If-Match (ou no campo version do corpo) ao atualizar uma tarefa, movê-la ou movê-la para outro quadro. Se a tarefa mudou nesse meio-tempo, a API responde 409 version_conflict com a versão atual em extra.current_version, para que você leia de novo e decida.

Sem If-Match, vale a última escrita.

Arquivar é a exclusão

Nenhum endpoint público exclui de forma definitiva uma tarefa, um quadro ou um projeto. Arquivar é a exclusão, e dá para reverter:

• Arquivar um projeto arquiva em cascata os quadros e as tarefas dele; arquivar um quadro arquiva em cascata as tarefas; arquivar uma tarefa arquiva as subtarefas.
• Restaurar sobe na hierarquia, nunca desce: restaurar um projeto não restaura os quadros que ele arquivou, porque a API não consegue diferenciá-los de quadros arquivados de propósito. Restaure cada um que você quiser de volta.
• Tarefas, quadros, projetos, metas e estados do fluxo de trabalho têm, cada um, um endpoint …/restore/.
• Os endpoints DELETE de tarefas e marcos são aliases que arquivam.
• Itens arquivados continuam legíveis: as listas os ocultam, a menos que você envie include_archived=true, e uma tarefa continua legível pela chave ou pelo uuid.
• As chaves de quadro continuam reservadas ao arquivar e ao restaurar.

Os endpoints de arquivamento, a conclusão de marcos e as chamadas em lote aceitam ?dry_run=true, que retorna a consequência (incluindo uma frase para mostrar a uma pessoa) sem gravar nada.

Menções

Para mencionar alguém em um comentário ou em uma atualização de projeto, escreva <@DB@{uuid}>, usando o uuid da pessoa obtido em GET /v1/plan/boards/{board_id}/mentionables/:

Está bom. <@DB@00000000-0000-4000-8000-00000000000c> você pode revisar o plano de rollout?

As respostas exibem as menções como texto legível em body e listam as pessoas em mentions[]: leia-as dali, nunca analisando body. Um uuid que não corresponde a ninguém da sua organização é removido do texto. Os comentários aceitam um nível de conversa em thread por meio de parent_comment.

Ignore os valores que você não reconhecer

Tipos de evento, tipos de relação, categorias de estado e a lista de eventos de webhook são aditivos: valores novos chegam em versões menores. Um cliente que trate um valor desconhecido como erro vai quebrar em uma versão que não mudou nada para ele. Ignore o que você não conhece.

O que Beta significa aqui

Caminhos, campos e comportamentos descritos nestas páginas podem mudar antes da disponibilidade geral; anunciamos as mudanças no changelog da API. Se faltar algo de que você depende ou se algo não estiver claro, escreva para [email protected].