Errors & conventions

Everything in the endpoint reference follows the same handful of conventions. Learn them once.

Base URL and auth

• Base URL — https://app.writecalliope.ink/api/v1
• Auth — a single bearer scheme. Send your key on every request:

Authorization: Bearer cal_your_key

Keys are created and revoked at /account/api, shown once, and stored only as a hash. See Setup.

Tiers gate the call

Every operation carries a tier that decides what it needs before it runs:

• read — free. Always available with a valid key.
• ai — spends your credits (or your subscription allowance). No subscription required.
• write — requires an active subscription.

If a call isn’t permitted, you get a clear status code below — never a silent charge or a partial write.

The error shape

Errors return a stable JSON body:

{ "error": "code", "message": "a human-readable explanation" }

So you can branch on error and show message. The status codes:

Status	error	When
401	unauthorized	Missing or invalid API key.
402	insufficient_credits	Out of AI credits — top up to continue.
403	subscription_required	This write needs an active subscription.
403	category_disabled	The relevant AI category is switched off by your spend governor.
404	not_found	Not found, or you don’t own it.
400	bad_request	The request was malformed.

A 404 deliberately covers “doesn’t exist” and “isn’t yours” — the API never reveals whether a resource you don’t own exists.

Ownership

A key acts as you. Every call is scoped to the resources your account owns; you can’t read or touch another writer’s book. This is the same actor model the web app and MCP use.

The contract is the source of truth

The endpoint reference on this site is generated from Calliope’s OpenAPI contract, but the live contract itself is always authoritative:

• /api/v1/openapi.json — the full OpenAPI 3.1 document;
• /api/v1/llms.txt — the LLM-facing brief.

If you’re building against the API programmatically, read openapi.json directly.