REST API
The durable headless integration contract for canonical Blocchi context and decisions.
The versioned API lives under /api/v1. The machine-readable OpenAPI document is exposed at /api/openapi/v1.
Authentication
Today the headless boundary accepts an authenticated Blocchi browser session or a valid Supabase bearer token. Blocchi-issued developer key management is a separate credential surface and should only be treated as available when it is exposed in the product.
Authentication does not imply tenant-wide access. Tenant role, viewer scope, product entitlement and capability-specific authorization remain authoritative.
Contract rules
- Canonical Blocchi IDs and concepts are the public contract, not provider-native schemas.
- A null metric with blocked or unknown readiness is not zero.
- Evidence and provenance are first-class.
- Business events and alerts are source-of-truth records; notification delivery is a receipt.
- Consequential commands are capability-gated and can require explicit confirmation.
- Provider credentials never belong in API responses or model context.
Live OpenAPI reference
The reference below is rendered directly from the same OPENAPI_V1 object served by /api/openapi/v1, so endpoint documentation and the machine-readable contract share one source.
Canonical OpenAPI v1
/api/openapi/v1| Method | Path | Summary |
|---|---|---|
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 |
Last updated on