API Endpoints

All endpoints are served from the control plane on port 3001 (HTTP) and 3002 (gRPC).

System (Public, No Auth Required)

Method	Path	Description
GET	/healthz	Health check
GET	/readyz	Readiness check
GET	/openapi.json	OpenAPI specification

Identity

Method	Path	Description
GET	/v1/me	Current principal
GET	/v1/me/organizations	My organizations
GET	/v1/me/teams	My teams
GET	/v1/me/permissions	Effective permissions

Tenancy

Method	Path	Description
POST	/v1/organizations	Create organization
GET	/v1/organizations/{id}	Get organization
GET	/v1/organizations/{id}/teams	List teams
GET	/v1/organizations/{id}/members	List members
POST	/v1/teams	Create team (RBAC enforced)
GET	/v1/teams/{id}	Get team
POST	/v1/invitations	Create invitation (RBAC enforced)
POST	/v1/invitations/{id}/accept	Accept invitation
POST	/v1/invitations/{id}/revoke	Revoke invitation

Authorization

Method	Path	Description
POST	/v1/authz/check	Single permission check
POST	/v1/authz/check-batch	Batch permission check

Jobs

Method	Path	Description
POST	/v1/jobs	Submit a job (with idempotency key, cost estimate)
GET	/v1/jobs/{id}	Get job by canonical job_id
GET	/v1/jobs	List jobs
GET	/v1/jobs/{id}/usage	Job cost/usage roll-up
GET	/v1/jobs/{id}/events	Per-job event stream (SSE)

Workflows

Method	Path	Description
POST	/v1/workflow-definitions	Create definition (supports NodeDefinition schema)
GET	/v1/workflow-definitions	List definitions
POST	/v1/workflow-runs	Create run (with idempotency key)
GET	/v1/workflow-runs/{id}	Get run status
POST	/v1/workflow-runs/{id}/start	Start execution
POST	/v1/workflow-runs/{id}/cancel	Cancel run
GET	/v1/workflow-runs/{id}/events	Per-run event stream (SSE)

Providers

Method	Path	Description
GET	/v1/providers	List available providers and capabilities
POST	/v1/providers/execute	Execute a provider request
POST	/v1/providers/execute/stream	Execute with SSE token streaming
POST	/v1/providers/estimate	Cost estimation

API Keys

Method	Path	Description
POST	/v1/api-keys	Create key (returns raw key once)
GET	/v1/api-keys	List keys
GET	/v1/api-keys/{id}	Get key metadata
DELETE	/v1/api-keys/{id}	Revoke key
POST	/v1/api-keys/{id}/disable	Disable key

Assets

Method	Path	Description
POST	/v1/assets	Upload asset
GET	/v1/assets/{id}	Download asset

Usage & Cost

Method	Path	Description
GET	/v1/organizations/{id}/usage	Usage summary with breakdowns
GET	/v1/organizations/{id}/usage/records	Detailed usage records

Audit

Method	Path	Description
GET	/v1/organizations/{id}/audit-logs	Org audit trail
GET	/v1/audit-logs	Global audit logs

Events

Method	Path	Description
GET	/v1/events/stream	All events (SSE)
GET	/v1/events/ws	All events (WebSocket)
GET	/v1/jobs/{id}/events	Per-job events (SSE)
GET	/v1/workflow-runs/{id}/events	Per-run events (SSE)

Response Envelope

Every response follows the standard envelope format:

{
  "meta": {
    "request_id": "uuid",
    "trace_id": "uuid",
    "timestamp": "2026-03-19T12:00:00Z",
    "status": 200,
    "version": "1.0"
  },
  "context": {
    "principal_id": "uuid",
    "organization_id": "uuid",
    "team_id": null
  },
  "data": { ... },
  "error": null,
  "links": { ... }
}

Error responses:

{
  "meta": { "status": 403, ... },
  "data": null,
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions"
  }
}