# ZevContent developer documentation — full text bundle

> Every page on `docs.zevcontent.com` concatenated into one file. Page boundaries are marked by `===` separators carrying the page title and canonical URL so an LLM can cite back to the source.

For a curated map without the full body text, see https://docs.zevcontent.com/llms.txt. For a single page, append `.md` to its URL.

---

===
# Introduction

> What ZevContent is, what it is not, and the one decision you make before anything else.

Source: https://docs.zevcontent.com/guide/

---

ZevContent is a **headless content backend**. You describe the shape of your
content, people who are not developers fill it in, and your frontend reads it
over a REST API.

Headless means we have no opinion about your frontend. There is no theme, no
template language and no renderer — we serve JSON, and what you build with it
is entirely yours. If you are looking for something that produces a website,
this is the wrong tool.

## The one decision: your own type, or a built-in module

Everything in ZevContent is one of two things, and knowing which you need is
most of the setup.

**Custom content types** are shapes you define. A `team-member` with a name, a
role and a photo. A `pricing-tier` with a price and a feature list. A
`homepage` singleton with a headline. You choose the fields, we store and serve
them, and the response shape follows your definition exactly.

**Built-in modules** are content types *we* define, document and maintain. There
are three: a [blog](/modules/blog), a [knowledge base](/modules/knowledge-base),
and the shared [author directory](/modules/authors) both of them credit. You
create nothing first — every project has these endpoints from the moment it
exists, and they serve an empty list until somebody writes something.

> **INFO: Why a blog is built in and a gallery is not**
>
> A blog is not a shape, it is a **set of behaviours**: slugs that must stay
> stable, an SEO chain with fallbacks, reading time, ordered co-authors, a
> category that is a page and a tag that is not. Ten teams modelling that
> themselves would produce ten subtly broken versions of the same thing, and
> each would discover the missing parts in production.
>
> A gallery is a shape: a title and a list of images. Nothing about it needs our
> opinion, so it is a custom type — and there is a template in the dashboard to
> start from.

## What you get without asking

Because a built-in module has a schema we control, it can do work for you that a
custom type cannot:

- **SEO arrives resolved.** `seo.title` falls back to the article title,
  `seo.description` to the excerpt and then to the opening of the body,
  `seo.og_image` to the featured image. You render what you are given. See
  [SEO](/concepts/seo).
- **References arrive as objects.** A listing carries the resolved author and
  category, not `author_id` and `category_id`, so twenty article cards cost one
  request rather than twenty-one.
- **Derived figures are computed.** `reading_time_minutes`, `word_count`, and
  the knowledge base's `freshness` verdict.

## What it is not

- **It is not a page builder.** There are no layouts, sections or blocks that
  render themselves.
- **It does not host your images.** Media goes to *your* object storage, and
  bytes never pass through us — see [Media](/concepts/media).
- **It is not a database.** The query surface is deliberately bounded: filters
  are ANDed, there is no OR and no nesting. A query that needs those is
  describing a report, not a page.

## Where to go next

If you have a key, the fastest path is the [quickstart](/guide/quickstart) —
three curl commands and you have read real content.

If you are an AI agent, or you are pointing one at this API, read
[For AI agents](/guide/agents) first. The short version: call
`/v1/introspection` before you read anything here, because it describes *your*
project rather than the product in general.

===
# Quickstart

> From a key to real content in three requests. Nothing to install.

Source: https://docs.zevcontent.com/guide/quickstart

---

There is no SDK and no build step. A key and `curl` are the whole toolchain.

## 1. Get a key

Create a project at [dashboard.zevcontent.com](https://dashboard.zevcontent.com),
then **Settings → API keys**. You are offered two kinds; take a **secret** key
for now, because you are calling from a terminal.

```bash
export ZEVCONTENT_KEY=sk_...
```

The key selects the project. There is no project id in any URL — the same path
serves different content for different keys.

> **WARNING: Which key goes where**
>
> A secret `sk_…` key is server-side only. The moment this reaches a browser
> bundle it is public, and anyone holding it can read everything the project
> serves. Browsers get a publishable `pk_…` key instead, locked to your origins.
> [API keys](/guide/keys) explains the difference in one page.

## 2. Ask the project what it holds

```http
GET /v1/introspection
```

```bash
curl https://api.zevcontent.net/v1/introspection \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

This is the single most useful request in the API. It returns every content
type with its fields and the exact shape each response will have, every
built-in module with its endpoints, the rich text contract, and the rules for
authentication, paging, filtering, rate limits and errors.

It describes **your** project, so it cannot be out of date with the content you
are about to fetch. [Introspection](/api/introspection) covers what comes back.

## 3. Read something

The built-in modules work immediately, with nothing configured:

```bash
curl "https://api.zevcontent.net/v1/blog/articles?limit=5" \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

```json
{
  "data": [
    {
      "slug": "how-we-deploy",
      "title": "How we deploy",
      "excerpt": "A short tour of the pipeline.",
      "authors": [{ "id": "aut_…", "name": "Ada", "slug": "ada" }],
      "categories": [{ "id": "cat_…", "name": "Engineering", "slug": "engineering" }],
      "reading_time_minutes": 6,
      "published_at": "2026-08-14T09:00:00.000Z",
      "seo": { "title": "How we deploy", "og_image": { "url": "https://…" } }
    }
  ],
  "meta": { "module": "blog", "limit": 5, "has_more": false, "next_cursor": null }
}
```

Note what you did **not** have to do: no second request for the byline, no
second request for the category, and no fallback chain to build `seo` yourself.

Your own types work the same way, at `/v1/content/{type}`:

```bash
curl "https://api.zevcontent.net/v1/content/team-member?where[role]=engineer&sort=name" \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

## 4. Page properly

Every listing is paginated, and there is no way to ask for all of something.
Read both `meta.next_offset` and `meta.next_cursor`: exactly one is set on a
page that has a successor, and **both are null on the last page**.

```bash
# The loop that works against every listing here.
next=0
while [ -n "$next" ]; do
  page=$(curl -s "https://api.zevcontent.net/v1/kb/articles?limit=50&offset=$next" \
    -H "Authorization: Bearer $ZEVCONTENT_KEY")
  echo "$page" | jq '.data[].title'
  next=$(echo "$page" | jq -r '.meta.next_offset // empty')
done
```

Do not compute the next offset yourself, and do not loop on `has_more` alone.
[Pagination and filtering](/api/pagination) explains why the two styles exist.

## Next

- [API keys](/guide/keys) — which key, and where it is safe.
- [Content types and entries](/concepts/content-model) — modelling your own shapes.
- [API overview](/api/) — the whole surface on one page.

===
# API keys

> Two kinds of key, what each one may do, and why the browser gets its own.

Source: https://docs.zevcontent.com/guide/keys

---

Every request carries a key, and the key selects the project:

```
Authorization: Bearer sk_…
```

There is no project id in any URL. The same path serves different content for
different keys, which means you can point a staging deploy at a different
project by changing one environment variable.

## The two kinds

| | `sk_…` secret | `pk_…` publishable |
|---|---|---|
| Where it runs | Server-side only | Safe in a browser |
| Origin restriction | None | Locked to the origins you list |
| Can list releases | Yes | No |
| Can write | Yes | No, except a knowledge base vote |
| Recoverable after creation | **No** | Yes |

### Secret keys

A secret key is shown **once**, when you create it. We store a hash, not the
key, so there is no "reveal" button and support cannot recover it — losing one
means creating another and revoking the old.

Treat it like a database password. It reads everything the project serves,
including unpublished releases, and it can write.

### Publishable keys

A publishable key is designed to be readable. It ships in page source, in a
mobile bundle, in a `view-source` — that is the point, and it is why the key
alone is not trusted as a claim about who is calling.

Two things bound it:

1. **An origin allow-list.** Add your site's origins to the key and a browser
   request from anywhere else is refused. `www.` is ignored when matching, so
   listing `https://example.com` covers `https://www.example.com`.
2. **A tighter rate budget.** Publishable keys are counted per key **and** per
   address, so one visitor hammering your help centre is limited without
   limiting every other visitor holding the same key.

> **WARNING: The origin allow-list is a browser control, not a wall**
>
> It works because browsers send `Origin` and cannot be made to lie about it.
> `curl` can send anything, so an allow-list does not make a publishable key
> secret — it stops your key being used to power somebody else's site, which is
> the realistic abuse. Never put content behind a publishable key that you would
> not put on the page it renders.

## Check a key

```http
GET /v1/ping
```

```bash
curl https://api.zevcontent.net/v1/ping \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

Confirms the key resolves and names the project it belongs to. This is the
first call to make when something is not behaving — it separates "wrong key"
from "wrong request", which are the two problems that look identical from a
404.

## Rotating and revoking

Revoking is immediate: the next request with that key is refused. There is no
grace period, so create the replacement, deploy it, and revoke afterwards.

Because a key belongs to one project, rotating one never affects another.

## Which key for which job

- **A static site build** — secret. It runs on a build machine, not a browser,
  and it can ask for `media_urls=permanent` to refuse expiring image URLs.
- **A React or Vue frontend fetching at runtime** — publishable, with your
  origins listed.
- **A help centre with helpful/not-helpful voting** — publishable. The
  [vote endpoint](/modules/knowledge-base#voting) is the one write a browser
  should ever make, and it explicitly expects a publishable key.
- **A migration script or an AI agent creating content** — secret. Writes
  require one.

===
# For AI agents

> Read this first if you are an agent holding a key — the API describes itself, and that description is better than this site.

Source: https://docs.zevcontent.com/guide/agents

---

This page is written for an AI agent asked to integrate ZevContent, and for the
person pointing one at it.

## Ask the server, not the docs

```http
GET /v1/introspection
```

If you hold a key, **start here rather than with this site**. One request
returns:

- every content type in the project, with its fields and the exact
  `response_shape` each one serves;
- every built-in module, with its endpoints, its shapes, how much is in it,
  and the notes that matter;
- the `core_endpoints` for custom content and schema;
- the rich text document contract — every node, mark and variant you may send;
- `conventions` — authentication, pagination, filtering, rate limits and the
  error envelope, with the real numbers.

It describes **that project**, not the product in general. These pages can go
stale; that response is generated from the code that serves the request, so it
cannot.

> **INFO: The rule of thumb**
>
> Read `/v1/introspection` to learn what to send. Read these pages to learn
> *why* — the reasoning, the trade-offs, and the mistakes the shape is built to
> prevent. If the two ever disagree, the API is right and this is a bug worth
> reporting.

## Machine-readable copies of this site

- **`/llms.txt`** — a curated index of every page, per the
  [llms.txt convention](https://llmstxt.org).
- **`/llms-full.txt`** — every page concatenated, for one-shot context.
- **`<any page>.md`** — the clean markdown body of a single page. Append `.md`
  to any URL here: `/api/errors.md`.

## The four things agents get wrong

**1. Fetching everything.** There is no way to ask for all of something, and
`?limit=5000` is refused rather than clamped. Page it: read both
`meta.next_offset` and `meta.next_cursor`, pass back whichever is set, and stop
when both are null. Do not loop on `has_more` alone.

**2. Filtering in the client.** Every listing filters server-side, on indexed
columns, and validates against the declared schema. `?where[role]=engineer` is
one indexed query; fetching a page and filtering it is a bug that only shows up
when the project grows. An unknown field is answered with the fields that
exist, so a wrong guess teaches you the right answer.

**3. Treating an empty list and a 404 as the same thing.** They are
deliberately different. A filter that matches nothing is `200` with an empty
array. Naming something that does not exist — an unknown category, section or
field — is a `4xx` that names the real ones and often carries `did_you_mean`.
If you get an empty list, your query was valid and there is nothing there.

**4. Retrying a 429 immediately.** Read `Retry-After` and wait exactly that
long. It is the moment the refusal lifts, not when the window rolls. While you
are being refused, requests are not counted — so hammering neither helps nor
hurts, it just wastes time. Better: read `X-RateLimit-Remaining-read` on every
response and slow down *before* you are refused.

## Errors are written to be acted on

Every failure is the same envelope, and the message is a sentence saying what
to do next rather than a status restated:

```json
{
  "error": {
    "type": "not_found_error",
    "code": "unknown_kb_article",
    "message": "This knowledge base has no published article at \"instal-the-cli\". Did you mean \"install-the-cli\"? List the published articles with GET /v1/kb/articles.",
    "request_id": "6e5c4029-…",
    "param": "slug",
    "did_you_mean": "install-the-cli"
  }
}
```

Branch on `code`, which is stable. `message` is for a human reading a log, and
may be reworded. See [Errors](/api/errors).

## Writing content

An agent can set a project up end to end with a **secret** key:

- `PUT /v1/schema/content-types/{type}` — define a type and its fields.
- `POST /v1/content/{type}/entries` — create an entry, optionally publishing
  it in the same call with `"publish": true`.
- `PUT /v1/content/{type}` — save a singleton.

Rich text is a document, not an HTML string. `/v1/introspection` returns the
whole node schema under `rich_text`; [Rich text](/concepts/rich-text) explains
the parts worth understanding before you generate one.

> **WARNING: Drafts are the default**
>
> Omitting `publish` creates a draft, which is deliberate: content generated by
> an agent should be reviewed by a person before it is public. Passing
> `"publish": true` skips that review — do it only when the person you are
> working for has asked you to.

===
# Troubleshooting

> The failures people actually hit, and what each one is really telling you.

Source: https://docs.zevcontent.com/guide/troubleshooting

---

## "It returns an empty list and I know there is content"

An empty list means your query was **valid** and matched nothing. Three usual
causes:

1. **Nothing is published.** `/v1` serves published content only. A draft is
   invisible here and visible in the dashboard, which is exactly how it should
   look while somebody is still writing.
2. **You are on the wrong release.** Custom content is release-scoped. Without
   `?release=` you are reading the default release, which may not be the one
   your colleague just edited. The built-in modules are release-*independent*,
   so this never explains a missing blog or knowledge base article — see
   [Releases](/concepts/releases).
3. **The filter matched nothing.** `?tag=setup` with no such tag is an empty
   list, not an error, because a tag is free-form and "no articles carry this"
   is a real answer.

> **INFO: An empty list is never a typo**
>
> Naming something that does not exist — an unknown category, section, field or
> sort key — is a `4xx` that names the real ones, not an empty list. So if you
> got `200` with `[]`, the names in your query were all correct.

## "I get 401 and the key is right"

`401` means the key did not resolve. Call `GET /v1/ping` — it confirms the key
and names its project, which separates "wrong key" from "wrong request".

If ping succeeds and your real request still fails, you are not looking at an
authentication problem.

## "It works in curl and fails in the browser"

`origin_not_allowed`. A publishable key is locked to the origins listed on it,
and `curl` does not send an `Origin` header, so it is never checked there.

Add the origin — scheme, host and port, exactly as the browser sends it — to
the key in the dashboard. `www.` is ignored when matching, so
`https://example.com` covers `https://www.example.com`. `http://localhost:3000`
and `http://localhost:5173` are different origins.

## "My image URLs stopped working"

Your project's bucket is **private**, so image URLs are presigned and expire.
The object carries `url_expires_at` saying exactly when.

That is fine for a page fetching at runtime and fatal for a static build, which
bakes the URL into HTML that outlives it. Pass `?media_urls=permanent` and the
API will **refuse** rather than hand you links that die — turning a silent
breakage weeks later into an error at build time. If you need permanent URLs,
make the bucket public. See [Media](/concepts/media).

## "I get 429 and I am not making many requests"

Check which budget. The header names it: `X-RateLimit-Remaining-read`,
`-write` or `-vote`. Budgets are separate, so reading all day never uses up
your allowance to vote.

Two things that surprise people:

- A **publishable** key is counted per key *and* per address. If your server is
  making requests with a publishable key, every one of them shares a single
  address budget. Use a secret key server-side.
- `Retry-After` is when the refusal **lifts**, not when the counting window
  rolls. Wait exactly that long. Retrying sooner earns another 429.

See [Rate limits](/api/rate-limits).

## "`where[…]` seems to be ignored"

Two possibilities, and the response tells you which:

- **A `400`** naming the fields that exist means you used a field key that is
  not on the type. `response_shape` in `/v1/introspection` lists them.
- **A `400`** naming operators means the operator does not apply to that field
  type. `contains` on a boolean is refused rather than silently matching
  nothing, because answering it with "0 results" would hide the mistake.

`where` only exists on `/v1/content`. The built-in modules take named filters
instead — `category`, `author`, `tag`, `q` for the blog; `collection`,
`section`, `q` for the knowledge base — because their schema is fixed.

## "Sorting changed how paging works"

It did, and the response says so. A cursor encodes a position in the *default*
order, so asking `/v1/content` for a `sort` switches it to offset paging:
`next_cursor` goes null and `next_offset` fills in.

Read both keys and pass back whichever is set. That one loop works everywhere.

## "The knowledge base ignores `?sort=`"

There is deliberately no `sort` anywhere in the knowledge base. Every listing
comes back in the order somebody dragged it into — collection, then section,
then the manual order inside it. A help centre in date order is not a help
centre.

If you need another order, sort client-side, knowing you are overriding an
editorial decision.

## "A slug I know exists returns 404"

Read the `code`:

- `kb_article_not_published` / `blog_article_not_published` — it exists and is
  a draft. Publish it.
- `kb_article_archived` — it was retired on purpose. Restore it, or remove the
  link.
- `unknown_kb_article` / `unknown_blog_article` — no such slug. Check
  `did_you_mean` in the error; it is usually a typo.

## Still stuck

Every response carries `X-Request-Id`, and every error repeats it as
`request_id`. Quote it — it leads straight to the log lines for that exact
request.

===
# Content types and entries

> Singletons, collections, the ten field types, and what a response looks like.

Source: https://docs.zevcontent.com/concepts/content-model

---

A **content type** is a shape you define: a name, a kind, and a list of fields.
An **entry** is one filled-in instance of that shape.

## Singleton or collection

A type is one of two kinds, and the kind is fixed once the type exists.

**Singleton** — there is exactly one of it. A homepage hero, a site footer, an
"about" page. `GET /v1/content/homepage` returns its values object directly,
with no array and no paging, because there is nothing to page through.

**Collection** — there are many. Team members, case studies, pricing tiers.
`GET /v1/content/team-member` returns a paginated array.

> **INFO: The kind cannot change later**
>
> A singleton that becomes a collection would change the response from an object
> to an array, which breaks every frontend reading it. So the kind is immutable
> (`content_type_kind_immutable`). If you are unsure, a collection with one entry
> is the recoverable mistake; a singleton that should have been a collection is
> not.

## The field types

| Type | Holds | Filterable with |
|---|---|---|
| `string` | A single line | `eq` `ne` `contains` `starts_with` `in` `is_null` |
| `text` | Multiple lines, no formatting | `eq` `ne` `contains` `starts_with` `is_null` |
| `richtext` | A formatted document | `is_null` |
| `number` | A number | `eq` `ne` `gt` `gte` `lt` `lte` `in` `is_null` |
| `boolean` | True or false | `eq` `ne` `is_null` |
| `date` | A date | `eq` `ne` `gt` `gte` `lt` `lte` `is_null` |
| `select` | One of a fixed list | `eq` `ne` `in` `is_null` |
| `url` | A link | `eq` `ne` `contains` `starts_with` `is_null` |
| `image` | One picture | `is_null` |
| `gallery` | Several pictures | `is_null` |

The three unfilterable types are deliberate. `richtext` is a document tree and
`image`/`gallery` are asset references — "does this body contain the word X" is
a search feature with its own index, not an equality test on JSON, and
pretending otherwise would ship a filter that quietly scans every row.

An operator a field type does not support is **refused**, not silently ignored.
A `contains` on a boolean is a mistake, and answering it with "0 results" hides
the mistake.

## What a response looks like

```http
GET /v1/content/{type}
```

```json
{
  "data": [
    {
      "id": "ent_2c8RkXqGn4wVtYbMhJpDs",
      "values": {
        "name": "Ada Lovelace",
        "role": "engineer",
        "joined": "2024-03-01",
        "photo": {
          "url": "https://cdn.example.com/…",
          "alt": "Ada at her desk",
          "width": 1600,
          "height": 900,
          "content_type": "image/jpeg"
        }
      },
      "published_at": "2026-08-14T09:00:00.000Z",
      "updated_at": "2026-08-20T11:12:00.000Z"
    }
  ],
  "meta": {
    "type": "team-member",
    "kind": "collection",
    "release": { "id": "rel_…", "name": "Launch", "default": true },
    "limit": 20,
    "has_more": false,
    "next_cursor": null,
    "next_offset": null
  }
}
```

Scalar fields appear as themselves. An `image` resolves to an object; a
`gallery` to an array of them; a `richtext` to `{ html, json, plain, toc }`.
You never receive a raw asset id.

> **INFO: Ask for the shape rather than deriving it**
>
> `/v1/introspection` returns a `response_shape` per type describing exactly
> this, key by key, including the extra `url_expires_at` a private project adds
> to every image. It is generated from the same code that serves the response,
> so it is the answer rather than an approximation of it.

## Only published content is served

`/v1` serves published entries. A draft is invisible here and visible in the
dashboard — that is what lets somebody work on a page for a week without it
appearing on your site.

Fetching an entry that exists but is not published answers `entry_not_published`
or `content_not_published`, which says so rather than pretending the entry does
not exist.

## Templates

The dashboard offers **templates** when you create a type: a gallery, a team
member, a pricing tier, a case study and others. Picking one **copies** the
fields into your project.

A copy, not a link — so improving a template later never changes a type
somebody is already using, and you are free to rename, delete and add fields
the moment it lands. The template is a starting point, not a parent.

## Writing from code

Both writes need a **secret** key.

```http
POST /v1/content/{type}/entries
```

```json
{ "values": { "name": "Ada Lovelace", "role": "engineer" }, "publish": true }
```

```http
PUT /v1/content/{type}
```

Replaces a singleton's draft, creating its one entry on first save.

Omit `publish` and you get a draft — the right default for a migration script
or an agent, because content generated by a machine should usually be reviewed
before it is public.

The type itself can be created from code too, with
`PUT /v1/schema/content-types/{type}`, which is what lets an agent set a
project up end to end.

===
# Releases

> Version control for content, why custom types have it and built-in modules do not.

Source: https://docs.zevcontent.com/concepts/releases

---

A **release** is a complete copy of your custom content — the types, their
fields, and every entry including drafts. One release per project is the
**default**, and that is what `/v1/content` serves when you do not ask for
another.

## What it is for

You want to change the shape of your content without breaking the site that is
currently reading it. So:

1. **Clone** the default release. You now have a second, complete copy with its
   own `rel_…` id.
2. **Change it** — add a field, rename one, restructure a type, edit entries.
   The live site sees none of this; it is still reading the default.
3. **Test it** by pointing a preview deploy at the new release:
   `?release=rel_…`, or the same environment variable set differently.
4. **Promote** it when the new frontend is ready. The release becomes the
   default and every request without a `?release=` follows.

Promotion is a flag flip, not a copy — nothing is moved at the moment of going
live, so nothing can half-move. Rolling back is the same flip in reverse: the
old release still exists, untouched, at the same id.

## Reading a specific release

```http
GET /v1/content/{type}?release=rel_…
```

Omit the parameter and you get the default. Every response says which release
answered it:

```json
"meta": {
  "release": { "id": "rel_RJuPMMbZ…", "name": "Launch", "default": true }
}
```

## Release ids are staging by obscurity

A non-default release has no other address. Anyone who knows its `rel_…` id can
read it, which is exactly what makes a preview deploy easy — and exactly why
the id must not leak.

> **WARNING: Publishable keys cannot list releases**
>
> `/v1/introspection` includes the full `releases` list for a **secret** key
> only. A publishable key ships in page source, so listing release ids to it
> would hand every visitor an index of your unreleased content.
>
> A publishable key still sees `release` — the one serving its request, whose id
> it either already knew or is the default. The key is *absent* rather than
> empty for publishable keys, so a client can tell "not allowed to see" from
> "there are none".

## Built-in modules are release-independent

Blog articles, knowledge base articles, collections, sections and authors hang
off the **project**, not a release. `?release=` is neither needed nor honoured
on `/v1/blog`, `/v1/kb` or `/v1/authors`, and every response from those
endpoints says so:

```json
"meta": { "module": "blog", "release_independent": true }
```

Concretely:

- Publishing an article shows it immediately, whatever release is default.
- Cloning a release does **not** copy the back catalogue.
- Promoting a release does **not** revert an article somebody edited yesterday.

This is deliberate. A release exists to change the **shape** of content, and
the shape of a blog article is ours — it does not change when you restructure
your own types. Tying the two together would mean a writer's Tuesday afternoon
correction disappearing because a developer promoted a release on Wednesday.

> **INFO: If your blog seems out of date, releases are not the reason**
>
> It is the first thing people suspect and it is never the cause. Check whether
> the article is published, and check you are reading the project you think you
> are with `GET /v1/ping`.

## What a clone copies

Everything in the custom content model: types, fields, entries, **draft and
published values**, and the publishing timestamps. A cloned release is a
complete working copy, not a published-only export — so a page half-written
when you cloned is still half-written in the copy, which is what you want when
the point is to test a migration.

Media is not copied and does not need to be: an asset belongs to the project,
and both releases reference the same one.

===
# Rich text

> One document, three views, and a node schema that is ours rather than an editor's.

Source: https://docs.zevcontent.com/concepts/rich-text

---

A `richtext` field stores a **document** and serves three views of it.

```json
"body": {
  "html":  "<h2 id=\"install\">Install</h2><p>Run <code>npm i</code>…</p>",
  "json":  { "version": 2, "content": [ /* nodes */ ] },
  "plain": "Install Run npm i …",
  "toc":   [ { "level": 2, "text": "Install", "id": "install" } ]
}
```

- **`html`** — semantic HTML, ready to render. External links carry
  `rel="nofollow noopener"`. Images carry `width`/`height` when known and
  become `<figure><img><figcaption>` when captioned. A callout is
  `<aside class="callout callout-info">`. A table is a real `<table>` with
  `<thead>` and `<th>`. An embed is a responsive `<iframe>` for a known
  provider and a plain link otherwise — **never** a third-party script.
- **`json`** — the stored document, with image URLs and embed URLs resolved
  and link `rel` added. Build your own renderer on this when you want React
  components instead of `dangerouslySetInnerHTML`.
- **`plain`** — text only. For meta descriptions, previews and search. Image
  captions and table cells are included; alt text and embed URLs are not.
- **`toc`** — the headings in order, with the *same ids* the rendered HTML
  puts on them, so `#id` lands. Build in-page navigation from this rather than
  parsing the HTML.

> **INFO: The schema is ours, not an editor's**
>
> `json` is not an editor's internal state. It is a document schema ZevContent
> defines and versions, which is what makes it safe to build a frontend on: the
> day we replace the dashboard's editor, nothing about this changes.

## The node schema

Current version: **2**. Both 1 and 2 are accepted on write.

**Block nodes** — `paragraph`, `heading`, `bulletList`, `orderedList`,
`listItem`, `blockquote`, `codeBlock`, `callout`, `table`, `tableRow`,
`tableCell`, `tableHeader`, `image`, `embed`, `horizontalRule`.

**Marks** — `bold`, `italic`, `underline`, `strike`, `code`, `highlight`,
`link`.

**Heading levels** — 2, 3 and 4. Level 1 belongs to the page, not to the body
of a field.

`listItem` appears only inside a list, and `tableRow`/`tableCell`/`tableHeader`
only inside a table. Every other node may appear at the top level.

## Versions

Send `"version": 2`. A document sent as version 1 is accepted — schema 2 is a
superset of schema 1 — and stored as 2. A version above 2 is refused.

A document **stored** at version 1 keeps saying 1 when you read it, and renders
exactly as it always did. Callouts, tables, embeds and image captions are the
schema 2 additions.

## Images inside a document

An `image` node takes **either** `assetId` **or** `src` — exactly one, never
both and never neither.

- `assetId` is a `med_…` id from this project's media library. It resolves to a
  URL on every read, and on a project with a private bucket gains
  `url_expires_at`.
- `src` is an absolute `http(s)` URL to an image hosted elsewhere, stored
  verbatim. Nothing else is accepted — no `data:`, no protocol-relative
  `//host`, no `/path`, no `#fragment`.

Reading one back, it carries `"source": "library"` or `"external"` and a `url`.
An external image's URL *is* its stored `src`: it never expires, we never fetch
it, and the server it lives on is not ours — it can move, disappear or block
hotlinking. That is the trade-off of pasting a URL in rather than uploading.

`alt` is for a screen reader; `caption` is printed under the picture and counts
toward the reading time.

## Callouts, tables and embeds

**Callouts** take `{ "variant": "info" | "warning" | "success" | "danger" }`
and hold paragraphs and lists. The variant is the callout's *meaning* and
becomes `class="callout callout-…"` on the rendered `<aside>`.

**Tables** hold `tableRow`; a row holds `tableCell` or `tableHeader`; a cell
takes `colspan` and `rowspan` (positive integers, default 1). Leading rows made
entirely of `tableHeader` become the `<thead>`.

**Embeds** take a `{ "url" }`, held to the same rule as a link `href`.
`provider` and `embedId` are **derived by the server** and any values you send
for them are discarded. `youtube`, `vimeo`, `x` and `codepen` get a responsive
iframe; anything else is `generic` and renders as a link.

> **WARNING: No embed ever emits a script tag**
>
> This is a hard rule, not a current limitation. Letting a content field inject
> third-party JavaScript into your page would make every writer a deploy of
> arbitrary code onto your site.

## Writing a document

Unknown **marks** are dropped on save. Unknown **node types** are refused with
an error naming what is allowed (`unknown_richtext_node`), because silently
dropping a node loses content somebody wrote.

`link` marks take `{ "href" }`. `rel` and `target` are set by the renderer and
never stored.

If you are generating documents programmatically, `/v1/introspection` returns
this whole contract under `rich_text` — every node type, mark, heading level,
callout variant and embed provider, as arrays you can validate against.

===
# Media and images

> Your bucket, your bytes. Public and private projects, and why a static build must ask for permanent URLs.

Source: https://docs.zevcontent.com/concepts/media

---

ZevContent does not host your images. Media lives in **your** object storage —
ZevCloud Storage, S3, R2, anything S3-compatible — and no byte of it passes
through us.

Uploads go browser → your bucket, using a URL we sign. Reads go browser → your
bucket, using a URL we resolve. We store a record of the asset, never the file.

> **INFO: Why it works this way**
>
> The alternative is proxying media through our CDN, which would make your
> bandwidth our cost and our outage your outage. Keeping bytes out of the path
> means an image is exactly as fast and exactly as available as your own
> storage, and your bill is your own.

## What an image looks like in a response

Every `image` field, gallery entry, featured image, avatar and og image is the
same object:

```json
{
  "url": "https://cdn.example.com/media/hero.jpg",
  "alt": "The team at the launch",
  "width": 1600,
  "height": 900,
  "content_type": "image/jpeg"
}
```

`width` and `height` are there so you can reserve space and avoid layout shift
without measuring the file. They are null when we could not determine them.

You never receive a raw `med_…` id in a content response — resolution happens
server-side, in one batched pass per request, so an article with a dozen
pictures costs the same round trip as one without.

## Public and private projects

Set per project, in the dashboard, and it changes the shape of every image URL.

**Public bucket.** URLs are permanent. They keep working forever, they cache
well, and they are safe to bake into static HTML.

**Private bucket.** URLs are presigned `GET`s with an expiry, and the object
gains one extra key:

```json
{
  "url": "https://…?X-Amz-Signature=…",
  "url_expires_at": "2026-09-02T11:30:00.000Z",
  "…": "…"
}
```

The response also carries a short `Cache-Control`, because caching a URL past
its own expiry serves a broken image.

## Static builds: ask for permanent URLs

A static build bakes URLs into HTML that outlives the build. A presigned URL
dies hours later, and the failure appears long after the deploy that caused it,
on a page nobody was looking at.

So say what you need:

```bash
curl "https://api.zevcontent.net/v1/blog/articles?media_urls=permanent" \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

On a public project this changes nothing. On a private project the request is
**refused** — `permanent_media_urls_unavailable` — rather than handing you
links that will break:

> This project's media bucket is private, so every image URL is signed and
> expires — there are no permanent URLs to give you. Either make the bucket
> publicly readable and switch the project to public media access in the
> dashboard, or fetch this content at request time and re-fetch before
> `url_expires_at`, or download each image at build time and serve it
> yourself.

That is a build failure instead of a silent breakage weeks later, which is the
whole reason the parameter exists.

> **WARNING: Private buckets and static site generators do not mix**
>
> If you are on Astro, Next `output: 'export'`, Hugo, Eleventy or any other SSG,
> either make the bucket public or download the images at build time. There is no
> third option that ends well.

## Knowing before you fetch

`/v1/introspection` reports the project's media policy once, next to the schema
that mentions it:

```json
"media": { "access": "private", "urls": "signed", "url_ttl_seconds": 3600 }
```

so a client does not have to infer it from the presence of a key inside one
field's shape.

## Images inside rich text

The same rules apply to `image` nodes in a rich text document, with one
addition: a node may reference an **external** URL instead of a library asset.
An external image never expires and is never fetched by us — see
[Rich text](/concepts/rich-text#images-inside-a-document).

===
# SEO

> One resolved object on every page-shaped thing, with the fallback chain already applied.

Source: https://docs.zevcontent.com/concepts/seo

---

Anything in ZevContent that corresponds to a **page** carries a complete `seo`
object: blog articles, blog categories, knowledge base articles, knowledge base
collections, and authors.

```json
"seo": {
  "title": "How we deploy",
  "description": "A short tour of the pipeline.",
  "og_image": {
    "url": "https://cdn.example.com/media/deploy.jpg",
    "alt": "A deployment pipeline",
    "width": 1200,
    "height": 630,
    "content_type": "image/jpeg"
  },
  "canonical_url": null,
  "noindex": false
}
```

It always arrives **complete and resolved**. Render what you are given.

## The fallback chains

A writer fills in as much as they care to. The server applies the rest, in the
same code path for every module:

| | `title` falls back to | `description` falls back to | `og_image` falls back to |
|---|---|---|---|
| **Blog article** | the article title | the excerpt, then the opening of the body | the featured image |
| **Blog category** | the name | the description | the featured image |
| **KB article** | the title | the summary, then the opening of the body | the featured image |
| **KB collection** | the title | the description | the collection image |
| **Author** | the name | the opening of the bio | the avatar |

Descriptions derived from a body are cut on a **word boundary**, not mid-word.

`canonical_url` and `noindex` always pass through exactly as set — there is
nothing sensible to derive them from, and guessing a canonical URL is how
duplicate-content problems get created rather than solved.

> **WARNING: Do not reimplement the chain**
>
> The commonest mistake is writing `article.seo.title || article.title` in a
> frontend. It is redundant on the day you write it, and it becomes wrong the day
> the chain changes — your version and ours will disagree, and only one of them
> is in the sitemap.
>
> `seo.title` is never null. `description` and `og_image` are null only when
> every source in the chain is empty, which means there is genuinely nothing to
> say.

## Rendering it

```html
<title>{seo.title}</title>
{seo.description && <meta name="description" content={seo.description} />}
{seo.canonical_url && <link rel="canonical" href={seo.canonical_url} />}
{seo.noindex && <meta name="robots" content="noindex" />}

<meta property="og:title" content={seo.title} />
{seo.description && <meta property="og:description" content={seo.description} />}
{seo.og_image && <meta property="og:image" content={seo.og_image.url} />}
{seo.og_image?.width && <meta property="og:image:width" content={seo.og_image.width} />}
{seo.og_image?.height && <meta property="og:image:height" content={seo.og_image.height} />}
```

`og_image` is the same media object as everywhere else, so on a **private**
project it is a presigned URL that expires. Social crawlers fetch when someone
shares a link, which may be months after your build — see
[Media](/concepts/media) for why a static build should ask for
`media_urls=permanent`.

## Where `seo` is *not*

Nested references do not carry it. An author inside an article's `authors`
array is a **byline** — id, name, slug, bio, social — and a category inside
`categories` is a **breadcrumb**. Neither has `seo` or `article_count`,
because a card printing twenty bylines will never render twenty og images.

Fetch the author's or category's own endpoint for the page shape.

## Custom content types

`seo` is a feature of the built-in modules, not of custom types. Your own type
gets the fields you define — if a `case-study` needs a meta description, add a
`string` field for it and render it yourself.

We do not synthesise an SEO object for a shape we did not design, because we
would have to guess which of your fields is the title.

===
# API overview

> One base URL, one key, and the whole surface on one page.

Source: https://docs.zevcontent.com/api/

---

```
https://api.zevcontent.net
```

Every request carries `Authorization: Bearer <key>`, and the key selects the
project. There is no project id in any URL.

> **INFO: The API describes itself**
>
> `GET /v1/introspection` returns your project's whole contract as JSON — every
> type, every module, every endpoint, every convention, with the real numbers.
> It is generated from the code that serves the requests, so it cannot be out of
> date. See [Introspection](/api/introspection).

## The surface

### Custom content

| | |
|---|---|
| `GET /v1/content/{type}` | A singleton's values, or a paginated collection |
| `GET /v1/content/{type}/{entryId}` | One entry by id |
| `POST /v1/content/{type}/entries` | Create an entry *(secret key)* |
| `PUT /v1/content/{type}` | Save a singleton *(secret key)* |
| `GET /v1/schema/content-types` | Every type definition *(secret key)* |
| `PUT /v1/schema/content-types/{type}` | Create or update a type *(secret key)* |

See [Content](/api/content).

### Blog

| | |
|---|---|
| `GET /v1/blog/articles` | Published articles, newest first |
| `GET /v1/blog/articles/{slug}` | One article, with its body |
| `GET /v1/blog/categories` | Every category |
| `GET /v1/blog/categories/{slug}` | One category page |

See [Blog](/modules/blog).

### Knowledge base

| | |
|---|---|
| `GET /v1/kb/tree` | The navigation tree, sections nested |
| `GET /v1/kb/articles` | Published articles in reading order |
| `GET /v1/kb/articles/{slug}` | One article, with its body |
| `POST /v1/kb/articles/{slug}/vote` | Helpful / not helpful *(publishable key)* |

See [Knowledge base](/modules/knowledge-base).

### Authors

| | |
|---|---|
| `GET /v1/authors` | Every author |
| `GET /v1/authors/{slug}` | One author page |

See [Authors](/modules/authors).

### Utility

| | |
|---|---|
| `GET /v1/introspection` | The whole project, described |
| `GET /v1/ping` | Confirms a key resolves |

## Conventions that hold everywhere

- **[Authentication](/api/authentication)** — two key kinds, and what each may do.
- **[Pagination and filtering](/api/pagination)** — every listing pages; nothing returns everything.
- **[Rate limits](/api/rate-limits)** — three separate budgets, counted per key.
- **[Errors](/api/errors)** — one envelope, and messages written to be acted on.

## The response envelope

A single item:

```json
{ "data": { … }, "meta": { … } }
```

A listing:

```json
{ "data": [ … ], "meta": { "limit": 20, "has_more": true, "next_offset": 20, "next_cursor": null } }
```

`meta` on a built-in module also carries `module` and `release_independent`, so
a caller inspecting a payload can tell what it is looking at without matching
on the URL it asked for.

## Stability

These URLs and these keys end up in static builds and mobile releases we do not
control, so the rule is **additive only**: new keys may appear, existing ones do
not change meaning and do not disappear.

Two consequences worth knowing:

- A listing omits `body`, and always will. Adding it later would be additive;
  removing it would not, which is why it starts absent.
- `authors` and `categories` are arrays with no singular `author`/`category`
  beside them. Two names for one thing is how a contract rots.

===
# Authentication

> Bearer keys, what each kind may do, and the failures that look like authentication and are not.

Source: https://docs.zevcontent.com/api/authentication

---

```
Authorization: Bearer sk_…
```

The key selects the project. No project id appears in any URL, so pointing a
deploy at a different project is a change to one environment variable.

## Key kinds

**`sk_…` — secret.** Server-side only. Reads everything the project serves,
can list every release, and can write. Shown once at creation; we store a hash,
so it cannot be recovered.

**`pk_…` — publishable.** Safe in a browser. Restricted to the origins listed
on it, cannot list releases, and cannot write — with one deliberate exception,
the knowledge base [vote endpoint](/modules/knowledge-base#voting).

Full comparison in [API keys](/guide/keys).

## Verify a key

```http
GET /v1/ping
```

```bash
curl https://api.zevcontent.net/v1/ping \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

Confirms the key resolves and names its project. Make this call first when
something is not behaving — it separates "wrong key" from "wrong request",
which look identical from a 404.

## Failures

| Status | `code` | What it means |
|---|---|---|
| 401 | `unauthenticated` | Missing, malformed, unknown or revoked key. Revocation is immediate. |
| 403 | `origin_not_allowed` | A publishable key used from an origin not on its list. |
| 403 | `secret_key_required` | A write, or a release listing, attempted with a publishable key. |

> **INFO: 401 and 403 are different questions**
>
> `401` says we do not know who you are. `403` says we do, and this is not
> allowed. If you are getting `403`, the key is fine — check which kind it is
> and where it is being called from.

## The origin check

A publishable key with origins listed is refused from any other **browser**
origin. The check compares the `Origin` header, ignoring `www.`, so
`https://example.com` covers `https://www.example.com`. Scheme and port are
part of an origin: `http://localhost:3000` and `http://localhost:5173` are not
the same.

It is best-effort by nature — `curl` sends whatever it likes, so an allow-list
does not make a publishable key secret. It stops your key powering somebody
else's site, which is the realistic abuse.

## What a key can see

A key sees its project's **published** content, and nothing outside that
project. There is no endpoint that crosses a project boundary, and an id from
another project is not found rather than forbidden — a "forbidden" would
confirm the id exists.

Drafts are never served on `/v1`, whichever key you hold. A draft article
answers `blog_article_not_published` or `kb_article_not_published`, which says
what is wrong rather than pretending the slug does not exist.

===
# Pagination and filtering

> Every listing pages, nothing returns everything, and filtering happens in the database.

Source: https://docs.zevcontent.com/api/pagination

---

## Nothing returns everything

Every listing on `/v1` is paginated server-side, and there is no parameter that
asks for all of something.

This is deliberate. An endpoint that will return ten thousand rows if asked is
an endpoint that eventually does — at the worst possible moment, on somebody
else's traffic. Bounding it here means the ceiling is ours to reason about
rather than every integrator's to remember.

**`limit`** is 1–100, default 20. A value outside that range is **refused**
(`invalid_limit`), not clamped: a caller building a paging loop must never
silently receive a different page size than it asked for.

## The one loop that works everywhere

Read **both** `meta.next_offset` and `meta.next_cursor`. Exactly one is set on
a page that has a successor, and **both are null on the last page**.

```js
let params = { limit: 50 };
const all = [];

for (;;) {
  const res = await fetch(url + '?' + new URLSearchParams(params), { headers });
  const { data, meta } = await res.json();
  all.push(...data);

  if (meta.next_offset != null) params.offset = meta.next_offset;
  else if (meta.next_cursor != null) params.cursor = meta.next_cursor;
  else break;
}
```

Do not compute the next offset yourself, and do not loop on `has_more` alone.

## Why there are two styles

**Cursor** — `/v1/blog/articles`, and `/v1/content` collections in their
default order. A cursor encodes a position in that order, so rows inserted
while you are paging cannot make you skip or repeat one.

**Offset** — everything else: `/v1/kb/*`, `/v1/authors`,
`/v1/blog/categories`, and `/v1/content` **whenever `sort` is used**.

That last case is the one that surprises people. A cursor is a position in the
*default* order, so asking for a different order invalidates it:
`next_cursor` goes null and `next_offset` fills in. The response tells you
which one it answered with — read it rather than assuming.

Treat a cursor as opaque. It is a base64 position, not a key you can construct.

## Filtering

Filtering happens in the database, on indexed columns, and is validated against
the declared schema.

### Custom content: `where[…]`

```
?where[role]=engineer
?where[price][gte]=100
?where[tag][in]=a,b,c
?where[archived_at][is_null]=true
```

`where[field]=value` is equality; `where[field][op]=value` for anything else.
Conditions are **ANDed**. There is no OR and no nesting — a query that needs
them is describing a report, not a page, and should run against your own copy
of the data.

**Operators:** `eq` `ne` `gt` `gte` `lt` `lte` `contains` `starts_with` `in`
`is_null`.

Which ones apply depends on the field type — see the table in
[Content types](/concepts/content-model#the-field-types). An operator the type
does not support is refused, not silently ignored.

`in` takes at most 50 values. So does `?ids=`.

> **INFO: A wrong name teaches you the right one**
>
> `?where[rôle]=engineer` answers `400 unknown_filter_field` and names every
> field the type declares. `?sort=nope` names the sortable ones. You never have
> to guess twice.

### Built-in modules: named filters

The modules have a fixed schema, so they expose named filters instead:

- **Blog** — `category`, `author`, `tag`, `q`
- **Knowledge base** — `collection`, `section`, `q`

All of them take **slugs**, not ids, because a page URL already contains the
slug and looking up an id first would be a request per page load to learn
something you already know.

`category` and `author` match an article carrying that slug **anywhere** in its
list, so a co-authored post appears on both authors' pages.

### Search

`q` is a case-insensitive **substring** match on titles and summaries or
excerpts, backed by a trigram index so it stays fast on a large corpus.

It is not ranked full-text search and it does not stem: "running" will not
match "run". It combines with the other filters, which is how a category or
collection page offers search *within itself* without a second endpoint.

## Empty is not the same as unknown

- A filter that matches nothing → `200` and an empty array. Your query was
  valid; there is nothing there.
- A name that does not exist — a category, section, collection or field →
  `4xx` naming the real ones.

So an empty list is never a typo, and a typo is never an empty list. This is
worth relying on: it is the difference between "we have no posts in
Engineering" and "you spelled Engineering wrong", which are otherwise
indistinguishable.

## Sorting

`/v1/content` takes `?sort=`: a field key, or `created_at`, `published_at`,
`updated_at`. Prefix with `-` for descending.

The **knowledge base has no `sort`, deliberately**. Every listing comes back in
the order somebody dragged it into. A help centre in date order is not a help
centre.

===
# Rate limits

> Three separate budgets, counted per key, with headers that let you slow down before you are refused.

Source: https://docs.zevcontent.com/api/rate-limits

---

## The budgets

| Budget | Per minute | Covers |
|---|---|---|
| `read` | 600 | Every `GET` |
| `write` | 60 | Every write except votes |
| `vote` | 30 | `POST /v1/kb/articles/{slug}/vote` |

A request spends **one** budget. Reading all day never uses up your allowance
to vote, and a site doing nothing but reading is never refused a write it never
attempted.

The numbers are sized against real use: a static build fetching every article,
category and author is a few dozen calls; a thousand-article import takes about
seventeen minutes at 60 writes a minute, which is the right speed for something
rewriting a customer's content.

## Counted per key, not per address

Server-to-server traffic arrives from one address — often one NAT or serverless
region shared by many projects. An address budget would either throttle a whole
platform down to one project's share, or be set so high it protects nothing.

**Publishable keys are the exception**: they are counted per key **and** per
address, because they live in a browser where anyone can read them. One visitor
hammering your help centre is limited without limiting every other visitor
holding the same key.

> **WARNING: Do not use a publishable key from a server**
>
> Every request from your server shares one address budget. It looks like a much
> lower limit than the table says, and the cause is invisible from the response.
> Use a secret key server-side.

## The headers

Every response carries, for the budget it spent:

```
X-RateLimit-Limit-read: 600
X-RateLimit-Remaining-read: 587
X-RateLimit-Reset-read: 43
```

`Remaining` is what this exists for. Read it and slow down **before** you are
refused — that is cheaper for you than a 429 and cheaper for everyone else too.

A `429` additionally carries:

```
Retry-After: 51
```

## Handling a 429

```json
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests on this API key — the limit is 30 per minute on this endpoint. Wait 51 seconds and try again…",
    "request_id": "8abf0d3d-…"
  }
}
```

Wait `Retry-After` seconds, then retry.

> **INFO: Retry-After is when the refusal lifts, not when the window rolls**
>
> They are different instants: the block is set partway through a window and runs
> its own duration from there. We send the later one on purpose, so a client that
> obeys the header is never refused for doing as it was told.
>
> While you are being refused, requests are **not counted** — so hammering
> neither helps nor hurts you. It just wastes your own time.

If you are backfilling, spread the writes out. If you are serving a site, cache
the reads: content changes when somebody edits it, not on every page view.

## Shared limits across instances

The counters are shared, so the numbers above are the numbers whether you run
one instance or twenty. Scaling your frontend horizontally does not multiply
your budget.

## Asking for more

The limits are per key, so splitting a workload across keys splits the budget
rather than multiplying it — one key per project is the intended shape, and
minting extra keys to route around a limit will not work the way it looks like
it should. If a legitimate workload does not fit, tell us what it is.

===
# Errors

> One envelope, a stable code to branch on, and a message written to be acted on.

Source: https://docs.zevcontent.com/api/errors

---

## The envelope

Every failure, at every status, looks like this:

```json
{
  "error": {
    "type": "not_found_error",
    "code": "unknown_kb_article",
    "message": "This knowledge base has no published article at \"instal-the-cli\". Did you mean \"install-the-cli\"? List the published articles with GET /v1/kb/articles.",
    "request_id": "6e5c4029-5e1b-47fd-a72e-eb2d5b8f1e2c",
    "param": "slug",
    "did_you_mean": "install-the-cli",
    "doc_url": "https://docs.zevcontent.com/errors/unknown_kb_article"
  }
}
```

| Key | |
|---|---|
| `type` | The broad class. One of the seven below. |
| `code` | The specific reason. **Branch on this** — it is stable. |
| `message` | A sentence saying what to do next. Written for a person reading a log; may be reworded. |
| `request_id` | Also on every response as `X-Request-Id`. Quote it when asking us. |
| `param` | Which parameter or field was at fault. |
| `did_you_mean` | **One** closest match, a string — not a list. |
| `available_fields` | Every field key a type declares, on a filter or sort naming one it does not have. |
| `available_types` | Every content type slug, on an unknown type. |
| `expected` / `got` | The type a value should have had, and the one it had. |
| `doc_url` | The page explaining this code. |

## Types

| `type` | Status | |
|---|---|---|
| `authentication_error` | 401 | We do not know who you are |
| `permission_error` | 403 | We do, and this is not allowed |
| `not_found_error` | 404 | No such thing |
| `conflict_error` | 409 | It exists, or it is in use |
| `rate_limit_error` | 429 | Too many requests |
| `invalid_request_error` | 4xx | The request was malformed |
| `api_error` | 5xx | Our fault |

## Errors are written to teach

The messages are not status codes restated. Naming something that does not
exist answers with the ones that do:

```
GET /v1/content/homepage
```
```json
{
  "error": {
    "code": "unknown_content_type",
    "message": "This project has no content type with slug \"homepage\". Available types: homepage-hero, filter-demo.",
    "param": "typeSlug",
    "available_types": ["homepage-hero", "filter-demo"]
  }
}
```

> **INFO: An empty list is never a typo**
>
> A filter that matches nothing is `200` with an empty array. A *name* that does
> not exist is a `4xx`. Relying on this distinction is the difference between "we
> have no posts in Engineering" and "you spelled Engineering wrong".

## Codes you will actually meet

### Reading

| `code` | |
|---|---|
| `unknown_content_type` | No type with that slug. Carries `available_types`. |
| `not_a_collection` / `not_a_singleton` | Right type, wrong kind for the endpoint. |
| `entry_not_published` · `content_not_published` | It exists and is a draft. |
| `unknown_entry` | No entry with that id in this type and release. |
| `unknown_release` | No release with that `rel_…` id. |

### Blog and knowledge base

| `code` | |
|---|---|
| `unknown_blog_article` · `unknown_kb_article` | No such slug. Usually carries `did_you_mean`. |
| `blog_article_not_published` · `kb_article_not_published` | It exists and is a draft. Publish it. |
| `kb_article_archived` | Retired on purpose. Restore it, or remove the link. |
| `unknown_blog_category` · `unknown_kb_collection` · `unknown_kb_section` | A filter named something that does not exist. |
| `unknown_author` | No author with that slug. |

### Filtering and paging

| `code` | |
|---|---|
| `invalid_limit` | Outside 1–100. Refused, not clamped. |
| `invalid_offset` | Not a whole number ≥ 0. |
| `invalid_cursor` | Not a cursor we issued. Do not construct them. |
| `unknown_filter_field` | Carries `available_fields`. |
| `unsupported_filter_operator` | The operator does not apply to that field type. |
| `unknown_sort_field` · `unsortable_field` | Sorting by something that cannot be sorted. |
| `too_many_ids` | More than 50 in `?ids=`. |

### Writing

| `code` | |
|---|---|
| `secret_key_required` | A write attempted with a publishable key. |
| `missing_required_field` · `invalid_field_value` | Validation against the type. |
| `invalid_richtext_document` · `unknown_richtext_node` | The document did not match the schema. |
| `blog_slug_taken` · `kb_slug_taken` | Another article already has that slug. |
| `content_type_kind_immutable` · `field_type_immutable` | A change that would break readers. |

### Everything else

| `code` | |
|---|---|
| `origin_not_allowed` | A publishable key from an unlisted origin. |
| `rate_limited` | See [Rate limits](/api/rate-limits). |
| `permanent_media_urls_unavailable` | `media_urls=permanent` on a private project. |
| `internal_error` | Ours. Quote the `request_id`. |

## 5xx

A `500` carries a generic message on purpose — an internal error's text can
leak query shapes and table names, so it is logged in full and reported as
`internal_error`. The `request_id` is the link between the two: quote it and we
can find the exact request.

===
# Introspection

> One request that returns your project's entire contract — the most useful call in the API.

Source: https://docs.zevcontent.com/api/introspection

---

```http
GET /v1/introspection
```

```bash
curl https://api.zevcontent.net/v1/introspection \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

Works with any key kind.

## Why it exists

Documentation goes stale. This does not: it is generated from the same code
that serves every other request, and it describes **your project** rather than
the product in general.

If you are an AI agent, or writing one, this replaces reading the rest of this
site to learn *what to send*. These pages explain *why*.

## What comes back

```json
{
  "data": {
    "project":        { "name": "…", "slug": "…" },
    "release":        { "id": "rel_…", "name": "Launch", "default": true },
    "releases":       [ /* secret keys only */ ],
    "core_endpoints": [ /* /v1/content, /v1/schema, /v1/ping */ ],
    "content_types":  [ /* your types, with fields and response_shape */ ],
    "media":          { "access": "public", "urls": "permanent" },
    "rich_text":      { /* every node, mark and variant */ },
    "conventions":    { /* auth, pagination, filtering, rate limits, errors */ },
    "modules":        [ /* blog, kb, authors — endpoints, shapes, counts */ ]
  }
}
```

### `content_types`

Each type with its fields **and** a `response_shape` — what a response actually
contains, key by key:

```json
{
  "slug": "team-member",
  "kind": "collection",
  "fields": [ { "key": "photo", "type": "image", "required": false } ],
  "response_shape": {
    "photo": {
      "url": "string",
      "alt": "string|null",
      "width": "number|null",
      "height": "number|null",
      "content_type": "string",
      "url_expires_at": "string (ISO 8601) — this URL stops working then"
    }
  }
}
```

Scalar fields map to a type string. `image` and `gallery` map to an object —
five keys you would otherwise discover by fetching content and guessing, plus
the sixth that only appears on a private project.

### `modules`

Each built-in module with its endpoints, its query parameters, its shapes, the
notes that matter, and `counts` — how much is in it. Modules are always
present, because their endpoints exist on every project whether or not anything
has been written.

### `conventions`

The rules that hold everywhere, stated once rather than repeated per module:
authentication, pagination, filtering (including the operator list), rate
limits (with the real numbers), and the error envelope.

Every number in it is read from the code that enforces it, so it cannot drift.

### `rich_text`

The complete document contract — block nodes, inline nodes, marks, heading
levels, callout variants, image sources, embed providers, and the rules for
each. It is static and identical for every project, and it is here anyway,
because "write a richtext value" is unanswerable without it and the caller this
endpoint exists for has no documentation open.

## Secret and publishable keys see different things

> **WARNING: `releases` is secret-key only**
>
> A non-default release's `rel_…` id is its only address — staging by obscurity —
> and a publishable key ships in page source. Listing release ids to it would
> hand every visitor an index of your unreleased content.
>
> Publishable keys still see `release`, the one serving the request. The
> `releases` key is **absent** rather than empty, so a client can tell "not
> allowed to see" from "there are none".

Everything else is identical. The schema is not a secret to someone already
holding a key to the project, and hiding it would make every publishable-key
integration start with a guessing game.

## Counts and privacy

Module counts report **published** content only, and the knowledge base counts
only **visible** collections and sections.

This response is readable with a publishable key. "This project has fourteen
unpublished articles" is a fact about work in progress that a stranger reading
a page source should not learn, and counting a hidden collection would
advertise navigation nobody can reach.

## Reading a specific release

```bash
curl "https://api.zevcontent.net/v1/introspection?release=rel_…" \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

`content_types` then describes **that** release's schema, which is the point of
a staging release: the new shape, before it is live.

The built-in modules are release-independent, so their part of the response
does not change.

===
# Content

> Reading and writing your own content types — the /v1/content and /v1/schema endpoints.

Source: https://docs.zevcontent.com/api/content

---

The endpoints for the types **you** define. For the blog, knowledge base and
authors, see [Built-in modules](/modules/blog).

## Fetch a type

```http
GET /v1/content/{type}
```

`{type}` is the type slug, exactly as `content_types[].slug` reports it in
[introspection](/api/introspection).

A **singleton** answers with its values object. A **collection** answers with a
paginated array.

| Parameter | |
|---|---|
| `limit` | Collections only. 1–100, default 20. Refused outside that, not clamped. |
| `cursor` | Collections in their default order. Opaque. |
| `offset` | Collections when `sort` is used. |
| `where[…]` | Filter by the type's own fields. See [filtering](/api/pagination#filtering). |
| `sort` | A field key, or `created_at` / `published_at` / `updated_at`. `-` prefixes descending. |
| `ids` | Comma-separated `ent_…` ids, at most 50. Returns exactly those, in the sort order. |
| `release` | A `rel_…` id. Omit for the default release. |
| `media_urls` | `permanent` to refuse expiring image URLs. |

```bash
curl "https://api.zevcontent.net/v1/content/team-member\
?where[role]=engineer&sort=-joined&limit=10" \
  -H "Authorization: Bearer $ZEVCONTENT_KEY"
```

```json
{
  "data": [
    {
      "id": "ent_2c8RkXqGn4wVtYbMhJpDs",
      "values": { "name": "Ada Lovelace", "role": "engineer", "joined": "2024-03-01" },
      "published_at": "2026-08-14T09:00:00.000Z",
      "updated_at": "2026-08-20T11:12:00.000Z"
    }
  ],
  "meta": {
    "type": "team-member",
    "kind": "collection",
    "release": { "id": "rel_…", "name": "Launch", "default": true },
    "limit": 10,
    "has_more": false,
    "next_cursor": null,
    "next_offset": null
  }
}
```

> **INFO: Sorting changes the paging style**
>
> `sort` switches this endpoint from cursor to offset paging: `next_cursor` goes
> null and `next_offset` fills in. Read both keys and pass back whichever is set.

## Fetch one entry

```http
GET /v1/content/{type}/{entryId}
```

By its `ent_…` id. Use this for a detail page when you already hold the id;
filter the listing instead when you hold a slug-like field value.

Takes `release` and `media_urls`.

## Create an entry

```http
POST /v1/content/{type}/entries
```

**Secret key only.** Collections only.

```json
{
  "values": { "name": "Ada Lovelace", "role": "engineer" },
  "publish": true
}
```

`values` is keyed by field key and validated against the type: a missing
required field is `missing_required_field`, a wrong type is
`invalid_field_value`, an unknown key is `unknown_field` naming the ones that
exist.

Omitting `publish` creates a **draft**. That is the right default for a
migration script or an agent — content generated by a machine should usually be
reviewed before it is public.

## Save a singleton

```http
PUT /v1/content/{type}
```

**Secret key only.** Singletons only.

Replaces the singleton's draft with `values`, creating its one entry on first
save, and publishes it in the same call with `"publish": true`.

It is a replace, not a merge: `values` is the whole object. A key you omit is
cleared, not left alone.

## The schema itself

```http
GET /v1/schema/content-types
```

**Secret key only.** Every type definition with its fields — the same
definitions introspection embeds, on their own endpoint for a client that wants
the schema without the rest of the map.

```http
PUT /v1/schema/content-types/{type}
```

**Secret key only.** Create or update a type and its fields. This is how a
project is modelled from code rather than in the dashboard, and it is what lets
an agent set one up end to end.

Two things are immutable once set, because changing them breaks every frontend
already reading:

- A type's **kind** (`content_type_kind_immutable`). A singleton becoming a
  collection changes the response from an object to an array.
- A field's **type** (`field_type_immutable`). A `string` becoming a `number`
  changes what every reader receives.

Everything else — labels, options, order, adding and removing fields — is
editable.

## Only published content is served

`/v1/content` serves published entries. A draft is invisible here and visible
in the dashboard, which is what lets somebody work on a page for a week without
it appearing on your site.

An entry that exists but is not published answers `entry_not_published` rather
than pretending it does not exist.

===
# Blog

> Articles, categories and a resolved SEO chain — a built-in module you configure nothing for.

Source: https://docs.zevcontent.com/modules/blog

---

A built-in module: articles and categories whose schema ZevContent defines,
documents and maintains. Nothing is configured first — every project has these
endpoints, and they serve an empty list until somebody writes something.

Bylines come from the shared [authors](/modules/authors) module, not from here.

> **INFO: Release-independent**
>
> Blog rows hang off the **project**, not a release. `?release=` is neither
> needed nor honoured: publishing an article shows it immediately whatever
> release is default, cloning a release does not copy the back catalogue, and
> promoting one does not revert it. Custom content is the opposite — see
> [Releases](/concepts/releases).

## List articles

```http
GET /v1/blog/articles
```

Published articles, newest first by `published_at`. Cursor-paginated. `body` is
omitted — fetch one article for it.

| Parameter | |
|---|---|
| `limit` | 1–100, default 20 |
| `cursor` | `meta.next_cursor` from the previous page |
| `category` | A category **slug**. Matches an article carrying it anywhere in `categories`. Unknown → error. |
| `author` | An author **slug**. Matches anywhere in `authors`, so a co-authored post appears on both pages. Unknown → error. |
| `tag` | An exact tag. No match → empty list. |
| `q` | Case-insensitive substring of title or excerpt |
| `media_urls` | `permanent` to refuse expiring image URLs |

`q` combines with `category` and `author` — which is how a category page or an
author page offers search **within its own articles** without a second
endpoint.

## One article

```http
GET /v1/blog/articles/{slug}
```

The whole article, with `body` as `{ html, json, plain, toc }`, every image
resolved, and the same `toc` beside the article so a sidebar table of contents
does not have to reach inside the body.

An unknown slug teaches with `did_you_mean`; a slug that exists but is a draft
says so (`blog_article_not_published`).

## Categories

```http
GET /v1/blog/categories
```
```http
GET /v1/blog/categories/{slug}
```

Every category alphabetically, each with `article_count`, its `featured_image`
and its resolved `seo` — enough to build blog navigation, section cards
included, from one request.

A category page is **two requests and never more**: the page itself, and
`GET /v1/blog/articles?category={slug}` for its articles, which pages and takes
`q`.

## The article shape

```json
{
  "id": "art_…",
  "slug": "how-we-deploy",
  "title": "How we deploy",
  "excerpt": "A short tour of the pipeline.",
  "body": { "html": "…", "json": {}, "plain": "…", "toc": [] },
  "toc": [{ "level": 2, "text": "The pipeline", "id": "the-pipeline" }],
  "featured_image": { "url": "…", "alt": "…", "width": 1600, "height": 900, "content_type": "image/jpeg" },
  "authors": [{ "id": "aut_…", "name": "Ada", "slug": "ada", "bio": "…", "avatar": null, "social": {} }],
  "categories": [{ "id": "cat_…", "name": "Engineering", "slug": "engineering", "description": null }],
  "tags": ["deploys", "ci"],
  "published_at": "2026-08-14T09:00:00.000Z",
  "updated_at": "2026-08-20T11:12:00.000Z",
  "reading_time_minutes": 6,
  "word_count": 1180,
  "seo": { "title": "…", "description": "…", "og_image": {}, "canonical_url": null, "noindex": false }
}
```

`body` and `toc` appear on one article only, never in a listing. Twenty full
rich text documents, each rendered three ways, is a response measured in
megabytes for a page that shows twenty cards.

## Arrays, and the first element

`authors` and `categories` are **ordered arrays**, and the first element of
each is the primary one:

- `authors[0]` is the lead byline — the name to print when there is room for
  one.
- `categories[0]` is the primary section — the breadcrumb, the eyebrow label,
  the section URL.

The order is the one a writer chose. Render it as given; never re-sort.

Both may be **empty** — an unattributed post and an uncategorised one are both
ordinary — but neither is ever null, so map over them without a check.

> **WARNING: There is no singular `author` or `category`**
>
> Two names for one thing is how a contract rots: the singular would have to mean
> `authors[0]`, and the day somebody set one without the other there would be no
> rule for which won. Use element 0.

## References and pages

Nested inside an article, an author and a category are **references** — the
byline and the breadcrumb. They carry no `article_count` and no `seo`, because
a card printing twenty bylines will never render twenty og images.

On their own endpoints they are **pages** and carry those as well. The category
page is `/v1/blog/categories/{slug}`; the author page is `/v1/authors/{slug}`,
which is **not** under `/v1/blog`.

## Categories and tags are different things

A **category** is a taxonomy term with a page of its own: a slug, a
description, an image, an SEO object, and a URL. A **tag** is a free-form label
with no page — many per article, matched exactly by `?tag=`.

If you find yourself wanting a page for a tag, it should have been a category.

## SEO

Every article and category carries a complete, resolved `seo` object. Do not
reimplement the fallback chain — see [SEO](/concepts/seo).

## Notes

- Everything here is **read-only** and works with any key kind. Articles are
  written in the dashboard.
- Only **published** articles are served. A draft is a 404 that says it is a
  draft.
- A future `published_at` does **not** publish an article by itself.
  Scheduling is not built.
- The body is rich text at schema version 2. An article written before schema 2
  keeps `"version": 1` and renders exactly as it always did — see
  [Rich text](/concepts/rich-text).

===
# Knowledge base

> A help centre with a navigation tree, freshness dates and helpful/not-helpful voting.

Source: https://docs.zevcontent.com/modules/knowledge-base

---

A built-in module: collections holding sections holding articles, each with a
byline, a freshness date and a helpful/not-helpful tally. Nothing is configured
first — every project has these endpoints whether or not anything is written.

Like the blog, it is **release-independent**: `?release=` is neither needed nor
honoured.

## Two things it has that a blog does not

**Order is the answer.** Every listing comes back in the order somebody dragged
it into — collection, then section, then the manual order inside it. There is
deliberately no `sort` parameter anywhere in this module. A help centre in date
order is not a help centre.

**Freshness.** Whether an answer is still believed to be true. A help article
that was correct in March and is wrong now is worse than no article, so an
article records when somebody last confirmed it.

## The tree

```http
GET /v1/kb/tree
```

Visible collections with their sections **nested inside**, in reading order,
with an article count on every node. One request draws a whole sidebar.

```json
{
  "data": [
    {
      "id": "kbc_…",
      "slug": "getting-started",
      "title": "Getting started",
      "description": "The first ten minutes.",
      "image": null,
      "sections": [
        { "id": "kbs_…", "slug": "accounts", "title": "Accounts", "description": null, "article_count": 4 }
      ],
      "article_count": 9,
      "seo": { "title": "Getting started", "description": "…", "og_image": null, "canonical_url": null, "noindex": false }
    }
  ],
  "meta": { "module": "kb", "release_independent": true, "limit": 20, "offset": 0, "has_more": false, "next_offset": null }
}
```

Sections are nested rather than served flat with a `collection_id` on each — a
sidebar is a tree, and regrouping a flat list to draw one is work already done
for you.

**Collections page; the sections inside them do not.** A section only means
anything as part of the collection that holds it, and splitting a node from its
children would make the tree unbuildable.

Hidden collections and sections are **omitted entirely** — absent, not marked.

## List articles

```http
GET /v1/kb/articles
```

Published articles in reading order. `body` is omitted; fetch one article
for it. Each item carries its resolved breadcrumb, byline, freshness and votes.

| Parameter | |
|---|---|
| `limit` | 1–100, default 20 |
| `offset` | Use `meta.next_offset` |
| `collection` | A collection **slug**. Everything beneath it, sections included. |
| `section` | A section **slug**. |
| `q` | Case-insensitive substring of title or summary |
| `media_urls` | `permanent` to refuse expiring image URLs |

An unknown `collection` or `section` is a **404 naming the real ones**, not an
empty list and never the whole knowledge base.

## One article

```http
GET /v1/kb/articles/{slug}
```

The whole article: rendered `body`, its `toc`, the resolved breadcrumb and
byline, `freshness` and the vote tally.

> **INFO: Slugs survive a reorganisation**
>
> Moving an article between sections does **not** change its slug, so
> `/help/{slug}` URLs keep working after the tree is rearranged. Build your
> routes on the slug, not on the breadcrumb.

## The article shape

```json
{
  "id": "kba_…",
  "slug": "install-the-cli",
  "title": "Install the CLI",
  "summary": "Get the CLI on your machine.",
  "collection": { "id": "kbc_…", "slug": "getting-started", "title": "Getting started" },
  "section": { "id": "kbs_…", "slug": "accounts", "title": "Accounts" },
  "authors": [{ "id": "aut_…", "slug": "ada", "name": "Ada", "bio": "…", "social": {} }],
  "tags": ["setup", "cli"],
  "published_at": "2026-09-01T14:30:35.486Z",
  "updated_at": "2026-09-01T23:14:10.566Z",
  "word_count": 420,
  "reading_time_minutes": 3,
  "freshness": { "last_reviewed_at": "2026-09-01T23:14:10.566Z", "is_stale": false, "days_until_review": 180 },
  "votes": { "helpful": 12, "not_helpful": 3, "total": 15, "score": 80 },
  "seo": { "title": "…", "description": "…", "og_image": null, "canonical_url": null, "noindex": false }
}
```

### `section` can be null

An article belongs to exactly one collection and **at most** one section.
`section` is null when it sits directly in its collection — an "Overview" or
"Start here" article usually does.

The key is always present, so check the value, not the key. A breadcrumb built
blindly as `collection › section › title` renders "› null" on the commonest
kind of overview page.

### `freshness`

Always present, never null as an object.

- `last_reviewed_at` — when somebody last confirmed this is still correct.
- `is_stale` — reviewed, and the review has lapsed.
- `days_until_review` — negative once overdue, null when never reviewed.

A never-reviewed article is `last_reviewed_at: null` with `is_stale: false`,
because "nobody has checked" is not the same claim as "this is out of date".

Nothing is hidden on the strength of it: a stale article is still served. Show
a "last reviewed" notice, or demote it in your own search — that is your call.

### `votes`

Always present, zeroed for an article nobody has voted on. Served in listings
as well as on one article, so a card can print "12 of 15 found this helpful"
without a second request.

## Voting

```http
POST /v1/kb/articles/{slug}/vote
```

The **only write** on `/v1/kb`, and the only endpoint in ZevContent a reader's
browser calls directly.

```json
{ "helpful": true }
```

```json
{
  "data": { "helpful": 13, "not_helpful": 3, "total": 16, "score": 81, "your_vote": true },
  "meta": { "module": "kb", "release_independent": true }
}
```

> **WARNING: Use a publishable key, never a secret one**
>
> This call is made from a browser. A secret key in a browser bundle is a secret
> key published. Use a `pk_…` key with your site in its origin allow-list.

- `helpful` must be a **real JSON boolean**. The string `"true"` is refused
  rather than guessed at, because on the one endpoint a stranger can write to,
  a body that records the opposite of what it says is not acceptable.
- **One vote per visitor per article.** Voting again *changes* the vote rather
  than adding one, so a tally cannot be inflated by clicking twice.
- **No address is stored.** A repeat voter is recognised by a keyed digest that
  includes the article id, so it cannot be reversed into an address or joined
  across articles into a reading history.
- It draws on the separate `vote` budget — 30 a minute. See
  [Rate limits](/api/rate-limits).

## Notes

- Everything except the vote is **read-only** and works with any key kind.
- Only **published** articles are served. A draft is a 404 that says it is a
  draft; an **archived** article disappears from `/v1` the moment it is
  archived while staying in the dashboard, so a help centre never serves a
  retired answer.
- The tree is the navigation and the article list is the content: two requests,
  not more. `GET /v1/kb/tree` draws the sidebar,
  `GET /v1/kb/articles?collection={slug}` fills the page, and both page
  independently.
- `tags` are free-form labels, browsable in the dashboard. There is no public
  tag filter on this module.
- There is no `?author=` filter here. `kb_article_count` on an author tells you
  how many they have written; if you need a page listing them, ask — it is an
  addition, not a workaround.

===
# Authors

> One directory of people, shared by every module that credits anybody.

Source: https://docs.zevcontent.com/modules/authors

---

A built-in module: the people who write. One person is one row whether they
write blog articles, knowledge base articles or both — which is why this lives
at `/v1/authors` and not under `/v1/blog`.

Release-independent, like the other modules.

## List authors

```http
GET /v1/authors
```

Every author alphabetically, each with their avatar, their three article counts
and the resolved `seo` of their page — enough to build a contributors page from
one request.

Takes `limit`, `offset` and `media_urls`.

## One author

```http
GET /v1/authors/{slug}
```

```json
{
  "data": {
    "id": "aut_…",
    "name": "Ada Lovelace",
    "slug": "ada",
    "bio": "Writes about deploys.",
    "avatar": { "url": "…", "alt": "…", "width": 400, "height": 400, "content_type": "image/jpeg" },
    "social": {
      "website": "https://ada.example.com",
      "x": "https://x.com/ada",
      "x_handle": "ada",
      "github": "https://github.com/ada",
      "github_handle": "ada",
      "linkedin": "https://linkedin.com/in/ada",
      "mastodon": null
    },
    "article_count": 14,
    "blog_article_count": 9,
    "kb_article_count": 5,
    "seo": { "title": "Ada Lovelace", "description": "Writes about deploys.", "og_image": {}, "canonical_url": null, "noindex": false }
  },
  "meta": { "module": "authors", "release_independent": true }
}
```

An unknown slug teaches with `did_you_mean` and names every author slug that
exists.

## Choose the count deliberately

Three numbers, and picking the wrong one is the mistake this module invites:

- **`article_count`** — every module together. What an author page across the
  whole site wants.
- **`blog_article_count`** — what a blog index means by "9 articles" under a
  byline.
- **`kb_article_count`** — knowledge base articles.

Printing the total under a blog byline overstates it for anyone who also writes
help articles.

> **INFO: Why `article_count` means the total**
>
> It was the blog's count when the blog was the only module that credited
> anyone. Rather than rename it — which would have removed a key integrations
> depend on — it now means what the word actually describes, with the two
> breakdowns added beside it. No key disappeared.

## Social links

Both forms are served, resolved for you:

- `x_handle` / `github_handle` — the handle, stored without an `@`. Print this.
- `x` / `github` / `linkedin` / `mastodon` / `website` — the full URL. Link
  this.

Each is a string or null. You never have to build a profile URL from a handle,
or strip one out of a URL to display it.

## An author page is two requests

The person, and their articles:

```
GET /v1/authors/ada
GET /v1/blog/articles?author=ada&limit=20
```

There is no "articles by this author" endpoint, because the listing endpoint
already filters, pages and searches. `?author=` matches an article crediting
that person **anywhere** in its `authors`, so a co-authored post appears on
both authors' pages.

> **WARNING: The knowledge base has no `?author=` filter**
>
> `kb_article_count` tells you how many knowledge base articles somebody has
> written; there is no public endpoint that lists them. If you need that page,
> ask — it is an addition, not something to work around.

## References and pages

Nested inside an article, an author is a **reference**: id, name, slug, bio and
`social`. No `article_count`, no `avatar` on the knowledge base's byline, and
no `seo` — those belong to the page, and a card printing twenty bylines will
never render twenty og images.

Fetch `/v1/authors/{slug}` for the page shape.

## Notes

- **Read-only**, any key kind. Authors are managed in the dashboard.
- These URLs were `/v1/blog/authors` before launch and moved when the knowledge
  base began crediting the same people. The old paths are gone, not redirected.