Content API

Content API

/v1 is the one surface built for somebody else’s software. It is versioned and read-only.

curl -H "Authorization: Bearer $TOKEN" https://api.staleless.com/v1/pages
curl -H "Authorization: Bearer $TOKEN" https://api.staleless.com/v1/pages/guides/install

Why /v1 and not /api

/api is what the writer calls, and it changes when the writer changes. /v1 is the shape other people’s code depends on, so it is versioned and it does not move underneath you.

Endpoints

GET /v1/pagesendpoint

Every published page, sorted by path.

{
  "pages": [
    { "path": "/guides/install", "file": "pages/guides/install.md", "title": "Installing" }
  ]
}

GET /v1/pages/{path}endpoint

One page: its frontmatter and its Markdown.

{
  "path": "/guides/install",
  "file": "pages/guides/install.md",
  "frontmatter": { "title": "Installing", "review_every": 90 },
  "markdown": "Install it with npm...\n"
}

GET /v1/healthendpoint

What is wrong with this documentation right now: the same state staleless check reports.

Markdown, not HTML

Deliberately. You asked for the content because you are rendering it in your own product with your own styles. HTML from here would carry our classes and our idea of what a callout looks like.

What “published” means in the response

The Markdown is what the published page says, not what the file says:

• {{variables}} are resolved;
• snippets are spliced in;
• a page marked draft is absent, and returns 404.

Your renderer has neither a variable table nor a snippet store, and no reader of the site is shown a draft either.

Authentication

A bearer token with docs:read. The token names its project, so there is no workspace header to get wrong.

See Tokens.

Rate limit

600 reads a minute, per token. Keyed on the token rather than on the workspace, so one runaway script cannot throttle anybody else.

Over the limit you get 429 with a retryAfter in seconds.

Paths

/v1/pages/guides/install resolves in this order:

1. pages/guides/install.md
2. pages/guides/install/index.md
3. pages/guides/install

A path containing .. is refused. Nothing here touches a filesystem: the only paths that can be answered are keys in your project’s own file map.

What is not here

Writing. The content API is read-only. To write, use MCP or your repository.

Availability

The content API is a Pro capability, with higher limits on Business. See Plans.