Conventions

The external API is uniform: every list endpoint paginates the same way, every error has the same shape, and every single-resource route accepts a UUID or a slug. Learn these once and the rest of the reference reads itself.

Base URL

Every external route is prefixed with /api/v1/external/:

https://api.clog.dev/api/v1/external/posts
https://api.clog.dev/api/v1/external/pages/about
https://api.clog.dev/api/v1/external/redirects

Clog is a hosted service — https://api.clog.dev is the same base URL for every consumer. The workspace is implicit from the API key — paths never carry a :workspaceId segment.

Headers

Resource identifiers — idOrSlug

Single-resource routes accept either a UUID (resolved by id) or any other string (resolved by slug), scoped to the bound workspace:

# By id
curl https://api.clog.dev/api/v1/external/posts/0a4b3c2d-... -H "X-API-Key: clog_live_xxx"

# By slug
curl https://api.clog.dev/api/v1/external/posts/my-first-post -H "X-API-Key: clog_live_xxx"

Whichever you pass, the response shape is identical.

Response envelopes

Single resource

A single-resource read or write returns the resource object directly — no wrapper:

{
  "id": "0a4b3c2d-...",
  "slug": "my-first-post",
  "title": "My first post",
  "bodyJson": [ /* ... */ ]
}

Paginated list

Every list endpoint returns a uniform PaginatedResponse:

{
  "data": [ /* items[] */ ],
  "page": 1,
  "pageSize": 10,
  "order": "desc",
  "orderBy": "publishedAt",
  "total": 42,
  "totalPages": 5
}

Pagination

All list endpoints accept the same four query params:

Example — second page of 25 published posts by newest first:

curl 'https://api.clog.dev/api/v1/external/posts?status=published&page=2&pageSize=25&order=desc&orderBy=publishedAt' \
  -H "X-API-Key: clog_live_xxx"

Filtering

Filters are passed as query params. The available filters vary per endpoint — the reference pages enumerate them — but a few patterns recur:

Error envelope

Every error response — regardless of status — returns the same JSON shape:

{
  "code": "BAD_REQUEST",
  "message": "Invalid post body: 'title' is required.",
  "details": { /* optional, see below */ }
}

Error codes

Handling errors

async function fetchPost(slug: string) {
  const res = await fetch(
    `https://api.clog.dev/api/v1/external/posts/${slug}`,
    { headers: { 'X-API-Key': process.env.CLOG_API_KEY! } },
  );

  if (res.status === 404) return null;          // post doesn't exist; treat as missing
  if (!res.ok) {
    const err = await res.json().catch(() => ({ code: 'INTERNAL', message: res.statusText }));
    throw new Error(`Clog ${err.code}: ${err.message}`);
  }

  return res.json();
}

Branch on code, not on the human-readable message — messages are not part of the API contract and may change without notice.

Date and time

All timestamps are ISO 8601 strings in UTC ("2026-05-23T12:34:56.789Z"). All dateFrom / dateTo filters accept the same format. There is no separate date-only type in v1.

Idempotency and retries

• Reads (GET) are safe to retry — they don't mutate state.
• Soft-delete on DELETE — deleting a post or page stamps deletedAt and frees the slug. The body returned is the pre-delete snapshot with deletedAt set; the row is hidden from all subsequent reads.
• Tag attach / detach is idempotent: re-attaching an attached tag (or detaching a missing one) is a silent no-op.
• Link-health reports (POST /external/link-health) upsert on (workspaceId, path) and bump hitCount — repeat reports for the same path are explicitly safe to send.

For other write operations, treat retries as you would any non-idempotent HTTP call: retry only after confirming the prior call did not commit, and prefer idempotent designs in your own code (e.g. by computing a deterministic slug client-side).

Related

• Authenticating requests — the X-API-Key contract.
• Rendering content — what the post / page response actually looks like and how to render it.
• Endpoint reference — the full per-endpoint spec.
• Reference → Error codes — the same error-code list as a lookup page.