Developer Hub / API (A7)

agility v2 central it · referência de api plataforma de gestão de projetos, portfólio e entrega — kanban, scrum, safe e tradicional em um único servidor multi tenant produto agility v2 — plataforma de gestão de projetos multi tenant, com api rest em /v1 público alvo desenvolvedores e equipes de integração versão do documento 1 0 versão da api v1 data de emissão setembro de 2026 classificação uso do cliente e parceiro técnico sumário executivo índice de leitura rápida — a ordem lógica de consumo do documento antes do sumário paginado nº capítulo 1 introdução 2 conceitos e modelo de domínio 3 primeiros passos 4 autenticação e autorização 5 convenções gerais 6 referência de endpoints 7 webhooks 8 erros — referência global 9 exemplo de integração ponta a ponta 10 versionamento da api 11 glossário 12 suporte e escopo 1\ introdução este documento é a referência técnica da api do agility v2 é escrito para desenvolvedores e equipes de integração que precisam consumir a api do produto — do primeiro handshake de autenticação até a integração completa com fluxos multi tenant de kanban, scrum, safe, portfólio e financeiro não descreve as telas do produto nem a operação para usuários finais; para isso, consulte o manual do usuário o agility v2 é uma plataforma de gestão de projetos e portfólio construída como um único binário go que serve simultaneamente a api rest e a spa embutida a superfície pública sob o prefixo /v1 expõe, no momento desta emissão, 381 rotas de produção que cobrem operação de quadros kanban, sprints scrum, wbs tradicional, programas e portfólios safe, gestão financeira por projeto e por board, importação estruturada de workspaces, e um webhook para integração com gitlab o documento oficial da superfície completa é gerado em tempo de execução pelo próprio servidor e está disponível em get /openapi json (atrás de credencial) e via ui interativa em get /docs nota esta referência descreve os agrupamentos de recursos e os endpoints representativos de cada domínio, com contratos concretos extraídos do código real para a lista exaustiva das 381 rotas — método, path e parâmetros de caminho — apoie se no documento openapi 3 1 servido pela própria api em /openapi json, cuja spec nunca pode divergir do que a porta responde (é gerada por percurso do próprio router chi) 2\ conceitos e modelo de domínio a api do agility v2 é estruturada em bounded contexts observáveis nos pacotes de serviço antes de qualquer chamada, entenda como as entidades se relacionam — os paths refletem essa hierarquia quase toda operação de conteúdo vive sob /v1/workspaces/ /…, e boa parte das operações de projeto sob /v1/workspaces/ /projects/ /… 2 1 entidades centrais entidade descrição tenant isolamento físico é identidade do host da requisição, resolvido pelo tenancit; cada tenant tem seu próprio database postgresql não há tenant default — host desconhecido devolve 404 tenant not found workspace espaço colaborativo dentro do tenant membros ativos são a base do controle de acesso (camada 3 de autorização) um workspace agrupa projects, teams, arts, boards, portfolios e products project iniciativa com escopo, membros e forma de trabalho declarada (kanban, scrum ou tradicional) projetos têm visibilidade (pública/privada) — projetos privados sem vínculo respondem 404 not found para não vazar existência board quadro kanban do projeto cada board tem raias (lanes) e cartões (tasks) board é também a granularidade de vários módulos derivados automation (regras/wip), finance (custos, orçamento), documents (anexos) lane coluna do quadro, com posição, limite de wip opcional e regras de automação task cartão do quadro possui título, descrição, prioridade (baixa/média/alta), responsáveis, dependências, checklists, comentários, tags, custos e anexos team / art time e agile release train (safe) podem estar vinculados a múltiplos projetos e concentram capacidade, coordenação e planejamento de pi portfolio / program / value stream / epic camadas safe portfolio level epics podem ser estratégicos (portfólio) ou de programa; value streams orientam a alocação por fluxo de valor sprint / iteration ciclo de trabalho fixado sprint é a instância; iterations podem representar sub ciclos ou ondas de planejamento wbs / baseline / milestone estrutura analítica do projeto no modo tradicional, com cronograma, versões de baseline e marcos comparáveis release / product ciclo de release e catálogo de produto um produto agrega releases e a release orquestra pipeline até a promoção financial entry / billing request / service order fatos financeiros do projeto entradas de custo, solicitações de faturamento e ordens de serviço, com regras de sla e catálogo de itens vinculado 2 2 hierarquia de path quase todos os recursos ficam sob a árvore de workspace/projeto a rota nomeia o escopo explicitamente — não há endpoints "órfãos" que descubram tenant/workspace por convenção fora do path /v1/session /v1/version /v1/workspaces/{workspaceid}/ projects/{projectid}/ boards/{boardid}/ lanes/{laneid}/ tasks/{taskid}/ documents/{documentid} checklists/{checklistid}/items/{itemid} finance/(summary|entries|billing requests|service orders|slas) documents/{documentid} finance/(summary|entries|billing requests|service orders|catalog items|slas) document types/{typeid} documents/{documentid} history/… goals/{goalid} teams/{teamid}/members arts/{artid}/(iterations|pi plannings|team performance) portfolios/{portfolioid}/(epics|value streams|programs) products/{productid}/(releases|objectives) releases/{releaseid}/(pipeline|version check) reports | people | import | integrations/gitlab/ 3\ primeiros passos este capítulo leva do zero à primeira chamada bem sucedida vale igualmente para integradores em ambiente de desenvolvimento (modo dev, bearer opaco) e para clientes em ambiente hospedado (modo oidc via keycloak) 3 1 escolha o modo de autenticação do servidor o servidor sempre exige credencial — não sobe sem auth mode definido dois modos são suportados modo como funciona uso típico dev bearer opaco o servidor aceita qualquer requisição que traga o header authorization bearer \<dev token> o token precisa ter no mínimo 16 caracteres todas as chamadas rodam como um usuário administrador estável (roles \[agility admin], 5 capabilities) desenvolvimento local, testes automatizados, integração contra ambiente sandbox oidc openid connect (authorization code + pkce) contra keycloak o servidor sela uma sessão em cookie aes 256 gcm (httponly) após o callback chamadas subsequentes usam o cookie ou um bearer jwt emitido pelo idp (fluxo hosted) ambientes produtivos hospedados, integração com idp do cliente 3 2 primeira chamada — modo dev depois de subir o servidor com auth mode=dev e dev token definido, valide a autenticação chamando /v1/session requisição curl s https //agility example com/v1/session \\ h "authorization bearer \<seu dev token>" resposta 200 ok http/1 1 200 ok content type application/json { "user" { "id" "11111111 1111 1111 1111 111111111111", "displayname" "dev user", "email" "dev\@example com", "avatarurl" "" }, "roles" \["agility admin"], "capabilities" \["view", "comment", "edit", "approve", "admin"] } dica a resposta de /v1/session confirma três coisas ao mesmo tempo (1) a credencial foi aceita; (2) o host resolveu para um tenant existente; (3) o usuário está ativo no diretório interno se qualquer uma dessas três camadas falhar, você recebe um erro diferente 401 unauthenticated para (1), 404 tenant not found para (2), ou 403 identity ineligible para (3) 3 3 primeira chamada — modo oidc (fluxo hosted) no modo oidc, três formas de apresentar credencial são aceitas — nesta ordem de precedência exata, sem fallback silencioso entre elas credencial de plataforma via cookie da plataforma hosted (nome configurado pelo operador do ambiente) ou header authorization bearer \<jwt> emitido pelo idp hosted cookie de sessão selado do agility (nome default agility session), emitido pelo callback oidc em modo dev exclusivamente, o bearer opaco descrito em 3 2 fluxo inicial via navegador (spa ou parceiro) navegue até get /v1/auth/login, o servidor redireciona para o keycloak, o callback em get /v1/auth/callback sela a sessão em cookies httponly (agility session + id token), e chamadas subsequentes levam o cookie automaticamente para integração server to server contra ambiente hospedado, obtenha um jwt pelo idp e envie o em authorization bearer requisição curl s https //\<tenant> agility example com/v1/session \\ h "authorization bearer \<jwt emitido pelo idp>" 4\ autenticação e autorização 4 1 precedência de credencial verifier authenticate resolve credenciais em uma ordem estrita uma credencial presente e inválida é sempre erro; nunca há fallback silencioso para o próximo tipo ordem fonte requisito falha explícita 1 resolução do tenant pelo host host precisa estar registrado no tenancit e ter provider oidc associado 404 tenant not found ou 503 tenant unavailable 2 cookie da plataforma hosted ou authorization bearer \<jwt> jwt cujo azp esteja na allowlist de client id da plataforma pode omitir aud; qualquer outro precisa trazer a audiência configurada 401 hyper token invalid — sem fallback para cookie de sessão 3 cookie de sessão selado do agility (default agility session) aes 256 gcm com prefixo v1 e iv aleatório; providerfingerprint precisa coincidir em tempo constante com o do provedor resolvido pelo host 401 unauthenticated 4 bearer opaco apenas em auth mode=dev precisa ter no mínimo 16 caracteres e bater exatamente com dev token 401 unauthenticated 4 2 capabilities e papéis (keycloak) cada rota autenticada pede uma capability específica o mapeamento papel do realm → capability é 1 1; papéis desconhecidos (incluindo os defaults do keycloak) são descartados silenciosamente em modo dev, o token opaco emite todos os cinco papéis papel de realm capability o que permite agility viewer view leitura da maior parte das rotas get agility commenter comment comentar em tasks e itens; complementa view agility editor edit escrita em quadros, tasks, projetos, financeiro agility approver approve aprovações de billing/service order/release agility admin admin administração do workspace, arts, portfólios, integrações 4 3 as cinco camadas de autorização uma requisição autenticada atravessa até cinco decisões independentes nenhuma substitui outra — falhar em qualquer uma encerra a requisição com um código específico camada decide falha típica 0 — tenant por host se o host resolve para um tenant conhecido e o control plane responde 404 tenant not found · 503 tenant unavailable · 503 database unavailable 1 — identidade interna se o principal externo mapeia para um usuário ativo em users do tenant 403 identity ineligible · 503 identity unavailable 2 — capability do realm se o principal tem a capability exigida pela rota (view/edit/…) 403 forbidden 3 — associação ao workspace se o usuário é membro ativo do workspace do path 404 not found (não vaza existência) 4 — visibilidade do projeto se o projeto é público ou o usuário tem vínculo em projeto privado 404 not found 5 — owner e estado se a ação exige ser dono, ou se o estado permite (wip, baseline etc ) 403 forbidden · 409 owner protected · 422 rule blocked atenção visibilidade de navegação nunca é fronteira de autorização a lista de capabilities devolvida em /v1/session (via derivecapabilities) é contrato de navegação para a ui, não substituto para os middlewares do servidor ocultar um item de menu no cliente não impede a chamada — a decisão está sempre no servidor 4 4 rotas públicas (sem credencial de sessão) sete rotas são explicitamente públicas — cobertas por testes que percorrem o router e disparam requisições sem credencial contra cada uma método rota papel get /healthz sonda de vivência do processo get /readyz sonda de prontidão (checa dependências) get /docs página swagger ui (a spec exige credencial, o html não) get /v1/auth/login inicia authorization code com pkce get /v1/auth/callback recebe o código e sela sessão post /v1/auth/logout encerra sessão local e devolve endsessionurl do idp post /v1/auth/refresh renova access token via refresh token selado post /v1/integrations/gitlab/webhook webhook gitlab — validado por segredo do tenant no handler 5\ convenções gerais 5 1 urls base e ambientes a api é servida sob agility base path quando esse valor é vazio, os endpoints ficam na raiz toda url na resposta é relativa — o tenant é resolvido pelo host da requisição, então urls absolutas trocariam o tenant e ainda esbarrariam no cors ambiente url típica observação local (dev) http //localhost 8080 auth mode=dev, dev token opaco hosted dev https //\<sub> \<domínio lab>/\<base path>/ oidc via keycloak local, tls consulte a topologia de dev do seu ambiente produção hosted https //\<tenant> agility \<domínio>/ host resolve o tenant no tenancit 5 2 formato de request e response content type é application/json em toda escrita, exceto upload de documentos (multipart/form data) toda resposta bem sucedida devolve json com content type application/json; charset=utf 8 corpo vazio de sucesso é 204 no content — operações típicas delete e reorderboards 5 3 envelope de erro erros de negócio e de infraestrutura usam um único envelope o status http e o campo code fazem parte do contrato; clientes nunca devem interpretar o texto de message para decidir fluxo envelope padrão de erro { "error" { "code" "not found", "message" "recurso não encontrado" } } 5 4 versionamento da api versionamento por path todas as rotas de conteúdo ficam sob /v1 uma mudança incompatível abre um novo prefixo (v2 conviveria com v1 até deprecar); mudanças compatíveis (novos campos opcionais, novos endpoints) chegam sem bump de versão a build do servidor é reportada em get /v1/version (autenticada de propósito — identificação para suporte, não banner público) 5 5 multi tenancy por host não existe tenant default nem parâmetro de tenant no path o tenant é o host da requisição, resolvido pelo tenancit; cada tenant tem seu próprio database consequência prática para integração um cliente que consome múltiplos tenants precisa ter uma url base distinta para cada um — reutilizar bearer entre hosts diferentes falha porque o providerfingerprint selado no cookie/token não coincide 5 6 documento openapi e swagger ui o próprio servidor publica a spec openapi 3 1 gerada em tempo de execução rota requisito conteúdo get /openapi json credencial autenticada documento openapi 3 1 completo com as 381 rotas, seus métodos, paths e parâmetros de caminho não descreve corpo/query/response — os payloads vivem em structs anônimas dentro dos handlers e a spec declara essa lacuna em info description em vez de adivinhar schemas get /docs público swagger ui vazia — o html não contém rota nenhuma o bundle busca o documento depois, atrás de credencial ideia chave a spec /openapi json é a fonte única de inventário de rotas — não pode divergir do router porque é gerada por percurso do mesmo router chi que serve produção se você precisa da lista canônica de endpoints (por exemplo, para gerar mocks ou testes de contrato), consuma /openapi json em vez de manter uma cópia paralela deste documento 6\ referência de endpoints os endpoints estão agrupados por recurso para cada grupo apresentamos (a) o path base, (b) as rotas representativas com método/parâmetros/capability, e (c) o exemplo de request/response ou o formato do payload quando conhecido a lista exaustiva das 381 rotas — inclusive as variantes com identificador legado — está em get /openapi json 6 1 autenticação e sessão método rota capability descrição get /v1/auth/login público inicia authorization code com pkce get /v1/auth/callback público sela sessão e id token em cookies httponly post /v1/auth/logout cookie de sessão encerra sessão local; devolve endsessionurl do idp post /v1/auth/refresh cookie selado renova access token get /v1/session autenticado devolve user, roles e capabilities do chamador get /v1/version autenticado informa version, revision, builtat, modified da build requisição get /v1/version authorization bearer \<token> resposta 200 ok http/1 1 200 ok { "version" "1 4 0", "revision" "\<commit hash curto>", "builtat" "2026 09 10t14 12 00z", "modified" false } 6 2 workspaces, projetos e times método rota capability descrição get /v1/workspaces/ /projects view lista projetos do workspace conforme visibilidade post /v1/workspaces/ /projects edit cria projeto get /v1/workspaces/ /projects/ view detalhe do projeto (aplica visibilidade) patch /v1/workspaces/ /projects/ edit atualiza atributos do projeto get /v1/workspaces/ /projects/ /members view lista membros do projeto post /v1/workspaces/ /projects/ /members edit adiciona membro patch /v1/workspaces/ /projects/ /members/ edit atualiza o papel do membro delete /v1/workspaces/ /projects/ /members/ edit remove membro post /v1/workspaces/ /projects/ /teams/ edit vincula time ao projeto delete /v1/workspaces/ /projects/ /teams/ edit desvincula time post /v1/workspaces/ /projects/ /arts/ edit vincula art ao projeto delete /v1/workspaces/ /projects/ /arts/ edit desvincula art get /v1/workspaces/ /teams view lista times do workspace post /v1/workspaces/ /teams edit cria time get /v1/workspaces/ /teams/ view detalhe do time patch /v1/workspaces/ /teams/ edit atualiza time delete /v1/workspaces/ /teams/ edit exclui time get /v1/workspaces/ /teams/ /members view membros do time get /v1/workspaces/ /reports view relatórios agregados do workspace get /v1/workspaces/ /people view diretório de pessoas do workspace requisição post /v1/workspaces/w 123/projects authorization bearer \<token> content type application/json { "name" "sistema de pagamentos", "description" "iniciativa 2026q4", "visibility" "private", "workingmode" "kanban" } resposta 201 created http/1 1 201 created { "id" "p 9f0c1e", "workspaceid" "w 123", "name" "sistema de pagamentos", "description" "iniciativa 2026q4", "visibility" "private", "workingmode" "kanban", "createdat" "2026 09 24t14 12 00z", "createdby" "u 42" } 6 3 boards, lanes e tasks (kanban) método rota capability descrição get /v1/workspaces/ /boards view lista boards do workspace post /v1/workspaces/ /boards edit cria board (title, type, startdate?, enddate?) post /v1/workspaces/ /boards/reorder edit reordena boards pela ordem dos ids get /v1/boards/ view detalhe do board por id (legado; use a variante contextual) get /v1/workspaces/ /projects/ /boards/ view detalhe do board no escopo do projeto patch /v1/boards/ edit atualiza título delete /v1/boards/ edit exclui board get /v1/boards/ /lanes view lista raias do board post /v1/boards/ /lanes edit cria raia patch /v1/lanes/ edit atualiza raia (título, wip, posição) delete /v1/lanes/ edit remove raia get /v1/lanes/ /tasks?title= view lista tasks filtro opcional por título post /v1/lanes/ /tasks edit cria task (com wip check da raia) get /v1/tasks/ view detalhe da task patch /v1/tasks/ edit atualiza task delete /v1/tasks/ edit exclui task post /v1/tasks/ /move edit move task para outra raia (aplica wip) post /v1/tasks/ /dependencies edit cria dependência entre tasks delete /v1/tasks/ /dependencies/ edit remove dependência get /v1/tasks/ /checklists view lista checklists da task post /v1/tasks/ /checklists edit cria checklist post /v1/checklists/ /items edit adiciona item ao checklist patch /v1/checklist items/ edit marca/edita item requisição — criar board post /v1/workspaces/w 123/boards authorization bearer \<token> content type application/json { "title" "sprint 42", "type" "kanban", "startdate" "2026 10 01", "enddate" "2026 10 14" } resposta 201 created http/1 1 201 created { "id" "b 77aa", "workspaceid" "w 123", "title" "sprint 42", "type" "kanban", "startdate" "2026 10 01", "enddate" "2026 10 14", "lanes" \[] } requisição — criar task post /v1/lanes/l 01/tasks authorization bearer \<token> content type application/json { "title" "escrever contrato pix", "priority" "alta", "assigneeids" \["u 42"] } resposta 422 (regra de wip bloqueou) http/1 1 422 unprocessable entity { "error" { "code" "rule blocked", "message" "limite de wip da raia foi atingido (3/3)" } } 6 4 scrum — sprints, iterações, capacidade método rota capability descrição get /v1/workspaces/ /projects/ /scrum/sprints view lista sprints do projeto post /v1/workspaces/ /projects/ /scrum/sprints edit cria sprint patch /v1/scrum/sprints/ edit atualiza sprint post /v1/scrum/sprints/ /close approve encerra sprint get /v1/scrum/sprints/ /iterations view lista iterações post /v1/scrum/sprints/ /iterations edit cria iteração get /v1/scrum/sprints/ /stories view backlog de histórias post /v1/scrum/sprints/ /stories edit adiciona história get /v1/scrum/sprints/ /capacity view capacidade planejada vs realizada 6 5 tradicional — wbs, cronograma, baselines, riscos método rota capability descrição get /v1/workspaces/ /projects/ /wbs view estrutura analítica do projeto get /v1/workspaces/ /projects/ /traditional/schedule view cronograma tradicional post /v1/workspaces/ /projects/ /traditional/schedule edit atualiza cronograma get /v1/workspaces/ /projects/ /traditional/baselines view lista baselines post /v1/workspaces/ /projects/ /traditional/baselines approve cria baseline get /v1/workspaces/ /projects/ /traditional/risks view registro de riscos post /v1/workspaces/ /projects/ /traditional/risks edit adiciona risco patch /v1/workspaces/ /projects/ /traditional/risks/ edit atualiza risco delete /v1/workspaces/ /projects/ /traditional/risks/ edit remove risco 6 6 portfólio, programas, value streams e épicos método rota capability descrição get /v1/workspaces/ /portfolios view lista portfólios do workspace post /v1/workspaces/ /portfolios admin cria portfólio get /v1/portfolios/ view detalhe do portfólio patch /v1/portfolios/ admin atualiza portfólio get /v1/portfolios/ /epics view épicos estratégicos post /v1/portfolios/ /epics edit cria épico get /v1/portfolios/ /value streams view value streams post /v1/portfolios/ /programs admin cria programa vinculado ao portfólio get /v1/programs/ view detalhe do programa get /v1/programs/ /features view features do programa get /v1/programs/ /program objectives view objetivos do programa 6 7 produtos e releases método rota capability descrição get /v1/workspaces/ /products view catálogo de produtos post /v1/workspaces/ /products admin cria produto get /v1/products/ view detalhe do produto get /v1/products/ /releases view releases do produto post /v1/products/ /releases edit cria release get /v1/products/ /product objectives view objetivos do produto get /v1/releases/ view detalhe da release post /v1/releases/ /promote approve promove a release no pipeline get /v1/releases/ /release version check view verifica versão da release contra pipeline 6 8 safe — arts, pi plannings e coordenação método rota capability descrição get /v1/workspaces/ /arts view lista agile release trains post /v1/workspaces/ /arts admin cria art get /v1/arts/ view detalhe da art get /v1/arts/ /team performance view desempenho por time da art get /v1/arts/ /pi plannings view pi plannings agendados post /v1/arts/ /pi plannings edit cria pi planning get /v1/pi plannings/ view detalhe do pi planning post /v1/pi plannings/ /close approve encerra pi planning get /v1/safe/workspaces/ /projects/ /… view rotas safe por projeto (release, planning, coordenação) 6 9 financeiro (72 rotas) o módulo financeiro é o maior por volume de rotas toda operação vive dentro do escopo de projeto (e várias também no escopo de board) papéis principais leituras usam view, escritas usam edit, aprovações usam approve quando as variáveis agility erp estão preenchidas, as leituras batem no erp real via adapter http; senão o adapter demo devolve dados determinísticos com badge demo método rota capability descrição get /v1/workspaces/ /projects/ /finance/summary view resumo financeiro do projeto get /v1/workspaces/ /projects/ /finance/entries view lista entradas de custo post /v1/workspaces/ /projects/ /finance/entries edit cria entrada patch /v1/workspaces/ /projects/ /finance/entries/ edit atualiza entrada delete /v1/workspaces/ /projects/ /finance/entries/ edit remove entrada post /v1/workspaces/ /projects/ /finance/appropriate hours edit apropria horas em custo get /v1/workspaces/ /projects/ /finance/settings view configurações financeiras put /v1/workspaces/ /projects/ /finance/settings admin atualiza configurações get /v1/workspaces/ /projects/ /finance/billing requests view solicitações de faturamento post /v1/workspaces/ /projects/ /finance/billing requests edit cria faturamento patch /v1/workspaces/ /projects/ /finance/billing requests/ approve avança estado get /v1/workspaces/ /projects/ /finance/service orders view ordens de serviço post /v1/workspaces/ /projects/ /finance/service orders edit cria ordem patch /v1/workspaces/ /projects/ /finance/service orders/ edit atualiza ordem get /v1/workspaces/ /projects/ /finance/catalog items view itens de catálogo vinculados post /v1/workspaces/ /projects/ /finance/catalog items edit vincula item patch /v1/workspaces/ /projects/ /finance/catalog items/ edit atualiza vínculo delete /v1/workspaces/ /projects/ /finance/catalog items/ edit desvincula get /v1/workspaces/ /projects/ /finance/slas view slas financeiros post /v1/workspaces/ /projects/ /finance/slas edit cria sla patch /v1/workspaces/ /projects/ /finance/slas/ edit atualiza sla delete /v1/workspaces/ /projects/ /finance/slas/ edit remove sla get /v1/boards/ /finance/ view variantes por board — mesmas coleções, escopo mais estreito nota as leituras financeiras contra o erp real dependem de agility erp base url, agility erp app key e agility erp external tenant id no ambiente do servidor — não são parâmetros da api do integrador falha comum 403 tenant unresolved indica identificador externo do tenant erp inválido (o resolver do erp faz optional\<uuid>, e um valor não uuid resolve vazio); 401 appkey invalid indica chave errada 6 10 documentos documentos vivem em três escopos projeto, board e task cada escopo tem seu par list/upload/download/delete, e um alias /download explícito para forçar content disposition attachment tipos de documento (document types) são catalogados por projeto — leia antes de anexar método rota capability descrição get /v1/workspaces/ /projects/ /document types view lista tipos post /v1/workspaces/ /projects/ /document types admin cria tipo patch /v1/workspaces/ /projects/ /document types/ admin atualiza tipo delete /v1/workspaces/ /projects/ /document types/ admin remove tipo get /v1/workspaces/ /projects/ /documents view lista documentos do projeto post /v1/workspaces/ /projects/ /documents (multipart) edit envia documento (file + typeid) get /v1/workspaces/ /projects/ /documents/ view baixa documento get /v1/workspaces/ /projects/ /documents/ /download view baixa forçando attachment delete /v1/workspaces/ /projects/ /documents/ edit remove post /v1/…/boards/ /documents edit upload no escopo de board post /v1/…/boards/ /tasks/ /documents edit upload no escopo de task 6 11 metas, riscos, objetivos método rota capability descrição get /v1/workspaces/ /goals view metas do workspace post /v1/workspaces/ /goals edit cria meta get /v1/workspaces/ /projects/ /goals view metas do projeto post /v1/workspaces/ /projects/ /goals edit cria meta no projeto patch /v1/goals/ edit atualiza meta delete /v1/goals/ edit remove meta get /v1/programs/ /program objectives view objetivos de programa (safe) get /v1/products/ /product objectives view objetivos de produto 6 12 importação de workspace importação estruturada de dados de workspace/projeto o fluxo típico é obtenha o schema, envie o payload a /import/validate para relatório de conformidade, e depois chame /import para efetivar método rota capability descrição get /v1/workspaces/ /import/schema view schema json esperado get /v1/workspaces/ /import/template view template pré preenchido post /v1/workspaces/ /import/validate edit valida payload; devolve diagnóstico post /v1/workspaces/ /import admin executa importação (idempotente por externalid) post /v1/workspaces/ /projects/ /import/validate edit validação por projeto post /v1/workspaces/ /projects/ /import admin importação por projeto 6 13 integrações — gitlab integração com gitlab tem duas superfícies rotas administrativas autenticadas para conectar/desconectar/configurar o link do workspace, e o webhook público que recebe eventos do gitlab (validado por segredo do tenant no handler, não por cookie de sessão) método rota capability descrição get /v1/workspaces/ /integrations/gitlab view estado da conexão do workspace put /v1/workspaces/ /integrations/gitlab admin configura/atualiza conexão delete /v1/workspaces/ /integrations/gitlab admin desconecta integração post /v1/workspaces/ /integrations/gitlab/rotate secret admin rotaciona segredo do webhook post /v1/integrations/gitlab/webhook público (segredo do tenant) recebe eventos gitlab 6 14 meu quadro, busca e ia método rota capability descrição get /v1/my board view vista agregada de todo trabalho atribuído ao usuário get /v1/search?q= view busca cross recurso (tasks, boards, projetos) get /v1/ai/status view status do serviço de ia (para ai estimate e afins) post /v1/ai/test edit testa integração com o backend de ia configurado post /v1/webhook test edit endpoint de teste de webhook (sem coordenada de recurso) 7\ webhooks o agility v2 tem, no momento, um webhook público /v1/integrations/gitlab/webhook, receptor de eventos do gitlab a rota fica fora do middleware requireauth — a credencial dela é o segredo do tenant, validado dentro do handler contra o cabeçalho enviado pelo gitlab 7 1 gitlab webhook configure o webhook no gitlab apontando para post /v1/integrations/gitlab/webhook do host do tenant, com o segredo obtido no put /v1/workspaces/ /integrations/gitlab rotacione o segredo pelo endpoint /rotate secret sempre que necessário; a rotação invalida imediatamente o segredo anterior requisição típica post /v1/integrations/gitlab/webhook host \<tenant> agility example com x gitlab token \<segredo do tenant> x gitlab event push hook content type application/json { / payload padrão do gitlab / } respostas 204 no content quando o evento é aceito; 401 unauthenticated quando o segredo é inválido; 422 quando o payload não é compreendido para o tipo de evento declarado não há retry no lado do servidor — o gitlab controla o retry conforme configuração dele 8\ erros — referência global toda resposta de erro carrega o envelope descrito em 5 3 a tabela abaixo consolida os códigos observados em produção — o campo code é estável e faz parte do contrato, a message é livre e pode ser reescrita entre versões status http code significado / quando ocorre 400 invalid body payload json malformado ou com campo obrigatório ausente 400 invalid query parâmetro de query inválido (formato, faixa) 401 unauthenticated credencial ausente, malformada ou expirada 401 hyper token invalid jwt hosted apresentado é inválido — sem fallback para outro tipo 403 forbidden autenticado mas sem a capability exigida pela rota 403 identity ineligible usuário externo válido mas inativo no diretório interno 404 not found recurso não existe ou não é visível para o chamador (não vaza existência) 404 tenant not found host da requisição não resolve para tenant registrado 409 conflict conflito de estado (versão desatualizada, item já existente) 409 owner protected ação de owner protegido — só o próprio dono pode executar 422 rule blocked regra de domínio impediu a ação (ex limite de wip da raia) 422 validation failed validação semântica do domínio falhou 503 tenant unavailable control plane inacessível — retentar depois 503 database unavailable banco do tenant inacessível — retentar depois 503 identity unavailable diretório interno indisponível — retentar depois dica nunca faça parsing do texto de error message para decidir fluxo do cliente — o texto é livre use error code, que é estável entre versões o cliente oficial da spa materializa isso em apierror, que carrega apenas status + code 9\ exemplo de integração ponta a ponta cenário um integrador precisa criar um board novo dentro de um workspace, adicionar uma raia "doing" com limite de wip e criar uma primeira task quatro chamadas, cada uma dependente da anterior 9 1 passo 1 — validar credencial e escolher o workspace requisição curl s https //agility example com/v1/session \\ h "authorization bearer \<token>" resposta http/1 1 200 ok { "user" {"id" "u 42", }, "capabilities" \["view","edit", ] } 9 2 passo 2 — criar o board requisição curl s x post https //agility example com/v1/workspaces/w 123/boards \\ h "authorization bearer \<token>" \\ h "content type application/json" \\ d '{"title" "backlog q4","type" "kanban"}' resposta http/1 1 201 created { "id" "b abc", "title" "backlog q4", } 9 3 passo 3 — criar a raia com wip requisição curl s x post https //agility example com/v1/boards/b abc/lanes \\ h "authorization bearer \<token>" \\ h "content type application/json" \\ d '{"title" "doing","wiplimit" 3,"position" 1}' resposta http/1 1 201 created { "id" "l 01", "title" "doing", "wiplimit" 3, "position" 1 } 9 4 passo 4 — criar a primeira task (com tratamento de wip) requisição curl s x post https //agility example com/v1/lanes/l 01/tasks \\ h "authorization bearer \<token>" \\ h "content type application/json" \\ d '{"title" "escrever contrato pix","priority" "alta"}' sucesso http/1 1 201 created { "id" "t 9f", "title" "escrever contrato pix", "priority" "alta" } falha — trate error code="rule blocked" e ofereça outra raia ao usuário http/1 1 422 unprocessable entity { "error" { "code" "rule blocked", "message" "limite de wip da raia foi atingido (3/3)" } } 10\ versionamento da api todas as rotas de conteúdo ficam sob /v1 a convenção do produto mudanças compatíveis (novos endpoints, novos campos opcionais na resposta) chegam sob /v1, sem bump nem aviso — clientes conservadores ignoram campos desconhecidos deprecação de rota anunciada em release notes internas do produto; a rota antiga continua respondendo até a próxima ondulação major mudança incompatível abre novo prefixo /v2, /v3 etc ; /v1 continua vivo durante o período de convivência declarado para identificar a build servida (útil em suporte), chame get /v1/version a resposta traz version (semântica), revision (commit curto), builtat e modified (true quando a árvore do build tinha alterações locais) 10 1 changelog resumido data mudança relevante para integradores 2026 09 22 divisória entre /docs (público) e /openapi json (autenticado) formalizada 2026 09 21 documento openapi 3 1 gerado em runtime pelo próprio servidor 2026 09 09 post /v1/lanes/ /tasks passou a aceitar priority ausente (default media) 2026 08 07 rotas contextuais /workspaces/ /projects/ /boards/ passam a ser o caminho canônico; rotas id only /boards/ continuam por compatibilidade 11\ glossário termo definição art agile release train — grupo estável de times safe que entrega valor em cadência baseline snapshot congelado do cronograma tradicional para comparação com o realizado board quadro kanban do projeto; agrega raias, tasks, regras e financeiro do board capability permissão derivada 1 1 de papel de realm do keycloak view/comment/edit/approve/admin dev token bearer opaco aceito quando auth mode=dev; ≥16 caracteres envelope de erro estrutura json única {error {code, message}} usada em toda resposta ≥400 épico iniciativa de portfólio safe, agrupa features feature unidade de valor de programa safe; agrupa histórias lane coluna de um board kanban, com posição e limite de wip opcional oidc openid connect — modo de autenticação hospedada via keycloak pi planning program increment planning — cerimônia safe de planejamento do próximo pi portfolio camada estratégica safe que agrupa programas e value streams principal objeto interno com identidade autenticada + roles + capabilities + binding do tenant providerfingerprint impressão digital do provedor oidc selada no cookie; impede reutilização entre hosts task cartão dentro de uma raia; unidade de trabalho no kanban tenant isolamento físico por host; cada tenant tem seu próprio database postgresql tenancit serviço de control plane que resolve host → tenant + provedor oidc value stream fluxo de valor safe usado para orientar alocação e priorização wbs work breakdown structure — estrutura analítica do projeto tradicional wip work in progress — limite máximo de tasks simultâneas em uma raia workspace espaço colaborativo dentro do tenant; base da associação e do controle de acesso 12\ suporte e escopo 12 1 o que este documento cobre referência técnica da api pública do agility v2 na versão v1 autenticação, modelo de domínio, endpoints representativos por recurso, webhooks, envelope de erro e exemplo de integração cobre todos os grupos de recursos observáveis no router de produção 12 2 o que este documento não cobre operação de interface (telas, cliques, navegação da spa) — consulte o manual do usuário detalhamento profundo de segurança de infraestrutura (isolamento entre tenants, criptografia em repouso, política de retenção) — consulte o whitepaper de arquitetura e trust center quando disponível 12 3 direcionamento de dúvidas técnicas dúvidas de contrato ou de comportamento específico não descrito aqui consulte get /openapi json (spec sempre em dia com a porta), a página /docs (swagger ui interativa), e as trilhas de developer em docs/developers/ do repositório para incidentes ou dúvidas de conta, procure o canal de suporte técnico acordado com a central it