REST endpoints (narrative)
Grouped by concern. Prefer the OpenAPI explorer for request/response shapes; this page gives you the mental map.
Auth
| Method |
Path |
Role |
Purpose |
| POST |
/api/v1/auth/login |
public |
Username/password → JWT (local dev only) |
| POST |
/api/v1/auth/logout |
viewer |
Invalidate token |
| GET |
/api/v1/auth/whoami |
viewer |
Decode current token; return user claims |
| POST |
/api/v1/auth/refresh |
viewer |
Refresh access token |
| GET |
/api/v1/auth/oidc/login |
public |
Start OIDC flow; 302 to IdP |
| GET |
/api/v1/auth/oidc/callback |
public |
IdP callback; issue JWT |
| PUT |
/api/v1/auth/oidc/config |
admin |
Configure IdP (issuer, client_id, …) |
See How-to: Set up OIDC SSO.
Pipelines
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/pipelines |
viewer |
List runs (filter by state, template, compliance) |
| POST |
/api/v1/pipelines |
operator |
Start a new run |
| GET |
/api/v1/pipelines/{run_id} |
viewer |
Run status + phase + active agent |
| GET |
/api/v1/pipelines/{run_id}/events |
viewer |
run_events journal (SQL-queryable) |
| GET |
/api/v1/pipelines/{run_id}/artifacts |
viewer |
List produced artefacts (models, reports, PDF) |
| POST |
/api/v1/pipelines/{run_id}/cancel |
operator |
Soft-cancel |
| POST |
/api/v1/pipelines/{run_id}/resume |
operator |
Resume crashed/paused |
| WS |
/api/v1/pipelines/{run_id}/stream |
viewer |
Live event stream |
Agents
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/agents |
viewer |
List all (built-in + plugin-contributed) |
| GET |
/api/v1/agents/{name} |
viewer |
Definition (role, tools, rules, model_tier) |
| POST |
/api/v1/agents/{name}/invoke |
operator |
Ad-hoc invocation (outside a pipeline) |
| GET |
/api/v1/agents/tools |
viewer |
List of all tools available to any agent |
Deployments
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/deployments |
viewer |
List models + versions + status |
| POST |
/api/v1/deployments/package |
operator |
Build OCI image from run_id |
| POST |
/api/v1/deployments/shadow-start |
operator |
Start shadow-traffic comparison |
| GET |
/api/v1/deployments/{model}/shadow-status |
viewer |
Shadow metrics |
| POST |
/api/v1/deployments/compare |
operator |
Champion vs challenger report |
| POST |
/api/v1/deployments/promote |
operator |
Promote (raises HITL gate) |
| POST |
/api/v1/deployments/rollback |
operator |
Instant rollback |
| POST |
/api/v1/deployments/retire |
operator |
Retire a version |
| POST |
/api/v1/deployments/audit |
operator |
Generate promotion audit PDF |
| WS |
/api/v1/deployments/{model}/events |
viewer |
Shadow + drift alerts stream |
See How-to: Deploy a model.
Plugins
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/plugins |
viewer |
List installed |
| GET |
/api/v1/plugins/{name} |
viewer |
Plugin detail incl. install_drops |
| POST |
/api/v1/plugins |
admin |
Install from path |
| POST |
/api/v1/plugins/{name}/reload |
admin |
Re-scan + re-register |
| DELETE |
/api/v1/plugins/{name} |
admin |
Uninstall + clean up every surface |
| GET |
/api/v1/plugins/commands |
viewer |
List slash-commands (from all plugins) |
| POST |
/api/v1/plugins/commands/{qname}/invoke |
operator |
Render + invoke a command |
| GET |
/api/v1/plugins/agents |
viewer |
List plugin-contributed agents |
| GET |
/api/v1/plugins/agents/{qname} |
viewer |
Plugin agent detail |
Permissions / audit
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/permissions/denials |
viewer |
Query denial log (filter by agent, tool, source, since) |
| GET |
/api/v1/permissions/rules |
viewer |
All active rules per source |
| GET |
/api/v1/approvals |
viewer |
HITL gates (pending + historical) |
| POST |
/api/v1/approvals/{gate_id}/approve |
operator |
Approve with optional comment |
| POST |
/api/v1/approvals/{gate_id}/reject |
operator |
Reject with reason |
See Concepts: Permissions & audit.
Cron
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/cron/jobs |
viewer |
List jobs |
| POST |
/api/v1/cron/jobs |
admin |
Create |
| GET |
/api/v1/cron/jobs/{id} |
viewer |
Detail |
| PUT |
/api/v1/cron/jobs/{id} |
admin |
Update (schedule, config, enabled) |
| DELETE |
/api/v1/cron/jobs/{id} |
admin |
Delete |
| POST |
/api/v1/cron/jobs/{id}/run |
admin |
Run-now (bypass schedule) |
| GET |
/api/v1/cron/jobs/{id}/runs |
viewer |
Run history |
See How-to: Schedule a drift check.
Batch
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/batch |
viewer |
List batch runs |
| POST |
/api/v1/batch/{run_id} |
operator |
Submit batch (JSONL body) |
| GET |
/api/v1/batch/{run_id}/status |
viewer |
Status + progress |
| POST |
/api/v1/batch/{run_id}/resume |
operator |
Resume crashed |
| GET |
/api/v1/batch/{run_id}/results |
viewer |
Stream results JSONL |
| GET |
/api/v1/batch/{run_id}/stats |
viewer |
Aggregated tool-usage stats |
| WS |
/api/v1/batch/{run_id}/stream |
viewer |
Progress events |
Features (feature flags)
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/features |
viewer |
List all flags with current values |
| GET |
/api/v1/features/{name} |
viewer |
Single flag detail |
| PUT |
/api/v1/features/{name} |
admin |
Set runtime value |
| DELETE |
/api/v1/features/{name} |
admin |
Reset to default |
Datasets + knowledge
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/datasets |
viewer |
List available datasets |
| GET |
/api/v1/datasets/{name}/profile |
viewer |
Auto-profile (types, cardinality, distributions) |
| POST |
/api/v1/knowledge/search |
viewer |
RAG knowledge search |
Evaluations
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/evaluations |
viewer |
List eval reports |
| POST |
/api/v1/evaluations |
operator |
Run eval on a model + dataset |
Chat
| Method |
Path |
Role |
Purpose |
| POST |
/api/v1/chat |
operator |
Send message to a running pipeline (if chat mode enabled) |
Inference
| Method |
Path |
Role |
Purpose |
| POST |
/api/v1/inference/{model} |
operator |
Single-prediction call against a deployed model |
Docs + health
| Method |
Path |
Role |
Purpose |
| GET |
/healthz |
public |
Liveness — always returns 200 if process alive |
| GET |
/livez |
public |
Detailed health (DB, disk, …) |
| GET |
/metrics |
public |
Prometheus format |
| GET |
/docs |
viewer |
Swagger UI |
| GET |
/redoc |
viewer |
ReDoc |
| GET |
/openapi.json |
viewer |
OpenAPI spec |
MCP
| Method |
Path |
Role |
Purpose |
| GET |
/api/v1/mcp/servers |
viewer |
List connected MCP servers |
| GET |
/api/v1/mcp/tools |
viewer |
All tools exposed via MCP |
Next
- OpenAPI explorer — full request / response shapes
- CLI — higher-level wrapper around these endpoints