API and webhooks

How it works

When a blog publishes through the API, your site reads its published articles from ByDefault and renders them itself. Open Publishing, pick the blog and choose API as its method. Its API page gives you a key, the endpoint, and a place for a webhook URL. We call that URL every time an article is published, updated or unpublished.

The API serves each article as it was when you last published it. Edits in the editor stay private until you publish again.

Authentication

Send the key from the blog's API page as a bearer token:

Authorization: Bearer bd_live_…

Each blog has its own key, and the key decides which blog's articles you get. Keep it on your server, for example as BYDEFAULT_API_KEY: anyone with it can read your published articles. Make a new key on the API page and the old one stops working at once.

List articles

GET /api/v1/articles returns your live articles, newest first, up to 100 per page. Page through them with limit (1 to 100) and offset. hasMore tells you whether another page follows.

curl "https://www.bydefault.so/api/v1/articles?limit=20" \
  -H "Authorization: Bearer $BYDEFAULT_API_KEY"

{ "articles": [ … ], "hasMore": false }

Get one article

GET /api/v1/articles/:slug returns { "article": … }, or a 404 when no live article has that slug.

{
  "article": {
    "id": "art_8f2c…",
    "slug": "how-to-rank-in-google-ai-mode",
    "title": "How to rank in Google AI Mode",
    "description": "What AI Mode cites, and how to be one of its sources.",
    "content": "AI Mode answers with a handful of sources…",
    "url": "https://example.com/blog/how-to-rank-in-google-ai-mode",
    "authors": [{ "name": "Jonas", "avatarUrl": "https://cdn.bydefault.so/avatar/…" }],
    "topic": { "id": "top_41a…", "name": "AI search" },
    "publishedAt": "2026-10-20T09:12:00.000Z",
    "updatedAt": "2026-10-20T11:40:00.000Z"
  }
}

Every image, in the body and in the authors' photos, is on cdn.bydefault.so. That's the one host to allow, in next/image or in a content security policy's img-src.

Webhooks

Add a URL under Webhooks on the API page and we POST to it whenever an article changes, so your site can rebuild or revalidate that page. Send test sends one right away with your newest article.

{ "event": "published", "article": { …the article, as above… } }

Every request carries three headers: X-ByDefault-Event, X-ByDefault-Delivery (one id per attempt) and X-ByDefault-Signature.

Answer with any 2xx within 10 seconds. If your site answers with anything else, or doesn't answer, we try again up to 3 times. Every attempt shows on the API page with what your site answered.

Verify a webhook

The signature is sha256= followed by the HMAC-SHA256 of the raw body, keyed with your API key. Check it before you trust the body:

import { createHmac, timingSafeEqual } from 'node:crypto'

export async function POST(request: Request) {
  const body = await request.text()
  const expected = 'sha256=' +
    createHmac('sha256', process.env.BYDEFAULT_API_KEY!).update(body).digest('hex')
  const given = request.headers.get('x-bydefault-signature') ?? ''
  if (given.length !== expected.length ||
      !timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return new Response('Bad signature', { status: 401 })
  }
  const { event, article } = JSON.parse(body)
  // Rebuild or revalidate the page at article.slug here.
  return new Response('OK')
}

Troubleshooting