API Reference
Gateway routes
Every route below is defined in services/api-gateway/src/routes/ and proxied to the downstream service noted in each section. Paths are relative to the gateway base URL.
On this page
Health
/Liveness probe for the API gateway. No authentication required.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /health | Returns gateway status, version, and environment. | None |
Authentication
/authJWT issuance, refresh rotation, OAuth2 SSO (when configured), and agent credentials.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /auth/oauth/login | Starts OAuth2/OIDC login when OAuth env vars are configured. | None |
| GET | /auth/oauth/callback | OAuth2 callback; sets HttpOnly cookies and redirects to the web app. | None |
| GET | /auth/oauth/session | One-time exchange of HttpOnly OAuth cookie for a JWT access token. | None |
| POST | /auth/login | Email/password login (development and test only; disabled in production). | None |
| POST | /auth/mfa-verify | Completes MFA after login returns requiresMfa (dev/test only). | None |
| POST | /auth/agent-token | OAuth2 client-credentials style token for registered agents. | None (client credentials) |
| GET | /auth/agents | List registered agent credentials. | Bearer JWT (admin) |
| POST | /auth/agents | Register a new agent client. | Bearer JWT (admin) |
| PATCH | /auth/agents/:clientId | Update agent autonomy level. | Bearer JWT (admin) |
| DELETE | /auth/agents/:clientId | Revoke an agent client. | Bearer JWT (admin) |
| POST | /auth/agents/:clientId/rotate | Rotate agent client secret. | Bearer JWT (admin) |
| GET | /auth/agents/stale | List agents whose secrets exceed the rotation threshold. | Bearer JWT (admin) |
| POST | /auth/logout | Blacklist access and refresh token JTIs. | Bearer JWT |
| POST | /auth/refresh | Rotate refresh token and issue a new access token (HttpOnly cookie). | Refresh cookie |
| GET | /auth/me | Return the current JWT payload (userId, email, role, tenantId). | Bearer JWT |
Governance
/governancePipelines, projects, audit log, RBAC, lineage, entitlements, and usage.
Proxied to governance-dashboard :4004
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /governance/pipelines | List pipelines for the tenant. | Bearer JWT (viewer+) |
| POST | /governance/pipelines | Create a pipeline. | Bearer JWT (engineer+) |
| GET | /governance/pipelines/:id | Get pipeline metadata. | Bearer JWT (viewer+) |
| GET | /governance/pipelines/:id/graph | Fetch the pipeline canvas graph. | Bearer JWT (viewer+) |
| PUT | /governance/pipelines/:id/graph | Save the pipeline canvas graph. | Bearer JWT (engineer+) |
| POST | /governance/pipelines/:id/validate | Validate pipeline graph and schema bindings. | Bearer JWT (engineer+) |
| GET | /governance/pipelines/:id/drift | Schema drift status for a pipeline. | Bearer JWT (viewer+) |
| POST | /governance/pipelines/:id/drift/resolve | Resolve drift for a pipeline. | Bearer JWT (admin) |
| GET | /governance/pipelines/:id/lineage | Lineage events for a pipeline. | Bearer JWT (viewer+) |
| GET | /governance/pipelines/:id/checkpoints | Checkpoint history for a pipeline. | Bearer JWT (viewer+) |
| POST | /governance/lineage/invalidate | Invalidate downstream lineage after graph changes. | Bearer JWT (engineer+) |
| GET | /governance/lineage/pipelines/:pipelineId/downstream | Downstream impact for changed nodes. | Bearer JWT (viewer+) |
| GET | /governance/audit-log | Tenant audit log entries. | Bearer JWT (viewer+) |
| GET | /governance/rbac/policies | List RBAC policies. | Bearer JWT (viewer+) |
| POST | /governance/rbac/policies | Create an RBAC policy. | Bearer JWT (admin) |
| PUT | /governance/rbac/policies/:id | Update an RBAC policy. | Bearer JWT (admin) |
| DELETE | /governance/rbac/policies/:id | Delete an RBAC policy. | Bearer JWT (admin) |
| GET | /governance/rbac/effective/:userId | Effective permissions for a user. | Bearer JWT (viewer+) |
| GET | /governance/provenance/object/:id | Provenance walk for an ontology entity. | Bearer JWT (viewer+) |
| GET | /governance/projects | List projects. | Bearer JWT (viewer+) |
| POST | /governance/projects | Create a project. | Bearer JWT (engineer+) |
| GET | /governance/projects/:id | Get project details. | Bearer JWT (viewer+) |
| GET | /governance/entitlements | Current tenant plan and limits. | Bearer JWT (viewer+) |
| POST | /governance/entitlements/admin/:tenantId | Admin provisioning of entitlements. | Bearer JWT (admin) |
| GET | /governance/usage | Usage metrics for the tenant. | Bearer JWT (viewer+) |
Schema
/schemaSchema registry, validation, compatibility checks, and drift.
Proxied to schema-engine :4001
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /schema/registry | List registered schemas. | Bearer JWT |
| GET | /schema/registry/:schemaId/versions | List versions for a schema. | Bearer JWT |
| GET | /schema/registry/:schemaId/:version | Fetch a specific schema version. | Bearer JWT |
| POST | /schema/registry | Register or update a schema. | Bearer JWT (engineer+) |
| POST | /schema/validate | Validate a payload against a registered schema. | Bearer JWT (engineer+) |
| POST | /schema/compatibility | Check backward/forward compatibility between versions. | Bearer JWT (engineer+) |
| GET | /schema/drift/:pipelineId | Schema drift status from the registry perspective. | Bearer JWT |
Ontology
/ontologyObject types, link types, action types, entities, and graph queries.
Proxied to schema-engine :4001
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /ontology/object-types | List object type definitions. | Bearer JWT (viewer+) |
| POST | /ontology/object-types | Create an object type. | Bearer JWT (engineer+) |
| GET | /ontology/object-types/:id | Get an object type. | Bearer JWT (viewer+) |
| PUT | /ontology/object-types/:id | Update an object type. | Bearer JWT (engineer+) |
| DELETE | /ontology/object-types/:id | Delete an object type. | Bearer JWT (engineer+) |
| POST | /ontology/object-types/:id/publish | Publish an object type. | Bearer JWT (engineer+) |
| POST | /ontology/object-types/:id/deprecate | Deprecate an object type. | Bearer JWT (engineer+) |
| GET | /ontology/link-types | List link type definitions. | Bearer JWT (viewer+) |
| POST | /ontology/link-types | Create a link type. | Bearer JWT (engineer+) |
| GET | /ontology/link-types/:id | Get a link type. | Bearer JWT (viewer+) |
| PUT | /ontology/link-types/:id | Update a link type. | Bearer JWT (engineer+) |
| DELETE | /ontology/link-types/:id | Delete a link type. | Bearer JWT (engineer+) |
| POST | /ontology/link-types/:id/publish | Publish a link type. | Bearer JWT (engineer+) |
| GET | /ontology/action-types | List action type definitions. | Bearer JWT (viewer+) |
| POST | /ontology/action-types | Create an action type. | Bearer JWT (engineer+) |
| GET | /ontology/action-types/:id | Get an action type. | Bearer JWT (viewer+) |
| PUT | /ontology/action-types/:id | Update an action type. | Bearer JWT (engineer+) |
| DELETE | /ontology/action-types/:id | Delete an action type. | Bearer JWT (engineer+) |
| POST | /ontology/action-types/:id/publish | Publish an action type. | Bearer JWT (engineer+) |
| POST | /ontology/validate | Dry-run ontology definition validation. | Bearer JWT (engineer+) |
| GET | /ontology/graph | Ontology type graph (nodes and edges). | Bearer JWT (viewer+) |
| GET | /ontology/graph/neighbors/:objectTypeId | Neighbor types for an object type. | Bearer JWT (viewer+) |
| GET | /ontology/graph/path | Shortest path between object types. | Bearer JWT (viewer+) |
| GET | /ontology/entities | List entity instances. | Bearer JWT (viewer+) |
| POST | /ontology/entities | Create an entity instance. | Bearer JWT (engineer+) |
| GET | /ontology/entities/:id | Get an entity instance. | Bearer JWT (viewer+) |
| GET | /ontology/entities/by-type/:objectTypeId | Entities filtered by object type. | Bearer JWT (viewer+) |
| GET | /ontology/entities/:id/neighbors | Linked entity neighbors. | Bearer JWT (viewer+) |
| POST | /ontology/actions/:id/execute | Execute a governed action type. | Bearer JWT (engineer+) |
| GET | /ontology/completeness | Ontology completeness metrics. | Bearer JWT (viewer+) |
Pipeline execution
/pipelineDAG validation, execution, schedules, streams, and node catalog.
Proxied to pipeline-core :4003
| Method | Path | Description | Auth |
|---|---|---|---|
| POST | /pipeline/execute | Execute a pipeline synchronously. | Bearer JWT (engineer+) |
| POST | /pipeline/execute/async | Enqueue async pipeline execution. | Bearer JWT (engineer+) |
| GET | /pipeline/execute/jobs/:id | Poll async job status. | Bearer JWT (viewer+) |
| POST | /pipeline/validate-dag | Validate a pipeline DAG structure. | Bearer JWT (engineer+) |
| POST | /pipeline/invalidate-downstream | Invalidate downstream execution cache. | Bearer JWT (engineer+) |
| GET | /pipeline/nodes/types | Available canvas node types. | Bearer JWT (viewer+) |
| POST | /pipeline/schedules | Create a pipeline schedule. | Bearer JWT (engineer+) |
| GET | /pipeline/schedules | List pipeline schedules. | Bearer JWT (viewer+) |
| GET | /pipeline/schedules/:id | Get schedule details. | Bearer JWT (viewer+) |
| DELETE | /pipeline/schedules/:id | Delete a schedule. | Bearer JWT (engineer+) |
| PATCH | /pipeline/schedules/:id/toggle | Enable or disable a schedule. | Bearer JWT (engineer+) |
| POST | /pipeline/evals/run | Run LLM node evaluation harness. | Bearer JWT (engineer+) |
| POST | /pipeline/streams/:topic/publish | Publish to an event stream topic. | Bearer JWT (engineer+) |
| GET | /pipeline/streams/:topic/depth | Stream topic depth. | Bearer JWT (viewer+) |
| POST | /pipeline/streams/subscriptions | Create a stream subscription. | Bearer JWT (engineer+) |
| GET | /pipeline/streams/subscriptions | List stream subscriptions. | Bearer JWT (viewer+) |
| DELETE | /pipeline/streams/subscriptions/:id | Delete a stream subscription. | Bearer JWT (engineer+) |
Sandboxes
/sandboxesIsolated pipeline workspaces with propose, review, merge, and revert.
Proxied to sandbox-manager :4002
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /sandboxes | List sandboxes. | Bearer JWT (viewer+) |
| POST | /sandboxes | Create a sandbox. | Bearer JWT (engineer+) |
| POST | /sandboxes/ontology-bootstrap | Bootstrap an ontology sandbox. | Bearer JWT (engineer+) |
| GET | /sandboxes/:id | Get sandbox details. | Bearer JWT (viewer+) |
| PUT | /sandboxes/:id/snapshot | Update sandbox snapshot. | Bearer JWT (engineer+) |
| DELETE | /sandboxes/:id | Delete a sandbox. | Bearer JWT (engineer+) |
| POST | /sandboxes/:id/propose | Propose sandbox changes for review. | Bearer JWT (engineer+) |
| GET | /sandboxes/:id/proposal | Get current proposal. | Bearer JWT (viewer+) |
| POST | /sandboxes/:id/proposal/review | Approve or reject a proposal. | Bearer JWT (reviewer+) |
| POST | /sandboxes/:id/proposal/merge | Merge an approved proposal. | Bearer JWT (engineer+) |
| POST | /sandboxes/:id/proposal/revert | Revert a merged proposal. | Bearer JWT (engineer+) |
| GET | /sandboxes/pipelines/:id/history | Sandbox history for a pipeline. | Bearer JWT (viewer+) |
| GET | /sandboxes/pipelines/:id/active-sandboxes | Active sandboxes for a pipeline. | Bearer JWT (viewer+) |
Connectors
/connectorsSaved connections (governance-dashboard) and connector-framework operations.
Proxied to governance-dashboard :4004, connector-framework :4005
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /connectors | List saved connector connections. | Bearer JWT (viewer+) |
| POST | /connectors | Create a connector connection. | Bearer JWT (engineer+) |
| GET | /connectors/:id | Get a connector connection. | Bearer JWT (viewer+) |
| DELETE | /connectors/:id | Delete a connector connection. | Bearer JWT (engineer+) |
| GET | /connectors/types/available | Available connector types from connector-framework. | Bearer JWT (viewer+) |
| POST | /connectors/:id/test | Test a saved connection. | Bearer JWT (viewer+) |
Tenants
/tenantsWorkspace provisioning and tenant metadata.
Proxied to governance-dashboard :4004
| Method | Path | Description | Auth |
|---|---|---|---|
| POST | /tenants | Create a tenant workspace. | Bearer JWT (viewer+) |
| GET | /tenants/:id | Get tenant details (members only). | Bearer JWT (viewer+) |
| PATCH | /tenants/:id | Update tenant metadata. | Bearer JWT (viewer+) |