API Reference

Krios exposes four API surfaces.

Surface	Path	Purpose
REST Management	/api/v1/projects/{slug}/...	CRUD over content, schema, settings. Bearer-authed with management or session keys.
REST Delivery	/api/delivery/projects/{slug}/sites/{siteSlug}/...	Read-only, public-cacheable content delivery.
GraphQL	/api/graphql/{slug}	Auto-generated read-only schema with DataLoader batching.
MCP	/api/mcp/{slug}	Model Context Protocol server for agentic clients.

Conventions

Authentication

Bearer tokens via Authorization: Bearer <api-key>. Three key types:

• delivery — read-only published content
• preview — read-only published + drafts
• management — full CRUD

Cookie sessions are accepted on /api/v1/* for admin UI traffic.

Response envelope

{ "data": <payload> }
{ "data": <payload>, "meta": { "total": ..., "page": ..., "limit": ..., "pages": ... } }
{ "error": "<code>", "message": "<human>", "details": { ... } }

Rate limiting

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1714592400

429 on overage with a Retry-After header. Defaults: delivery 100 req/s, management 30 req/s; per-key overrides in the admin UI.

Error codes

Stable, machine-readable codes are returned in error. Common ones:

Code	Meaning
unauthenticated	No / invalid credentials
forbidden	Authenticated but not authorized for the action
<resource>_not_found	Resource doesn't exist (or you can't see it). 404 codes are resource-specific (entry_not_found, site_not_found, media_not_found, view_not_found, folder_not_found, …); bare not_found is rare
validation	Zod validation error (HTTP 422); details lists each failure
version_conflict	Optimistic concurrency mismatch on update
required_references_unpublished	Publish blocked by unpublished required references (HTTP 422)
slug_taken	Slug collides with an existing entry / project / site
rate_limit_exceeded	Too many requests

Request IDs

Every response includes X-Request-Id. Surface it in your error reporting — Krios's structured logs are keyed by it.