rest-api.md

title	REST API reference
description	Generated from the committed OpenAPI 3.1 contract.

REST API reference

Generated from dist/openapi.json by scripts/gen_api_reference.py — do not edit by hand. Regenerate with task docs:api (or python scripts/gen_api_reference.py). The spec itself is drift-gated in CI.

AgentContextOS Gateway · version 0.10.0 · OpenAPI 3.1

Endpoints

agent

POST /v1/agent

Run an agent loop over a goal, streaming events as SSE

Drive the agent loop for body.goal and stream its events.

See agent.md.

Request body (application/json): AgentRequest (required)

Responses

Status	Schema	Description
200	object	SSE stream of AgentEvent frames (text/event-stream).
400	—	Invalid request body
401	—	Missing or invalid auth
422	HTTPValidationError	Validation Error

audit

GET /v1/audit

The tenant's own audit events, newest-first (Step 6.6)

Return the calling tenant's audit events (tamper-evident hash chain).

Name	In	Required	Type	Description
limit	query	no	integer
action	query	no	—
outcome	query	no	—

Responses

Status	Schema	Description
200	AuditListResponse	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	Audit read API disabled
422	HTTPValidationError	Validation Error

POST /v1/audit/export

Signed WORM export of the tenant's audit log (Step 6.6b)

Return a self-verifying export bundle of the calling tenant's events.

The bundle is content-hashed and (when cfg.audit.export_secret is set) HMAC-signed, so a consumer verifies it offline; chain_verified attests the source log's whole-log hash chain was intact at export time. It is the artifact an operator archives to immutable (WORM) storage.

Responses

Status	Schema	Description
200	AuditExport	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	Audit read API disabled

GET /v1/audit/verify

Whole-log hash-chain integrity check (Step 6.6)

Verify the whole-log SHA-256 hash chain — True iff no link was altered.

Responses

Status	Schema	Description
200	AuditVerifyResponse	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	Audit read API disabled

compliance

POST /v1/compliance/erase

Erase the calling tenant's data — GDPR right-to-erasure (Step 6.10)

Erase (or, by default, preview) the calling tenant's data across all stores.

Returns an :class:ErasureResult with per-data-class counts. Deletes only when dry_run=false and confirm=true; otherwise it is a counting preview (dry_run=true in the result).

Request body (application/json): ComplianceEraseRequest (required)

Responses

Status	Schema	Description
200	ErasureResult	Successful Response
401	GatewayError	Missing or invalid auth
422	HTTPValidationError	Validation Error

corpora

GET /v1/corpora

List corpora visible to the calling tenant

Return every corpus the calling principal can read.

See docs/reference/gateway.md for the response shape + pagination semantics (paging is a Phase 3.x add — v0 returns everything visible).

Responses

Status	Schema	Description
200	CorpusList	Successful Response
401	GatewayError	Missing or invalid auth

GET /v1/corpora/{corpus_id}

Describe a single corpus

Return metadata for one corpus, or 404 if not visible.

Cross-tenant lookups (the corpus exists in a different tenant) return 404 deliberately — the response shape doesn't distinguish "not found" from "not visible" so attackers can't probe for other tenants' corpora.

Name	In	Required	Type	Description
corpus_id	path	yes	string

Responses

Status	Schema	Description
200	Corpus	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	Corpus not found / not visible
422	HTTPValidationError	Validation Error

feedback

POST /v1/feedback

Submit explicit feedback or an implicit signal about a query

Request body (application/json): FeedbackRequest (required)

Responses

Status	Schema	Description
200	FeedbackAck	Successful Response
422	GatewayError	Invalid signal / rating

health

GET /healthz

Healthz

Responses

Status	Schema	Description
200	object	Successful Response

GET /readyz

Readyz

Readiness probe — all wiring happens in the app factory, so a served response means the app is fully constructed and routable.

Responses

Status	Schema	Description
200	object	Successful Response

GET /v1/info

Info

Responses

Status	Schema	Description
200	object	Successful Response

ingest

POST /v1/ingest/document

Ingest Document

Single-document ingest — multipart upload (Step 1.10).

Request body (multipart/form-data): Body_ingest_document_v1_ingest_document_post (required)

Responses

Status	Schema	Description
200	IngestResult	Successful Response
422	HTTPValidationError	Validation Error

openai

POST /v1/chat/completions

Create a chat completion with retrieval pre-fetch (OpenAI-compatible)

RAG chat completion: retrieve → inject context → generate.

See openai-compat.md.

Request body (application/json): ChatCompletionRequest (required)

Responses

Status	Schema	Description
200	ChatCompletionResponse	Successful Response
400	OpenAIError	Invalid request
401	OpenAIError	Missing or invalid auth
403	OpenAIError	ACL denied
422	HTTPValidationError	Validation Error
429	OpenAIError	Rate limit exceeded
502	OpenAIError	Downstream retrieval / LLM failure

POST /v1/embeddings

Create embeddings (OpenAI-compatible)

Embed text via the wired Embedder SPI.

See openai-compat.md.

Request body (application/json): EmbeddingsRequest (required)

Responses

Status	Schema	Description
200	EmbeddingsResponse	Successful Response
400	OpenAIError	Invalid request
401	OpenAIError	Missing or invalid auth
422	HTTPValidationError	Validation Error
429	OpenAIError	Quota / rate limit exceeded

GET /v1/models

List models (OpenAI-compatible) — reports the wired LLM + embedder

Advertise the wired LLM + embedder under OpenAI's model-list shape.

Many OpenAI clients call this on startup to validate the endpoint. The ids are the wired backends' canonical model names plus a rag-gateway alias clients can target generically.

Responses

Status	Schema	Description
200	ModelList	Successful Response

queries

POST /v1/query

Full RAG query: retrieve → rerank → pack → optional LLM answer

End-to-end RAG query.

Runs the Phase 2 pipeline in sequence — understanding, router, optional rerank, optional pack, optional LLM — and returns the combined evidence envelope. See docs/reference/gateway.md.

Request body (application/json): QueryRequest (required)

Responses

Status	Schema	Description
200	QueryResponse	Successful Response
400	GatewayError	Invalid request body
401	GatewayError	Missing or invalid auth
403	GatewayError	ACL denied
422	HTTPValidationError	Validation Error
429	GatewayError	Tenant rate limit exceeded
502	GatewayError	Downstream retrieval failure

GET /v1/query/{request_id}/trace

Per-query provenance + captured span trace (Step 5.1)

Return the signed provenance record + captured spans for a query.

Tenant identity comes from request headers (Authorization / X-Tenant-Id); a record is returned only to the tenant that produced it. 404 when the id is unknown to the tenant or provenance is disabled.

Name	In	Required	Type	Description
request_id	path	yes	string

Responses

Status	Schema	Description
200	QueryTraceResponse	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	No provenance for this query id
422	HTTPValidationError	Validation Error

POST /v1/retrieve

Retrieval-only: understanding + router; no rerank / pack / LLM

Retrieval-only subset of /v1/query.

Useful when the caller brings their own reranker / packer / LLM and just wants the policy-checked, fused chunk-ref list.

Request body (application/json): RetrieveRequest (required)

Responses

Status	Schema	Description
200	RetrieveResponse	Successful Response
400	GatewayError	Invalid request body
401	GatewayError	Missing or invalid auth
403	GatewayError	ACL denied
422	HTTPValidationError	Validation Error
502	GatewayError	Downstream retrieval failure

scim

GET /scim/v2/Groups

List Groups

Name	In	Required	Type	Description
startIndex	query	no	integer
count	query	no	integer
filter	query	no	—

Responses

Status	Schema	Description
200	ScimListResponse	Successful Response
422	HTTPValidationError	Validation Error

POST /scim/v2/Groups

Create Group

Request body (application/json): ScimGroup (required)

Responses

Status	Schema	Description
201	ScimGroup	Successful Response
422	HTTPValidationError	Validation Error

GET /scim/v2/Groups/{group_id}

Get Group

Name	In	Required	Type	Description
group_id	path	yes	string

Responses

Status	Schema	Description
200	ScimGroup	Successful Response
422	HTTPValidationError	Validation Error

PUT /scim/v2/Groups/{group_id}

Replace Group

Name	In	Required	Type	Description
group_id	path	yes	string

Request body (application/json): ScimGroup (required)

Responses

Status	Schema	Description
200	ScimGroup	Successful Response
422	HTTPValidationError	Validation Error

DELETE /scim/v2/Groups/{group_id}

Delete Group

Name	In	Required	Type	Description
group_id	path	yes	string

Responses

Status	Schema	Description
204	—	Successful Response
422	HTTPValidationError	Validation Error

GET /scim/v2/ResourceTypes

Resource Types

Responses

Status	Schema	Description
200	object	Successful Response

GET /scim/v2/ServiceProviderConfig

Service Provider Config

Responses

Status	Schema	Description
200	object	Successful Response

GET /scim/v2/Users

List Users

Name	In	Required	Type	Description
startIndex	query	no	integer
count	query	no	integer
filter	query	no	—

Responses

Status	Schema	Description
200	ScimListResponse	Successful Response
422	HTTPValidationError	Validation Error

POST /scim/v2/Users

Create User

Request body (application/json): ScimUser (required)

Responses

Status	Schema	Description
201	ScimUser	Successful Response
422	HTTPValidationError	Validation Error

GET /scim/v2/Users/{user_id}

Get User

Name	In	Required	Type	Description
user_id	path	yes	string

Responses

Status	Schema	Description
200	ScimUser	Successful Response
422	HTTPValidationError	Validation Error

PUT /scim/v2/Users/{user_id}

Replace User

Name	In	Required	Type	Description
user_id	path	yes	string

Request body (application/json): ScimUser (required)

Responses

Status	Schema	Description
200	ScimUser	Successful Response
422	HTTPValidationError	Validation Error

PATCH /scim/v2/Users/{user_id}

Patch User

Name	In	Required	Type	Description
user_id	path	yes	string

Request body (application/json): ScimPatchOp (required)

Responses

Status	Schema	Description
200	ScimUser	Successful Response
422	HTTPValidationError	Validation Error

DELETE /scim/v2/Users/{user_id}

Delete User

Name	In	Required	Type	Description
user_id	path	yes	string

Responses

Status	Schema	Description
204	—	Successful Response
422	HTTPValidationError	Validation Error

status

GET /v1/billing/usage

Billing Usage

One tenant's accrued metered usage for the current billing period (Step 7.9).

Tenant resolves from the tenant_id query param, else the X-Tenant-Id header, else "default". Empty when no usage meter is wired (billing disabled). Read-only — metering never rejects a request.

Name	In	Required	Type	Description
tenant_id	query	no	—

Responses

Status	Schema	Description
200	BillingUsageResponse	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/connectors/status

Connectors Status

Responses

Status	Schema	Description
200	ConnectorsStatusResponse	Successful Response

GET /v1/status/breakers

Status Breakers

List every per-backend circuit breaker + its current state (Step 4.4).

Responses

Status	Schema	Description
200	BreakersStatusResponse	Successful Response

POST /v1/status/breakers/{name}/force-close

Force Close Breaker

Force one circuit breaker CLOSED — the operator one-click recovery (Step 4.4).

404 when no breaker registry is wired or the name is unknown. If the backend is still unhealthy the breaker simply re-trips on the next failure run; this just gives an operator an immediate retry without waiting out reset_timeout_s.

Name	In	Required	Type	Description
name	path	yes	string

Responses

Status	Schema	Description
200	BreakerActionResponse	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/compliance

Status Compliance

The live compliance posture (Step 6.10).

Reports which governance controls are enabled (audit / ACL / PII / BYOK / SSO / SCIM / quotas / retention / residency), the deployment's data region, and the retention windows — the machine-readable backing for the SOC 2 / GDPR control-mapping docs. Carries only configuration booleans, no tenant data, so it is safe on the status surface.

Responses

Status	Schema	Description
200	CompliancePosture	Successful Response

GET /v1/status/cost

Status Cost

One tenant's recent-spend anomaly verdict (Step 5.6c).

Tenant resolves from the tenant_id query param, else the X-Tenant-Id header, else "default". Returns insufficient_data when cost tracking is disabled or the tenant has seen too few requests. Detection only — never rejects a request.

Name	In	Required	Type	Description
tenant_id	query	no	—

Responses

Status	Schema	Description
200	CostStatusResponse	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/drift

Status Drift

Drift report across the five monitors (Step 5.5).

Infra-scoped (no tenant). Computing the report also emits drift.detected for any monitor that has newly crossed its threshold (idempotent per transition). Empty when drift is disabled.

Responses

Status	Schema	Description
200	DriftReport	Successful Response

POST /v1/status/drift/{metric}/rebaseline

Rebaseline Drift

Promote a monitor's current window to its reference — "accept the new normal".

The operator one-click "this is the new baseline" — 404 when drift is disabled, 400 on an unknown metric. Returns the post-rebaseline snapshot.

Name	In	Required	Type	Description
metric	path	yes	string

Responses

Status	Schema	Description
200	DriftSnapshot	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/experiments

Status Experiments

A/B experiment comparisons — control vs candidate per experiment (Step 5.7).

Composes the per-variant sample windows held by the experiment_tracker with the pure analyze_ab_experiment (lift + confidence interval). Empty when experiments are disabled; a comparison below min_samples on either side reports insufficient_data.

Responses

Status	Schema	Description
200	ExperimentsStatusResponse	Successful Response

GET /v1/status/feedback

Status Feedback

One tenant's aggregate feedback for the dashboard (Step 5.4).

Tenant resolves from the tenant_id query param, else the X-Tenant-Id header, else "default". Returns a zeroed :class:~rag_core.types.FeedbackStats when feedback is disabled or the tenant has none yet.

Name	In	Required	Type	Description
tenant_id	query	no	—

Responses

Status	Schema	Description
200	FeedbackStats	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/health

Status Health

Responses

Status	Schema	Description
200	HealthResponse	Successful Response

GET /v1/status/logs

Status Logs

Name	In	Required	Type	Description
limit	query	no	integer
level	query	no	—
event	query	no	—
tenant	query	no	—

Responses

Status	Schema	Description
200	LogsResponse	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/logs/stream

Status Logs Stream

Name	In	Required	Type	Description
level	query	no	—
event	query	no	—
tenant	query	no	—
interval_ms	query	no	integer
backlog	query	no	integer

Responses

Status	Schema	Description
200	object	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/metrics

Status Metrics

Responses

Status	Schema	Description
200	MetricsResponse	Successful Response

GET /v1/status/quotas

Status Quotas

One tenant's quota usage across every dimension (Step 4.5).

Tenant resolves from the tenant_id query param, else the X-Tenant-Id header, else "default". Empty when quotas are off.

Name	In	Required	Type	Description
tenant_id	query	no	—

Responses

Status	Schema	Description
200	QuotasStatusResponse	Successful Response
422	HTTPValidationError	Validation Error

POST /v1/status/quotas/{tenant_id}/reset

Reset Quota

Clear a tenant's usage on one dimension (?dimension=qps) or all (Step 4.5).

The operator one-click "give them headroom now" — 404 when quotas are off, 400 on an unknown dimension. Returns the post-reset snapshot.

Name	In	Required	Type	Description
tenant_id	path	yes	string
dimension	query	no	—

Responses

Status	Schema	Description
200	QuotaActionResponse	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/sso

Status Sso

SSO / SCIM posture for the calling tenant (Step 6.8).

Reports whether identity federation (cfg.sso) and SCIM provisioning (cfg.scim) are enabled on the gateway, plus whether this tenant has an IdP configured and which protocol it speaks. Tenant-scoped — it never lists other tenants' config. Tenant resolves from the tenant_id query param, else the X-Tenant-Id header, else the gateway default.

Name	In	Required	Type	Description
tenant_id	query	no	—

Responses

Status	Schema	Description
200	SsoStatusResponse	Successful Response
422	HTTPValidationError	Validation Error

GET /v1/status/tenant

Status Tenant

Resolved per-tenant logical-tenancy settings (Step 6.1).

Surfaces what the TenantResolver resolves for a tenant — its namespace, PII action, and ACL labels — so an operator can see the effective config a tenant's requests run under. Tenant resolves from the tenant_id query param, else the X-Tenant-Id header, else the gateway default. Reports safe defaults (known=false) when the tenant is absent from rag.yaml or no resolver is wired.

Name	In	Required	Type	Description
tenant_id	query	no	—

Responses

Status	Schema	Description
200	TenantStatusResponse	Successful Response
422	HTTPValidationError	Validation Error

webhooks

GET /v1/webhooks/subscriptions

List webhook subscriptions (secrets masked)

Responses

Status	Schema	Description
200	SubscriptionList	Successful Response
401	GatewayError	Missing or invalid auth

POST /v1/webhooks/subscriptions

Create a webhook subscription (signing secret returned once)

Request body (application/json): CreateSubscriptionRequest (required)

Responses

Status	Schema	Description
201	WebhookSubscription	Successful Response
401	GatewayError	Missing or invalid auth
422	HTTPValidationError	Validation Error

GET /v1/webhooks/subscriptions/{subscription_id}

Describe a subscription (secret masked)

Name	In	Required	Type	Description
subscription_id	path	yes	string

Responses

Status	Schema	Description
200	WebhookSubscription	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	Subscription not found
422	HTTPValidationError	Validation Error

DELETE /v1/webhooks/subscriptions/{subscription_id}

Delete a subscription

Name	In	Required	Type	Description
subscription_id	path	yes	string

Responses

Status	Schema	Description
204	—	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	Subscription not found
422	HTTPValidationError	Validation Error

POST /v1/webhooks/subscriptions/{subscription_id}/test

Send a synthetic test event to a subscription

Name	In	Required	Type	Description
subscription_id	path	yes	string

Responses

Status	Schema	Description
200	WebhookTestResult	Successful Response
401	GatewayError	Missing or invalid auth
404	GatewayError	Subscription not found
422	HTTPValidationError	Validation Error