Skip to content
ver .md sin procesar

API de Dailybot Plan

Planifica y sigue el trabajo con la API de Dailybot Plan (Beta): proyectos, tableros, tareas y objetivos en una sola API REST, con los conceptos que necesitas antes de tu primera llamada.

Beta

Plan está en beta. Todo lo que está bajo /plan en la aplicación web, los comandos del CLI y de la agent skill para proyectos, objetivos, tableros y tareas, y la API pública /v1/plan/ puede cambiar antes de la disponibilidad general. ¿Quieres probarlo con tu equipo? Escribe a [email protected].

solicitar acceso a la beta

Dailybot Plan es donde un equipo planifica y sigue su trabajo: proyectos, tableros, tareas y objetivos. La app web, el CLI de Dailybot y el agent skill usan la misma API pública bajo https://api.dailybot.com/v1/plan/. No hay una API privada detrás, así que todo lo que puede hacer cualquiera de ellos también lo puede hacer tu integración.

Esta página explica el modelo una sola vez. Todas las demás páginas de Plan enlazan aquí.

Quién puede hacer qué

Todo miembro no invitado autenticado puede usar toda la API de Plan: crear y gestionar objetivos, proyectos, tableros, estados y membresías. Una API key personal actúa como su persona y puede hacer todo lo que esa persona puede hacer, así que la key de un miembro no necesita ningún scope ni un rol de administrador de la organización. Los invitados se rechazan antes del entitlement (403 guest_not_allowed), con una key o una sesión.

La privacidad es la invitación / membresía, no el rol de la organización. Los proyectos y tableros de toda la organización son un espacio compartido. Un contenedor members es 404 (no visible) sin un grant. Invita a una persona o a un equipo para compartir; el último grant en un contenedor privado es 409 last_grant_cannot_be_removed. No hay roles por proyecto (lead/viewer): la membresía es un grant, no una escalera de roles.

Supervisión: los administradores de la organización y los managers de todos los equipos pueden ver todos los proyectos. Un tablero members sigue necesitando un grant explícito.

Las keys de agente y de la organización no tienen una persona detrás: solo ven tableros visibles para la organización y se rechazan (403 insufficient_scope) en los endpoints que requieren una persona. Detalle: Autenticación y scopes para Plan.

Por dónde empezar

Recetas

Comprueba que Plan esté habilitado para tu organización

Plan está en Beta y se habilita por organización. GET /v1/plan/entitlements/ es el único endpoint de Plan que responde aunque tu organización todavía no esté habilitada, así que llámalo primero:

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 con reason: "rollout" significa que tu organización todavía no está en la Beta. Hasta que lo esté, todos los demás endpoints de Plan responden 402 plan_upgrade_required, y es lo esperado. Escribe a [email protected] para unirte.

El modelo: organización, proyecto, tablero, tarea

Organización
└── Proyecto           qué es un conjunto de trabajo (salud, notas de estado, hitos)
    └── Tablero        dónde se sigue el trabajo; sus columnas son estados del flujo de trabajo
        └── Tarea      una unidad de trabajo, identificada como ENG-142

Un tablero pertenece a un proyecto y una tarea pertenece a un tablero. Las tareas pueden tener subtareas (un solo nivel), relaciones con otras tareas (blocks, relates_to, duplicates), un responsable, participantes, etiquetas, comentarios y adjuntos.

Los estados del flujo de trabajo y sus cinco categorías

Las columnas de un tablero son sus estados del flujo de trabajo. Puedes ponerles el nombre que quieras, pero cada estado tiene una de cinco categorías fijas, y la categoría es la que responde “¿esto está terminado?” en cualquier tablero:

Categoría Significado Cuenta como
backlog Aún no planificada abierta
todo Planificada, sin empezar abierta
in_progress En curso abierta
done Terminada terminada
canceled No se hará terminada

El filtro state acepta dos atajos basados en estas categorías: open (backlog, todo, in_progress) y done (done, canceled). “Bloqueada” no es una categoría: se deriva de las relaciones, así que filtra con blocked=true.

Los objetivos apuntan al trabajo, no lo contienen

Un objetivo dice para qué es el trabajo, con un periodo (period_start, period_end) y un status declarado. Nada vive dentro de un objetivo. Un proyecto puede apuntar a varios objetivos y un objetivo puede estar servido por varios proyectos, así que archivar un objetivo deja cada proyecto donde estaba.

Una tarea puede apuntar a su propio objetivo. Si no lo hace, hereda el objetivo de su proyecto, y los filtros y los cálculos de progreso aplican esa misma regla.

El progreso de un objetivo depende de lo que tú ves: cuenta solo las tareas que puedes ver, y is_partial: true te indica cuándo parte del trabajo del objetivo está oculto para ti. Nunca lo presentes como una cifra de toda la organización.

Identificadores: uuid y KEY-n

Todo objeto tiene un uuid. Una tarea también tiene una clave legible, KEY-n, como ENG-142: ENG es la clave del tablero y 142 es un contador por tablero. Ambos funcionan en cualquier lugar donde se identifique una tarea, por ejemplo GET /v1/plan/tasks/ENG-142/.

La clave de un tablero se puede renombrar y las claves anteriores siguen resolviéndose, así que un enlace escrito el año pasado sigue abriendo la tarjeta. Las claves nunca se reutilizan, ni siquiera después de archivar una tarea o un tablero. Los ids numéricos nunca se aceptan.

Un identificador que no existe y un identificador de otra organización devuelven el mismo cuerpo 404, así que la API nunca revela si algo existe fuera de tu organización.

Orden: mueve en relación con las tarjetas vecinas

Las tarjetas de una columna se ordenan por un rank opaco. Nunca calcules un rank. En su lugar, ubica una tarjeta en relación con sus vecinas: POST /v1/plan/tasks/{task_id}/move/ recibe un state de destino y como máximo uno de after / before (una tarea de esa columna). Si no envías ninguno, la tarjeta queda al final. Si dos personas arrastran la misma tarjeta al mismo tiempo, ambas producen un orden válido.

Mover es la única forma de cambiar el estado de una tarea.

Versiones y ediciones concurrentes

Cada tarea tiene un version entero que aumenta con cada escritura. Para no sobrescribir la edición de otra persona, envía la versión que cargaste en el header If-Match (o en el campo version del cuerpo) cuando actualices una tarea, la muevas o la muevas a otro tablero. Si la tarea cambió mientras tanto, la API responde 409 version_conflict con la versión actual en extra.current_version, para que puedas volver a leerla y decidir.

Sin If-Match, gana la última escritura.

Archivar es la forma de eliminar

Ningún endpoint público elimina de forma definitiva una tarea, un tablero o un proyecto. Archivar es la forma de eliminar, y se puede revertir:

  • Archivar un proyecto archiva en cascada sus tableros y sus tareas; archivar un tablero archiva en cascada sus tareas; archivar una tarea archiva sus subtareas.
  • Restaurar sube por la jerarquía, nunca baja: restaurar un proyecto no restaura los tableros que archivó, porque la API no puede distinguirlos de los tableros archivados a propósito. Restaura cada uno que quieras recuperar.
  • Las tareas, los tableros, los proyectos, los objetivos y los estados del flujo de trabajo tienen cada uno un endpoint …/restore/.
  • Los endpoints DELETE de tareas e hitos son alias que archivan.
  • Los elementos archivados se pueden seguir leyendo: las listas los ocultan salvo que envíes include_archived=true, y una tarea se puede seguir leyendo por clave o uuid.
  • Las claves de tablero siguen reservadas al archivar y al restaurar.

Los endpoints de archivado, la finalización de hitos y las llamadas en lote aceptan ?dry_run=true, que devuelve la consecuencia (incluida una frase para mostrarle a una persona) sin escribir nada.

Menciones

Para mencionar a alguien en un comentario o en una actualización de proyecto, escribe <@DB@{uuid}>, con el uuid de la persona que obtienes de GET /v1/plan/boards/{board_id}/mentionables/:

Se ve bien. <@DB@00000000-0000-4000-8000-00000000000c> ¿puedes revisar el plan de despliegue?

Las respuestas muestran las menciones como texto visible en body y listan a las personas en mentions[]: léelas de ahí, nunca analizando body. Un uuid que no corresponde a nadie de tu organización se elimina del texto. Los comentarios admiten un nivel de hilos mediante parent_comment.

Ignora los valores que no reconozcas

Los tipos de evento, los tipos de relación, las categorías de estado y la lista de eventos de webhook son aditivos: llegan valores nuevos en versiones menores. Un cliente que trate un valor desconocido como un error fallará con una versión que no cambió nada para él. Omite lo que no conozcas.

Qué significa Beta aquí

Las rutas, los campos y el comportamiento descritos en estas páginas pueden cambiar antes de la disponibilidad general; anunciamos los cambios en el changelog de la API. Si falta algo de lo que dependes o no está claro, escribe a [email protected].