Authentication

How requests to the public REST API identify themselves: the base URL, organization API keys, rate limits, and when to prefer a typed client.

The public API is defined once as an oRPC contract and served from the Worker at /api/v1. Every reference page in this section is generated from that contract’s OpenAPI spec, so it always matches what is deployed.

Base URL

https://stetcms.com/api/v1

On your own deployment, the API lives at your origin followed by /api/v1.

API keys

Every endpoint except the health check requires an organization-scoped API key, sent in the x-api-key header:

curl https://stetcms.com/api/v1/org \
  -H "x-api-key: $STET_API_KEY"

Create one in the Stet app under Developers → API keys. You need to be an owner or admin of the organization. A key is scoped to that one organization and reads every entry it holds, so it belongs on a server, never in a browser bundle. Only its hash is stored, so it is shown once, when it is created; the page lists what is left of it afterwards, and revokes it when you are done.

stet org is the quickest way to confirm a key is the one you meant:

STET_API_KEY=... npx stet org

Not for the MCP server

The MCP server is the exception. It authenticates a person over OAuth rather than an organization over an API key, so a key sent to it is not recognised, and an MCP token does not open the REST API. Keep the two apart.

Rate limits

Content delivery (/model and /content/*) is temporarily exempt from both the public API rate limit and the organization’s API request quota. Other public API requests and analytics ingest have separate budgets. Ingest is far larger and does not spend the organization’s API request quota: it is one request per browser batch.

An exhausted budget answers 429.

Prefer the typed clients

Hand-written requests are the fallback, not the happy path: