REST API
O contrato headless durável para contexto e decisões canônicas do Blocchi.
A API versionada fica em /api/v1. O documento OpenAPI legível por máquina está disponível em /api/openapi/v1.
Autenticação
Hoje o limite headless aceita uma sessão autenticada do Blocchi ou um bearer token válido do Supabase. O gerenciamento de chaves de desenvolvedor emitidas pelo Blocchi é uma superfície de credenciais separada e só deve ser considerado disponível quando estiver exposto no produto.
Autenticação não significa acesso a todo o tenant. Papel no tenant, viewer scope, entitlement de produto e autorização específica da capacidade continuam sendo autoridade.
Regras do contrato
- IDs e conceitos canônicos do Blocchi são o contrato público, não schemas nativos de provedores.
- Uma métrica nula com prontidão bloqueada ou desconhecida não é zero.
- Evidência e proveniência são de primeira classe.
- Eventos de negócio e alertas são registros source-of-truth; entrega de notificação é um recibo.
- Comandos consequenciais são limitados por capacidade e podem exigir confirmação explícita.
- Credenciais de provedores nunca pertencem a respostas de API ou contexto de modelos.
Referência OpenAPI ao vivo
A referência abaixo é renderizada diretamente do mesmo objeto OPENAPI_V1 servido por /api/openapi/v1, portanto a documentação de endpoints e o contrato legível por máquina compartilham a mesma fonte.
OpenAPI v1 canônico
/api/openapi/v1| Método | Caminho | Resumo |
|---|---|---|
GET | / | API index and usage rules |
GET | /me | Resolved actor, capabilities, viewer scope and coarse product entitlements |
GET | /surfaces | Blocchi product/domain surfaces with tenant entitlement state |
GET | /metrics | List governed metric/indicator definitions |
POST | /metrics/{indicatorSlug}/query | Compute/query a governed metric with readiness and provenance |
GET | /events | List authorized cross-product business events |
GET | /alerts | List alerts addressed to the current actor |
POST | /alerts/{alertId}/acknowledgement | Acknowledge or unacknowledge one recipient-scoped alert |
GET | /alert-rules | List organization rules and the current actor's personal rules |
POST | /alert-rules | Create a governed personal or Tenant-Admin organization alert rule |
PATCH | /alert-rules/{ruleId} | Update a visible governed alert rule |
DELETE | /alert-rules/{ruleId} | Delete a visible governed alert rule while preserving alert/event history |
GET | /subscriptions | List the current actor's delivery subscriptions |
POST | /subscriptions | Create or update the current actor's alert/event/report subscription |
DELETE | /subscriptions/{subscriptionId} | Delete one subscription owned by the current actor |
GET | /entities | Search canonical entities when the caller's current scope is safely supported |
GET | /entities/{id} | Get authorized canonical entity context and provenance |
GET | /findings | List authorized governed findings; currently includes Data Quality findings |
GET | /findings/{id} | Get one authorized governed finding |
GET | /findings/{id}/evidence | Get authorized structured evidence behind a finding |
GET | /sources | List authorized governed source datasets and sync health; never returns provider credentials |
POST | /sources/{datasetId}/syncs | Trigger a governed source sync (tenant admin) |
GET | /interview-purposes | List governed reported-evidence interview purposes |
POST | /interviews | Start a purpose-driven reported-evidence interview |
POST | /interviews/{sessionId}/answers | Continue the same actor/purpose/subject-bound interview |
GET | /evidence | List governed business-context evidence when the caller's current scope is safely supported |
Última atualização em