Architecture

Clog exposes a single API for integration — the external API at /api/v1/external/*, authenticated with a workspace-bound key in the X-API-Key header. You author content in the Clog dashboard and issue API keys from it; your application calls the external API.

The API surface

The external API's endpoints mirror the content modules — posts, pages, categories, tags, authors, media — plus the operational helpers redirects, link-health, workspace, and feeds/sitemap-data. The full catalogue lives in the API reference.

Where you fit

┌────────────────────┐                  ┌──────────────────────────┐
│   Clog dashboard   │      HTTPS       │                          │
│       (UI)         │ ───────────────► │   Clog backend           │
└────────────────────┘                  │   (Postgres +            │
                                        │    object storage)       │
                                        │                          │
                                        │  /api/v1/external/* (key)│
                                        └──────────────────────────┘
                                                  ▲
                                                  │ X-API-Key
                                                  │ HTTPS
                                                  │
                                        ┌─────────┴────────────────┐
                                        │   YOUR APPLICATION       │
                                        │  (marketing site,        │
                                        │   docs portal, app)      │
                                        └──────────────────────────┘

You issue an API key from the Clog dashboard, store it server-side, and call the external API from your own backend or build-time fetcher. Render the returned blocks however you want.

Keep API keys server-side. The key grants the creator's full workspace permissions — anyone who exfiltrates it from a browser bundle can read (and potentially write) your content. Fetch from your server / build process, not from the browser.

Why headless

Clog renders no public-facing pages. There is no hosted blog at /blog, no sitemap.xml, no rss.xml — just structured JSON. That means:

You own the URL structure. Posts can live at /blog/<slug>, /articles/<slug>, or anywhere else. Clog stores slugs; your site decides paths.
You own the styling. The block renderer is yours.
You own caching. Fetch at build time, request time, or anywhere in between.
You handle SEO surfacing. Clog gives you a pre-assembled JSON-LD payload and per-entity SEO meta; you stamp them into your <head>. See API → SEO and JSON-LD.

In return, Clog handles the parts you don't want to: a typed block schema, image storage with URL enrichment, slug-change auto-redirects, broken-link reporting, a Schema.org type wizard, and a live SEO scorer.

What ships as data, not as a feature

A few traditional CMS deliverables are returned as rows you stamp, not pages Clog hosts:

Redirects — GET /external/redirects returns the workspace's redirect table; your edge or middleware replays them. See API → Redirects and link health.
Broken-link reporting — your site POSTs every 404 to /external/link-health; the dashboard turns the entries into redirects, marks them fixed, or ignores them.
Sitemap data — GET /external/feeds/sitemap-data returns a JSON array of { url, lastmod, changefreq, priority }; you stamp the XML.

A typical request

Every external API request has the same shape:

GET /api/v1/external/posts/my-first-post HTTP/1.1
Host: api.clog.dev
X-API-Key: clog_live_xxx

The backend:

Hashes the key and looks up the ApiKey row in constant time.
Resolves the creator's current Membership on the bound workspace.
Enforces the required permission for the route (posts:read here).
Returns the resource — or 401 if the key is unknown / revoked / expired, 403 if the membership doesn't carry the permission.

See API → Authenticating requests for the full error semantics and API → Conventions for the envelope.

What's next

Quickstart — wire it up end-to-end.
API → Conventions — pagination, ordering, filtering, the error envelope.
Examples → Next.js — a worked App Router integration.