FEATURE ROLLOUT · DOCUMENTAÇÃO

Referência HTTP por família de recursos

A API possui contratos de automação estáveis e rotas de sessão usadas pelo dashboard. A tabela abaixo deixa explícito método, autenticação, entrada e saída antes dos exemplos.

Convenções

Envie JSON com Content-Type: application/json, arquivos com multipart/form-data e credenciais de automação no header Authorization: Bearer. Datas retornam em ISO 8601. Erros JSON usam ao menos { "error": "mensagem" }.

200Leitura ou atualização concluída

201Recurso ou execução criada

204Logout sem corpo

400Entrada inválida

401Credencial ausente, expirada ou inválida

403Papel, escopo ou confiança insuficiente

404Recurso fora do escopo ou inexistente

409Conflito, duplicidade ou gate bloqueado

413Payload acima do limite

422Contrato semanticamente inconsistente

Inventário de endpoints

GET /api/health e /api/versionDiagnóstico e versão · público

/api/v2/management/projectsListar, criar, ler, atualizar e excluir projetos · token pessoal

/api/v2/management/projects/:id/portfoliosListar e criar portfólios · token pessoal

/api/v2/management/portfolios/:id/featuresListar e criar features · token pessoal

/api/v2/management/features/:id/{scenarios,evidences,risks}Sub-recursos da feature · token pessoal

/api/v2/management/portfolios/:id/documentsListar e enviar documentações · token pessoal

/api/v2/management/documents/:id/versionsAdicionar versão documental · token pessoal

/api/v2/management/document-versions/:id/contentBaixar conteúdo versionado · token pessoal

POST /api/v1/test-resultsIngestão simples por feature · chave CI

POST /api/v2/test-runsIngestão contextual e idempotente · chave CI

POST /api/v1/test-results/:id/coverageCobertura · chave CI

PUT /api/v2/catalogReconciliação · OIDC confiável

POST /api/v2/gates/evaluateGate · OIDC confiável

Crie um projeto

Este contrato usa o token pessoal emitido por fr login e funciona da mesma forma no Docker local e no remoto. O slug é gerado e desambiguado pelo servidor.

shell

export WORKSPACE_SLUG='lb-pay'

curl --fail-with-body --request POST   "$FEATURE_ROLLOUT_URL/api/v2/management/projects"   --header "Authorization: Bearer $FEATURE_ROLLOUT_TOKEN"   --header 'Content-Type: application/json'   --data "{
    \"workspace\": \"$WORKSPACE_SLUG\",
    \"name\": \"Pagamentos Brasil\",
    \"description\": \"Rollout dos produtos de pagamento\"
  }"

Entrada

workspace aceita slug ou UUID, name tem entre 2 e 100 caracteres e description até 500. O token precisa de management:write e papel admin ou owner.

Leia a saída da criação

Guarde project.id para configuração e project.slug para o catálogo/CI. Liste os projetos autorizados com GET /api/v2/management/projects?workspace=lb-pay.

json

{
  "project": {
    "id": "74fb03ea-75e8-4e81-aed9-ea08b913b23d",
    "workspaceId": "11111111-1111-4111-8111-111111111111",
    "workspaceSlug": "lb-pay",
    "workspaceName": "LB Pay",
    "slug": "pagamentos-brasil",
    "name": "Pagamentos Brasil",
    "description": "Rollout dos produtos de pagamento"
  }
}

Atualize ou exclua um projeto

O PATCH devolve o projeto atualizado. O DELETE bem-sucedido responde 204 No Content; erros mantêm o envelope JSON padronizado e o x-request-id. Faça backup antes de qualquer exclusão local.

shell

export PROJECT_ID='74fb03ea-75e8-4e81-aed9-ea08b913b23d'

curl --fail-with-body --request PATCH   "$FEATURE_ROLLOUT_URL/api/v2/management/projects/$PROJECT_ID"   --header "Authorization: Bearer $FEATURE_ROLLOUT_TOKEN"   --header 'Content-Type: application/json'   --data '{
    "name": "Pagamentos LATAM",
    "description": "Rollout dos produtos de pagamento na América Latina"
  }'

# Exclusão é destrutiva: confirmation deve ser o nome atual exato.
curl --fail-with-body --request DELETE   "$FEATURE_ROLLOUT_URL/api/v2/management/projects/$PROJECT_ID"   --header "Authorization: Bearer $FEATURE_ROLLOUT_TOKEN"   --header 'Content-Type: application/json'   --data '{"confirmation":"Pagamentos LATAM"}'

Operação destrutiva

DELETE exige o nome atual exato e remove todos os recursos descendentes. Um agente nunca deve executar essa chamada sem confirmação humana explícita.

Atualize checklist e sign-off

Checklist e sign-off são alterações pontuais; features, tarefas, cenários, evidências declarativas e riscos são reconciliados em conjunto pelo catálogo v2.

checklist input{ completed: boolean }

checklist outputItem atualizado com id, estado e timestamps

signoff inputstatus + note opcional até 1.000 caracteres

signoff outputid, status, owner, note e decidedAt

shell

curl --fail-with-body --request PATCH   "$FEATURE_ROLLOUT_URL/api/checklist/CHK-PIX-001"   --header 'Content-Type: application/json'   --data '{"completed":true}'

curl --fail-with-body --request PATCH   "$FEATURE_ROLLOUT_URL/api/signoffs/SIGN-PIX-OPS"   --header 'Content-Type: application/json'   --data '{"status":"APROVADO","note":"Runbook validado em homologação."}'

Avalie o gate sem alterar estado

Sem bloqueadores retorna HTTP 200 e passed: true. Com bloqueadores retorna HTTP 409, passed: false e uma lista de objetos { type, featureId, feature, message }. Use o status HTTP para o pipeline e o corpo para explicar a decisão.

shell

curl --request POST   "$FEATURE_ROLLOUT_URL/api/v2/gates/evaluate"   --header "Authorization: Bearer $FEATURE_ROLLOUT_TOKEN"   --header 'Content-Type: application/json'   --data '{
    "project": "lb-pay",
    "application": "pix-automatico",
    "repository": "conta-facil/lb-pay",
    "environment": "production"
  }'

Descubra IDs antes de automatizar

Use fr project list --workspace lb-pay e as coleções da Management API para descobrir UUIDs antes de automatizar. Slugs continuam sendo o identificador recomendado para catálogo e testes; IDs de checklist/sign-off permanecem definidos no catálogo.

Contrato fechado

Não consulte tabelas PostgreSQL para descobrir recursos em automações. Isso acopla o agente ao schema interno e contorna permissões e auditoria.