API REST

aqua y Bandeja de entrada

La IA de tracker, los créditos, las revisiones y la Bandeja de entrada.

GET /aqua (tracker:read): si aqua (el asistente de IA) está activada en la empresa, {"available": true, "reason": null, "can_review": true} (reason: disabled o no_key; can_review: la persona edita issues en algún proyecto y ve la pantalla aqua, GET /aqua/recommendations). POST /aqua (tracker:read): la conversación de ayuda de la app, {"messages": [{"role": "user", "content": "¿Cómo creo una issue?"}], "path": "/issues", "app": "ios"} (hasta 20 mensajes, empezando y terminando con user y alternando; app: ios o mac, opcional). aqua responde dudas de uso y también sobre los datos: consulta, solo para leer y como la persona del token, lo que esa persona ve en la empresa (sus tareas y las que sigue, proyectos, sprints, releases, pruebas, personas, horas, bandeja de entrada, Chats, documentos, ideas y estado), con las mismas consultas de lectura del MCP; no cambia nada. También abre los adjuntos de las tareas y de los comentarios cuando la pregunta lo pide: ve las capturas (png, jpg y webp hasta 3,7 MB) y los PDF (hasta 10 MB) y lee los textos (md, csv, txt, log y json), hasta 4 imágenes o PDF por pregunta; video no. aqua también propone cambios cuando la persona lo pide (crear una tarea, editar o asignar, comentar, cambiar el estado, bloquear, seguir, planificar, registrar horas, vincular tareas), pero la pregunta no guarda nada: cada propuesta vuelve en actions para que la persona la confirme. Los enlaces de la respuesta son direcciones de la app (/issues/MOB-0012?org=...). Cuando la pregunta trata de una tarea o de un proyecto, manda en path la pantalla abierta (/issues/MOB-0012, /projects/mobilidade): aqua entiende "esta tarea". Una pregunta que consulta los datos tarda un poco más y cuenta como un uso de IA. aqua responde en el idioma de la persona del token (el locale de GET /me; en Automático, el Accept-Language del pedido), y en el mismo idioma vienen title, details y result de las acciones y los textos de status. Toda conversación queda guardada: manda conversation_id (devuelto en la primera respuesta) para seguir la misma; sin él, una conversación nueva (o la reciente que tiene exactamente los mismos mensajes). Devuelve {"answer": "...", "conversation_id": "...", "actions": [...]}, cada acción con id, tool (la tool del MCP que ejecuta), input, title (la frase de la tarjeta, escrita por tracker), details, state (pending, running, done, cancelled o failed), result (text y url, una vez hecha) y error. Con "stream": true, la respuesta llega de a poco en NDJSON (application/x-ndjson, un JSON por línea): {"type": "status", "text": "Consultando las tareas…"} mientras consulta (el texto recibido antes de un status ya no vale), {"type": "text", "text": "..."} con cada parte de la respuesta, {"type": "ping"} para mantener la conexión y, al final, {"type": "done", ...} con el mismo JSON que sin stream (la respuesta que vale) o {"type": "error", "message": "..."}; el estado HTTP es 200 incluso con error. POST /aqua/conversations/{id}/actions/{action} (tracker:write) con {"decision": "confirm"} hace el cambio con el perfil de la persona del token (o "cancel" lo descarta) y devuelve {"action": ...}; la misma acción no se ejecuta dos veces (422 cuando ya se decidió). GET /aqua/conversations (tracker:read, ?limit= hasta 50) lista las conversaciones de la persona (id, title, messages, created_at, updated_at; quedan las 50 más recientes), GET /aqua/conversations/{id} trae los mensajes (role, content, at, actions) y DELETE /aqua/conversations/{id} (tracker:write) la borra. En el MCP: list_aqua_conversations y get_aqua_conversation. 422 cuando la IA se niega o está desactivada, sin clave o en el límite.
GET /aqua/credits (tracker:read): los créditos de IA de la empresa. Sin clave propia, aqua usa la clave de tracker y gasta créditos de un paquete por ciclo de 30 días (el del plan de la empresa), que se renueva solo; con la clave propia de la empresa, no gasta. Devuelve available, reason, key_source (server: créditos; organization: clave propia; null sin IA), credits (null con la clave propia): state (ok, low con 20% o menos, empty cuando se acabaron y aqua se pausa hasta renovar, expired), remaining, used, total (per_cycle más granted, los créditos que el equipo de la plataforma agregó en el ciclo), cycle_days, cycle_start, cycle_end, auto_renew y renews_at; y usage (solo admins y dueños, null para los demás): since (el inicio del ciclo; con la clave propia, 30 días atrás) y by_action, de las acciones más usadas a las menos (action, label, calls, failures, credits). Siempre en créditos, nunca en dinero. Cuando una llamada de IA vuelve 422 por falta de créditos, el mensaje dice cuándo se renuevan. En el MCP: get_ai_credits. La clave propia de la empresa (solo de Claude) se pone, cambia y quita solo en la pantalla, en Empresa → Integraciones → Asistente de IA (admins y dueños): ni la API ni el MCP leen o guardan la clave.
Bandeja de entrada (la de la pantalla /inbox): GET /inbox (tracker:read, ?view=unread solo las no leídas o ?view=hidden las ocultas; sin él, las no ocultas; ?before=<id> pagina, ?limit= hasta 100) trae unread e items, los comentarios que llegaron a la persona del token, los más recientes primero: kind (mention: alguien escribió @su nombre; reply: respuesta en una conversación en la que escribió), own_thread (la conversación empezó con un comentario suyo), id (del comentario), text, author, excerpt, issue (id, code, title, project), url, at, read y hidden. Escribir en la tarea después del comentario, abrir la tarea o leer su notificación también cuentan como leída. Las menciones y las respuestas en los hilos de los Chats vienen aparte, en chat_items (con chat_unread): id (de la notificación), kind (mention o reply, respuesta en un hilo en el que está), own_thread (el hilo empezó con un mensaje suyo), thread (vino de un hilo), text, author, excerpt (el fragmento del mensaje), project, url (directo al mensaje), at, read y hidden; abrir el hilo o leer el canal cuenta como leída. POST /inbox (tracker:read) cambia el estado (de los ids de items y de chat_items): {"action": "read", "ids": [...]} o {"action": "read", "all": true}, {"action": "hide", "ids": [...]} o {"action": "hide", "older_than_days": 30} (ocultar cuenta como leída) y {"action": "unhide", "ids": [...]}; devuelve updated, unread y chat_unread. Resumen de aqua del día y del mes (el de arriba de la bandeja): GET /aqua/summary (tracker:read, ?period=day, el de por defecto, o month, en la zona horaria de Brasilia) devuelve available, reason, period y summary (null antes de pedirlo): headline, highlights (lo que pasó en las tareas de la persona y en las que sigue), attention (lo que pide su atención), issues (las citadas, con code, id y url), generated_at y outdated (llegaron novedades después). POST /aqua/summary (tracker:read) con {"period": "month"} pide uno nuevo, escrito en el idioma de la persona del token (gasta créditos de IA; un período sin nada no gasta); 422 con la IA desactivada, sin clave o sin créditos. En el MCP: list_inbox, update_inbox y get_aqua_summary.
aqua en las issues (la misma de la pantalla): GET /issues/{ref}/aqua (tracker:read) trae available, can_review (si la persona puede pedir la revisión), summary (como aqua_summary de GET /issues/{ref}), review (summary, reviewed_at, outdated), las recommendations abiertas (id, kind: comment, status, field, custom_field, label, duplicate o move; title, before, after, reason y comment, el texto del pedido de información) y snooze_options. POST /issues/{ref}/aqua/summary (tracker:read) resume la conversación (a partir de summary_min_comments comentarios) y devuelve {"summary": ...}. POST /issues/{ref}/aqua/review (tracker:write, quien edita la issue) la revisa y devuelve lo mismo que el GET. La revisión (esta, la en lote y la diaria) lee también los adjuntos de la issue y de los comentarios: hasta 3 capturas, 1 PDF (hasta 5 MB) y el texto de hasta 2 archivos de texto o log, los más nuevos primero; video no. El costo de leer entra en los créditos como el resto de la revisión. POST /aqua/recommendations/{id}/apply (tracker:write) aplica la sugerencia ({"comment": "..."} opcional cambia el texto del pedido de información); POST /aqua/recommendations/{id}/dismiss (tracker:write) con {"for": "7"} (1, 7, 30 días o forever) la ignora. La pantalla aqua entera: GET /aqua/recommendations (tracker:read, ?project=MOB opcional) trae available, reason, can_review, daily_review (enabled, hour, limit, last_on, last_count, last_error), sentry_waiting (errores de Sentry esperando decisión, en GET /sentry/errors?waiting=true), total e issues, las issues con sugerencias abiertas (de las paradas hace más tiempo a las recientes), cada una con id, code, title, project, status (name, color, category), summary, reviewed_at, outdated y recommendations (como arriba), y snooze_options. "Revisar issues abiertas" corre en el servidor: POST /aqua/review-runs (tracker:write, {"project": "MOB"} opcional) empieza la revisión de todas las issues abiertas que aqua todavía no vio o que cambiaron desde la revisión (hasta 500, una a la vez; una revisión a la vez por empresa, y pedirla de nuevo devuelve la que ya corre) y devuelve {"run": ...} (null sin nada pendiente); GET /aqua/review-runs (tracker:read) trae la que corre o la última, GET /aqua/review-runs/{id} el avance (status: running, done, stopped o failed; total, reviewed, failed, suggestions, error, created_at, finished_at e issues, cada una con id, code, title, state — waiting, running, done o failed —, suggestions y error) y POST /aqua/review-runs/{id}/stop (tracker:write) la detiene. GET /aqua/review-queue (tracker:read, ?project= y ?limit= hasta 25) sigue devolviendo la cola (id, code, title) para revisar una por una con POST /issues/{ref}/aqua/review y {"batch": true} (el modelo de la revisión en lote). En el MCP: list_aqua_recommendations, start_aqua_review, get_aqua_review, stop_aqua_review, list_issues_to_review, review_issue_with_aqua, apply_aqua_recommendation y dismiss_aqua_recommendation. POST /aqua/draft (tracker:read) con {"text": "relato libre", "project": "MOB"} (project opcional) devuelve los campos de POST /issues completados y missing (lo que el relato no dice), en el idioma del relato, sin crear nada. POST /aqua/improve (tracker:read) con {"project": "MOB", "type": "bug", "title": "...", "description": "..."} (y los demás textos del formulario) devuelve título y textos reescritos y notes, sin guardar. 422 cuando la IA está desactivada, sin clave o en el límite.