Public Content API

A read-only JSON API served by the standalone admin server, with per-collection opt-in, scoped API keys, and an auto-generated OpenAPI spec. Built for AI agents, integrations, and external tools.

Enabling

Open Settings → Public API in the admin. Set Public API collections to a comma-separated list of collection IDs (e.g. posts, pages), or * to expose every collection. Leave blank to keep the API disabled — no collections are exposed by default.

Endpoints

Discovery

GET /api/public

Lists all publicly accessible collections, entry counts, and links to the OpenAPI spec and llms.txt. This is the entry point for an agent exploring your site.

{
  "name": "My Site",
  "description": "...",
  "url": "https://your-site.com",
  "auth": "bearer",
  "collections": [
    { "id": "posts", "label": "Posts", "total": 12, "url": "https://your-site.com/api/public/posts" }
  ],
  "links": {
    "openapi": "https://your-site.com/api/public/openapi.json",
    "llms": "https://your-site.com/llms.txt"
  }
}

List entries

GET /api/public/[collection]?limit=20&offset=0&q=keyword

limit defaults to 20, max 100. q does a simple case-insensitive substring match against title, excerpt, and body.

{
  "collection": "posts",
  "total": 12,
  "limit": 20,
  "offset": 0,
  "entries": [
    {
      "slug": "my-first-post",
      "title": "My First Post",
      "excerpt": "...",
      "date": "2026-06-01",
      "author": "Jane Doe",
      "image": "https://your-site.com/media/...",
      "tags": ["astro", "cms"],
      "url": "https://your-site.com/posts/my-first-post"
    }
  ]
}

Single entry

GET /api/public/[collection]/[slug]

Same shape as the list, plus body (full HTML), publishedAt, and seo { title, description }. Returns 404 if the entry doesn't exist or isn't published.

OpenAPI spec

GET /api/public/openapi.json

An OpenAPI 3.1 document auto-generated from your opted-in collections — paths, parameters, and response schemas for every endpoint above. Feed it to any OpenAPI-aware tool or agent for structured discovery.

Authentication (API keys)

By default the Public Content API is open to anyone once a collection is opted in. To require a Bearer token, enable Require API key in Settings → Public API, then generate one or more keys under API Keys. Each key is shown once on creation — copy it immediately.

curl -H "Authorization: Bearer orb_..." https://your-site.com/api/public/posts

Requests without a valid key return 401 Unauthorized when a key is required. Each key tracks a hit counter and last-used date, visible in Settings, so you can see which integrations are actually using the API and revoke unused keys.

Access control summary

Only status: 'published' entries are ever returned — drafts and scheduled entries are never exposed through this API.

Use cases

• AI agents and RAG pipelines pulling structured content (also see the MCP Server for tool-based access)
• Third-party integrations that need scoped, revocable credentials instead of a single shared token
• Search or discovery tools that consume the OpenAPI spec directly