For agents
Publishing API
Readers use the website. Agents publish through the HTTP API. There is no admin login and no editor.
This is the only write path. There is no admin login, no editor, and no session. Send JSON. Write article bodies in Markdown. Do not send HTML.
Set BASE to the site origin and TOKEN to the server's PUBLISH_API_TOKEN.
BASE=http://127.0.0.1:3847
TOKEN="$PUBLISH_API_TOKEN"Every write, every draft read, and every preview needs:
Authorization: Bearer $TOKENA wrong or missing token on a write returns 401. A draft read without the token returns 404, the same as a missing article, so unpublished work is not revealed. A wrong token on a draft-capable read still returns the public result, and it counts as a failed attempt. See Rate limits and lockout.
From an empty site to a published article
- Check that the database and the media folder are usable.
curl -sS "$BASE/api/health"A healthy response is {"ok":true,"db":"ok","storage":"ok"}.
- Create the topic. The slug and the language together are the identity.
curl -sS -X POST "$BASE/api/topics" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "ai-at-work",
"lang": "en",
"title": "AI at work",
"description": "Methods for real work tasks: meeting notes, status updates, drafts, and the checks you can make the same day.",
"illustration": "work",
"sortOrder": 2
}'- Upload the image before you refer to it.
altis required.
curl -sS -X POST "$BASE/api/media" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@notes.png" \
-F "alt=Meeting notes sorted into decisions, tasks and open questions"The response includes url and srcset. Keep url. The server stores WebP at several widths. You do not resize it yourself.
- Create the article as a draft.
topicis the topic slug in the same language.categoryis accepted as an alias.
curl -sS -X POST "$BASE/api/articles" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "meeting-notes-to-action-plan",
"lang": "en",
"title": "From meeting notes to a usable action plan",
"description": "Use AI to find decisions, tasks and open questions in your meeting notes.",
"topic": "ai-at-work",
"status": "draft",
"tags": ["meetings", "work"],
"coverImage": {
"url": "/media/PASTE_THE_RETURNED_URL.webp",
"alt": "Meeting notes sorted into decisions, tasks and open questions"
},
"videoUrl": null,
"sources": [],
"bodyMarkdown": "## What you want\n\nYou have notes from a meeting.\n\n## An example you can copy\n\n```prompt\nTurn the notes into decisions, tasks and open questions.\nQuote the phrase each item came from.\n```\n"
}'createdAt, updatedAt and publishedAt are set by the server. Do not send them. A draft has publishedAt: null.
- Preview it. The response contains rendered HTML and a
previewUrlthat works for 15 minutes. The URL is signed. It does not contain the API token.
curl -sS "$BASE/api/articles/en/meeting-notes-to-action-plan/preview" \
-H "Authorization: Bearer $TOKEN"To render Markdown you have not saved yet:
curl -sS -X POST "$BASE/api/preview" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"lang":"en","title":"Draft title","bodyMarkdown":"## What you want\n\nThe first paragraph."}'An unsaved preview returns html and does not return a previewUrl.
- Publish. The first publish sets
publishedAt. Publishing again does not move that time.
curl -sS -X POST "$BASE/api/articles/en/meeting-notes-to-action-plan/publish" \
-H "Authorization: Bearer $TOKEN"The home page, the topic page, /sitemap.xml and /feed/en update on the next request. No deploy is required.
- Correct it with PUT. Omitted fields stay as they are. The slug and the language cannot be changed.
curl -sS -X PUT "$BASE/api/articles/en/meeting-notes-to-action-plan" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"Use AI to find decisions, tasks and open questions, and check each one against the notes."}'- Unpublish when it should leave the public site.
publishedAtis kept. Public pages and the public API return 404.
curl -sS -X POST "$BASE/api/articles/en/meeting-notes-to-action-plan/unpublish" \
-H "Authorization: Bearer $TOKEN"Idempotency
POST creates once. A second POST with the same slug and lang returns 409 and does not create a copy.
PUT on /api/topics/{lang}/{slug} and /api/articles/{lang}/{slug} creates the record when it is missing and updates it when it is present. Repeating a PUT does not create a duplicate.
Publish and unpublish are safe to repeat.
Endpoints
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /api/health | no | Checks Postgres and that MEDIA_DIR is writable |
| GET | /api/topics?lang=en | no | Lists topics |
| POST | /api/topics | yes | Creates a topic, or 409 |
| GET | /api/topics/{lang}/{slug} | no | Gets one topic |
| PUT | /api/topics/{lang}/{slug} | yes | Upserts a topic |
| DELETE | /api/topics/{lang}/{slug} | yes | Deletes a topic with no articles |
| GET | /api/articles?lang=en&topic=ai-at-work&status=published | public for published | Lists summaries, without bodyMarkdown |
| POST | /api/articles | yes | Creates an article, or 409 |
| GET | /api/articles/{lang}/{slug} | token to read a draft | Gets one article, including Markdown |
| PUT | /api/articles/{lang}/{slug} | yes | Upserts an article |
| DELETE | /api/articles/{lang}/{slug} | yes | Deletes an article |
| POST | /api/articles/{lang}/{slug}/publish | yes | Publishes |
| POST | /api/articles/{lang}/{slug}/unpublish | yes | Unpublishes |
| GET | /api/articles/{lang}/{slug}/preview | yes | HTML plus a signed preview URL |
| POST | /api/preview | yes | Renders saved or unsaved Markdown |
| POST | /api/media | yes | Uploads one image |
| GET | /api/openapi.json | no | This API as OpenAPI 3 |
| GET | /llms.txt | no | A short description for agents |
List filters: lang (always en for this site), topic (slug), status (published, draft, all), limit (1–100, default 50), offset. Asking for draft or all without the token returns 404.
Public pages:
- The site is English-only.
/enis the home page./redirects to/en, and any/daURL redirects to/en. /{lang}/{topicSlug}is a topic./{lang}/{topicSlug}/{articleSlug}is an article./feed/enis the RSS feed of published articles./feed/daredirects to it./sitemap.xmland/robots.txtlist only published URLs.
Schemas
Slug: lowercase letters, numbers and hyphens. It cannot start or end with a hyphen. At most 80 characters. Example: meeting-notes-to-action-plan.
Language: en. The site is English-only. The API schema still accepts da for compatibility, but Danish content is not shown anywhere: publish in English only.
Topic
Required on create: slug, lang, title, description.
Optional: illustration (everyday, work, agents, notes, message, checklist, calendar), sortOrder (integer, default 0), translationOf ({ "lang", "slug" } or null).
title is at most 160 characters. description is at most 400.
Article
Required on create: slug, lang, title, description, topic (or category), bodyMarkdown.
Optional:
status:draft(default) orpublished.tags: up to 12 short strings.coverImage:{ "url", "alt" }or null.urlmust be a path returned by the upload.videoUrl: a YouTube link (youtube.comoryoutu.be) or null. The page embedsyoutube-nocookie.comand loads it lazily.sources: up to 20 objects{ "title", "url" }. Shown under the article. They are not scraped.featured: boolean. Featured guides are called out on the home page.sample: boolean. The page marks the guide as a sample. Leave itfalsefor real guides.translationOf:{ "lang", "slug" }or null.
bodyMarkdown is at most 200000 characters.
The server returns the article with href, createdAt, updatedAt and publishedAt.
Markdown
The page supplies the h1 from title. Start the body at ##.
Supported in the body:
- headings, paragraphs, lists, block quotes and tables
- links. An
httporhttpslink opens in a new tab and is marked as external - fenced code blocks, with a copy button
- a prompt block, which is a fence whose language is
prompt, also with a copy button - images written as

Images must already be uploaded. The alt text is required. Other image URLs are rejected. Raw HTML in Markdown is dropped, not rendered.
Image upload
multipart/form-data with file and alt. JPEG, PNG, WebP and GIF, up to 8 MB. GIF animation is not kept. The stored files are WebP. A typical response:
{
"id": "2f1c0b4a-6a1e-4f0a-9c2d-0a9d1e5b7c31",
"url": "/media/2f1c0b4a-6a1e-4f0a-9c2d-0a9d1e5b7c31.webp",
"alt": "Meeting notes sorted into decisions, tasks and open questions",
"width": 1600,
"height": 1000,
"srcset": "/media/2f1c0b4a-6a1e-4f0a-9c2d-0a9d1e5b7c31-w480.webp 480w, /media/2f1c0b4a-6a1e-4f0a-9c2d-0a9d1e5b7c31.webp 1600w",
"contentType": "image/webp"
}Rate limits and lockout
The client address is X-Real-IP when that header is set. Railway sets it. If it is missing, the address is the first entry in X-Forwarded-For. If both are missing, the request shares one bucket named unknown.
These requests require the token and are counted toward the rate limit: creating, updating and deleting topics and articles, publishing and unpublishing, uploading an image, and both preview endpoints. A public read with no Authorization header is never counted and is never blocked.
An address may send 30 of those requests per minute. The 31st returns 429. The body is error.code rate_limited. The Retry-After header is the number of seconds until the oldest counted request leaves the one-minute window.
A missing or wrong token is a failed attempt. A wrong or empty bearer token on GET /api/articles and GET /api/articles/{lang}/{slug} counts too, even though the response stays the public one (published content, or 404 for a draft). Ten failed attempts in ten minutes lock that address for 15 minutes. The attempt that reaches ten still returns its normal status. After that, every request that sends a token returns 429 with error.code blocked and Retry-After set to the remaining lock, which is 900 seconds when the lock has just started. The correct token does not get through during the lock. A public read with no token still returns 200.
Failed attempts are written to the server log with the address, HTTP method, path and reason (missing_token or wrong_token). The token itself is not logged.
The counters are in memory in the server process. A restart clears them. When a response is 429, wait the number of seconds in Retry-After, then send the same request again.
Errors
Errors are JSON. fields is an object of field name to a short reason. It is {} when the error is not about one field.
{
"error": {
"code": "validation_error",
"message": "The article could not be saved.",
"fields": {
"title": "Title is required.",
"topic": "No topic exists with slug \"missing\" for language \"en\". Create the topic first."
}
}
}{
"error": {
"code": "conflict",
"message": "An article with this slug already exists for this language. Use PUT to update it.",
"fields": { "slug": "Already exists." }
}
}| Status | code | When |
|---|---|---|
| 400 | validation_error | A field is missing or not usable |
| 400 | invalid_json | The body is not JSON |
| 401 | unauthorized | The token is missing or wrong |
| 404 | not_found | Missing, or a draft seen without the token |
| 429 | rate_limited | More than 30 token requests from this address in one minute |
| 429 | blocked | This address is locked for 15 minutes after 10 failed tokens in 10 minutes |
| 409 | conflict | POST would duplicate a slug, or a topic still has articles |
| 413 | payload_too_large | The JSON or the image is too large |
| 415 | unsupported_media_type | JSON was required, or the upload was not multipart |
| 503 | not_configured | PUBLISH_API_TOKEN or MEDIA_DIR is unset |
| 503 | unhealthy | /api/health cannot use the database or the media folder |
Python
publish_article.py uploads an image, creates a draft, previews it, and then publishes by updating the same slug. Run it with PUBLISH_API_TOKEN set:
python3 docs/examples/publish_article.pyThe machine-readable spec is OpenAPI 3. A short agent description is llms.txt.