Authentication

Every Minima API request is authenticated with an API key sent in the x-api-key header. There are no other authentication methods, and there is no OAuth flow.

If you are working from the CLI, minima auth signup creates an account and mints one of these keys from the terminal. It is an ordinary key once you have it — everything below applies to it unchanged.

curl https://api.minima.ltd/api/v1/me \
  -H "x-api-key: priv_your_key_here"

That endpoint is the fastest way to check a key works. It needs nothing but the key itself, and it answers with what the key can do:

{
  "key": { "id": "key_...", "name": "Production", "type": "admin" },
  "role": "admin",
  "organizationId": "org_...",
  "siteId": null,
  "siteScope": null,
  "permissions": ["entities:read", "entities:write", "..."]
}

Use it when you are setting up. It is also the only route that resolves entirely from the key — every other organization route needs your organization ID in the path, so /me is how you discover which organization a key belongs to.

Two APIs, one host

Everything lives under https://api.minima.ltd/api/v1. Below that base URL there are two separate APIs, and which one you want depends on whether you are building a front end or an integration.

The Public API is the one you build a website against. Its routes live under /public/sites/{siteId}/, it returns only published content, and it is CORS-enabled for GET so you can call it from the browser.

The Admin API is everything else — creating and updating content, managing sites, publishing. Its keys can do destructive things, so they belong on a server.

See API keys for how the two key types differ and how to create one.

Your first Public API request

A Public API key is bound to a single site, so every request names that site in the path:

curl https://api.minima.ltd/api/v1/public/sites/site_abc123/articles \
  -H "x-api-key: pub_your_key_here"

The site in the URL must be the site the key is scoped to. Calling a different site with the same key returns 403, not an empty result.

Because these responses carry no credentials, the Public API sends permissive CORS headers for GET and OPTIONS, and x-api-key is an allowed request header. Fetching directly from the browser works:

const response = await fetch(
  "https://api.minima.ltd/api/v1/public/sites/site_abc123/articles",
  { headers: { "x-api-key": "pub_your_key_here" } },
)
const { data } = await response.json()

Your first Admin API request

Admin routes are scoped to your organization, which appears in the path:

curl https://api.minima.ltd/api/v1/org_abc123/entities \
  -H "x-api-key: priv_your_key_here"

Get your organization ID from /me, or from the URL in the Minima dashboard.

When authentication fails

Failures come back as JSON with a matching HTTP status.

{
  "url": "/api/v1/me",
  "status": 401,
  "statusCode": 401,
  "statusMessage": "Invalid API key",
  "message": "Invalid API key",
  "error": true
}

A revoked key and a key that never existed both return Invalid API key. That is deliberate — telling you which one it was would confirm a guess for anyone probing keys. If a key stops working unexpectedly, check whether it was revoked in Settings rather than reading anything into the message.