HTTP API reference

The HTTP API is rooted at /api/v1. The generated OpenAPI document is served at:

GET /api/v1/openapi.json

Envelopes

JSON API responses use:

{
  "data": {},
  "error": null,
  "meta": {}
}

Errors use the diagnostic registry:

{
  "data": null,
  "error": {
    "code": "ORL-3006",
    "message": "permission denied: telemetry:query required",
    "status": 403
  }
}

Public routes

Method	Path
GET	/healthz
GET	/readyz
GET	/internal/metrics
GET	/api/v1/meta
GET	/api/v1/openapi.json
POST	/api/v1/auth/login
GET	/api/v1/auth/oidc/{slug}/start
GET	/api/v1/auth/oidc/{slug}/callback
POST	/api/v1/auth/signup
GET	/api/v1/invitations/{token}
POST	/api/v1/invitations/{token}/accept

Auth routes

Method	Path
POST	/api/v1/auth/logout
GET	/api/v1/auth/me
PATCH	/api/v1/auth/me
POST	/api/v1/auth/password
GET	/api/v1/permissions

Browser sessions use the oriel_session cookie. API tokens use bearer auth. Feature-flag SDK routes use environment-pinned flag keys, also passed as bearer tokens.

Workspace and control routes

Area	Routes
Workspaces	GET/POST /workspaces, PATCH/DELETE /workspaces/{ws}
Members	GET/POST /workspaces/{ws}/members, member delete, grant get/put
Invitations	GET/POST /workspaces/{ws}/invitations, delete by ID
Roles	GET/POST /workspaces/{ws}/roles, role get/patch/delete
Projects	GET/POST /workspaces/{ws}/projects, project patch/delete
Environments	GET/POST/PATCH/DELETE /workspaces/{ws}/projects/{p}/environments...
Onboarding	GET /workspaces/{ws}/projects/{p}/telemetry-status
Services	GET /services, GET/PATCH /services/{name}
Tokens	GET/POST /tokens, DELETE /tokens/{id}
Audit	GET /audit

All workspace-control paths are under:

/api/v1/workspaces/{ws}

Telemetry routes

Method	Path	Purpose
POST	/workspaces/{ws}/query	Run OQL.
POST	/workspaces/{ws}/oql/validate	Validate OQL without running it.
POST	/workspaces/{ws}/oql/explain	Compile OQL and return the query plan shape.
GET	/workspaces/{ws}/traces/{trace_id}	Fetch trace detail.
GET	/workspaces/{ws}/fields	Field autocomplete.
GET	/workspaces/{ws}/exemplars	Metric exemplars.
GET	/workspaces/{ws}/tail	Live tail stream.
GET	/workspaces/{ws}/service-map	Service-map edges.
GET	/workspaces/{ws}/log-patterns	Repeated log body templates for the active window.
GET	/workspaces/{ws}/flamegraph	Folded profile flamegraph (profile_type, optional trace_id).
GET	/workspaces/{ws}/flamegraph/diff	Compare two profile windows in one folded tree.
GET	/workspaces/{ws}/flamegraph/sandwich	Caller and callee neighborhood for one function.
POST	/workspaces/{ws}/contrast	Attribute distribution comparison.
GET	/workspaces/{ws}/usage	Per-project ingest, cardinality, and storage-retention usage report.

Alerting and metadata routes

Area	Routes
Alert rules	GET/POST /alert-rules, get/patch/delete by ID
Alert instances	GET /alert-instances
Silences	GET/POST /silences, delete by ID
Channels	GET/POST /channels, delete by ID, test by ID
Routing policies	GET/POST /routing-policies, get/patch/delete by ID
Saved queries	GET/POST /saved-queries, delete by ID
Query history	GET /query-history
Dashboards	GET/POST /dashboards, get/put/delete by ID
Dashboard versions	GET /dashboards/{id}/versions, get by version, rollback
Annotations	GET/POST /annotations, delete by ID
SLOs	GET/POST /slos, get/put/delete by ID, status, and timeseries
Recording rules	GET/POST /recording-rules, get/put/delete by ID

Feature flag management routes

All feature flag management paths are under:

/api/v1/workspaces/{ws}/projects/{p}

Area	Routes
Flags	GET/POST /flags, GET/PATCH/DELETE /flags/{key}
Targeting	GET/PUT /environments/{e}/flags/{key}, POST /environments/{e}/flags/{key}/promote
Rollout analytics	GET /environments/{e}/flags/{key}/rollout
Server evaluation	POST /environments/{e}/flags/{key}/evaluate
Deferred changes	GET/POST /environments/{e}/flags/{key}/changes
Ramps	GET/POST /environments/{e}/flags/{key}/ramp, pause, resume, abort
Guarded release	GET/PUT/DELETE /environments/{e}/flags/{key}/guarded-release, arm, disarm, events
Prerequisites	GET/PUT /flags/{key}/prerequisites
History	GET /flags/{key}/changes
Segments	GET/POST /segments, GET/PATCH/DELETE /segments/{skey}
SDK keys	POST /flag-keys
Flag changes	GET /flag-changes, approve, reject, cancel by ID
Metrics	GET/POST /metrics, get/put/delete by ID, explain by ID

Experiment routes

Experiment paths are project-scoped under:

/api/v1/workspaces/{ws}/projects/{p}/experiments

Area	Routes
Experiments	GET/POST /, GET/PUT/DELETE /{id}, GET /calculator
Lifecycle	POST /{id}/start, POST /{id}/stop, POST /{id}/archive
Winner	POST /{id}/apply-winner
Goal metrics	GET/PUT /{id}/metrics
Results	GET /{id}/results, GET /{id}/results/timeseries

Feature flag SDK routes

SDK routes authenticate with a flag key minted for one project and environment. They are not authorized by browser sessions or general API tokens.

Method	Path	Purpose
POST	/api/v1/sdk/flags/evaluate/{key}	Evaluate one flag for a context.
POST	/api/v1/sdk/flags/evaluate	Evaluate every non-archived flag for a context.
GET	/api/v1/sdk/flags/ruleset	Fetch the full evaluable ruleset; supports ETag.
GET	/api/v1/sdk/flags/stream	Receive ruleset updates over Server-Sent Events.

OpenFeature OFREP routes

OFREP lives outside /api/v1 and uses protocol response bodies rather than the Oriel envelope. See OpenFeature OFREP reference.

Method	Path
POST	/ofrep/v1/evaluate/flags
POST	/ofrep/v1/evaluate/flags/{key}