API REST

aqua e Caixa de entrada

A IA do tracker, os créditos, as revisões e a Caixa de entrada.

  • GET /aqua (tracker:read): se a aqua (assistente de IA) está ligada na empresa, {"available": true, "reason": null, "can_review": true} (reason: disabled ou no_key; can_review: a pessoa edita issues em algum projeto e vê a tela aqua, GET /aqua/recommendations). POST /aqua (tracker:read): a conversa de ajuda do app, {"messages": [{"role": "user", "content": "Como crio uma issue?"}], "path": "/issues", "app": "ios"} (até 20 mensagens, começando e terminando com user e alternando; app: ios ou mac, opcional). Devolve {"answer": "..."}; 422 quando a IA recusa ou está desligada, sem chave ou no limite.
  • GET /aqua/credits (tracker:read): os créditos de IA da empresa. Sem chave própria, a aqua usa a chave do tracker e gasta créditos de um pacote por ciclo de 30 dias, que renova sozinho; com a chave própria da empresa, não gasta. Devolve available, reason, key_source (server: créditos; organization: chave própria; null sem IA), credits (null com a chave própria): state (ok, low com 20% ou menos, empty quando acabou e a aqua pausa até renovar, expired), remaining, used, total (per_cycle mais granted, os créditos lançados pela equipe da plataforma no ciclo), cycle_days, cycle_start, cycle_end, auto_renew e renews_at; e usage (só admin e dono, null para os demais): since (o início do ciclo; com a chave própria, 30 dias atrás) e by_action, das ações mais usadas para as menos (action, label, calls, failures, credits). Sempre em créditos, nunca em dinheiro. Quando uma chamada de IA volta 422 por falta de créditos, a mensagem diz quando renova. No MCP: get_ai_credits. A chave própria da empresa (só da Claude) se põe, troca e tira só na tela, em Empresa → Integrações → Assistente de IA (admin e dono): nem a API nem o MCP leem ou gravam a chave.
  • Caixa de entrada (a da tela /inbox): GET /inbox (tracker:read, ?view=unread só as não lidas ou ?view=hidden as ocultadas; sem ele, as não ocultadas; ?before=<id> pagina, ?limit= até 100) traz unread e items, os comentários que chegaram para a pessoa do token, os mais recentes primeiro: kind (mention: alguém escreveu @o nome dela; reply: resposta numa conversa em que ela escreveu), own_thread (a conversa começou com um comentário dela), id (do comentário), text, author, excerpt, issue (id, code, title, project), url, at, read e hidden. Escrever na tarefa depois do comentário, abrir a tarefa ou ler a notificação dele também contam como lida. As menções e as respostas nas threads das Conversas vêm à parte, em chat_items (com chat_unread): id (da notificação), kind (mention ou reply, resposta numa thread em que ela está), own_thread (a thread começou com uma mensagem dela), thread (veio de uma thread), text, author, excerpt (o trecho da mensagem), project, url (direto à mensagem), at, read e hidden; abrir a thread ou ler o canal conta como lida. POST /inbox (tracker:read) muda o estado (dos ids de items e de chat_items): {"action": "read", "ids": [...]} ou {"action": "read", "all": true}, {"action": "hide", "ids": [...]} ou {"action": "hide", "older_than_days": 30} (ocultar conta como lida) e {"action": "unhide", "ids": [...]}; devolve updated, unread e chat_unread. Resumo da aqua do dia e do mês (o do topo da caixa): GET /aqua/summary (tracker:read, ?period=day, o padrão, ou month, no fuso de Brasília) devolve available, reason, period e summary (null antes de pedir): headline, highlights (o que aconteceu nas tarefas da pessoa e nas que ela acompanha), attention (o que pede a atenção dela), issues (as citadas, com code, id e url), generated_at e outdated (chegou novidade depois). POST /aqua/summary (tracker:read) com {"period": "month"} pede um novo (gasta créditos de IA; período sem nada não gasta); 422 com a IA desligada, sem chave ou sem créditos. No MCP: list_inbox, update_inbox e get_aqua_summary.
  • aqua nas issues (a mesma da tela): GET /issues/{ref}/aqua (tracker:read) traz available, can_review (se a pessoa pode pedir a revisão), summary (como aqua_summary de GET /issues/{ref}), review (summary, reviewed_at, outdated), as recommendations abertas (id, kind: comment, status, field, custom_field, label, duplicate ou move; title, before, after, reason e comment, o texto do pedido de informações) e snooze_options. POST /issues/{ref}/aqua/summary (tracker:read) resume a conversa (a partir de summary_min_comments comentários) e devolve {"summary": ...}. POST /issues/{ref}/aqua/review (tracker:write, quem edita a issue) revisa e devolve o mesmo que o GET. POST /aqua/recommendations/{id}/apply (tracker:write) aplica a sugestão ({"comment": "..."} opcional troca o texto do pedido de informações); POST /aqua/recommendations/{id}/dismiss (tracker:write) com {"for": "7"} (1, 7, 30 dias ou forever) ignora. A tela aqua inteira: GET /aqua/recommendations (tracker:read, ?project=MOB opcional) traz available, reason, can_review, daily_review (enabled, hour, limit, last_on, last_count, last_error), sentry_waiting (erros do Sentry esperando decisão, em GET /sentry/errors?waiting=true), total e issues, as issues com sugestões abertas (das paradas há mais tempo para as recentes), cada uma com id, code, title, project, status (name, color, category), summary, reviewed_at, outdated e recommendations (como acima), e snooze_options. "Revisar issues abertas" roda no servidor: POST /aqua/review-runs (tracker:write, {"project": "MOB"} opcional) começa a revisão de todas as issues abertas que a aqua ainda não viu ou que mudaram desde a revisão (até 500, uma de cada vez; uma revisão por vez na empresa, e pedir de novo devolve a que já roda) e devolve {"run": ...} (null sem nada pendente); GET /aqua/review-runs (tracker:read) traz a que roda ou a última, GET /aqua/review-runs/{id} o andamento (status: running, done, stopped ou failed; total, reviewed, failed, suggestions, error, created_at, finished_at e issues, cada uma com id, code, title, state — waiting, running, done ou failed —, suggestions e error) e POST /aqua/review-runs/{id}/stop (tracker:write) para. GET /aqua/review-queue (tracker:read, ?project= e ?limit= até 25) continua devolvendo a fila (id, code, title) para revisar uma a uma com POST /issues/{ref}/aqua/review e {"batch": true} (o modelo da revisão em lote). No MCP: list_aqua_recommendations, start_aqua_review, get_aqua_review, stop_aqua_review, list_issues_to_review, review_issue_with_aqua, apply_aqua_recommendation e dismiss_aqua_recommendation. POST /aqua/draft (tracker:read) com {"text": "relato livre", "project": "MOB"} (project opcional) devolve os campos de POST /issues preenchidos e missing (o que o relato não diz), sem criar nada. POST /aqua/improve (tracker:read) com {"project": "MOB", "type": "bug", "title": "...", "description": "..."} (e os outros textos do formulário) devolve título e textos reescritos e notes, sem gravar. 422 quando a IA está desligada, sem chave ou no limite.