{"openapi":"3.0.3","info":{"title":"Practical AI publishing API","version":"1.0.0","description":"Token-protected HTTP API for topics, articles and images. Readers use the website. Agents publish through this API. Article bodies are Markdown. The API never accepts HTML or frontend components. Drafts are not readable without the token. Token requests are limited to 30 per minute per client address (X-Real-IP, else the first X-Forwarded-For entry, else unknown). The 31st returns 429 rate_limited with Retry-After. Ten failed tokens in ten minutes lock that address for 15 minutes; further token requests return 429 blocked with Retry-After, even with the correct token. Public reads with no Authorization header are not counted."},"servers":[{"url":"/"}],"tags":[{"name":"Health"},{"name":"Topics"},{"name":"Articles"},{"name":"Media"},{"name":"Preview"}],"components":{"parameters":{"lang":{"name":"lang","in":"path","required":true,"schema":{"type":"string","enum":["en","da"]}},"slug":{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"PUBLISH_API_TOKEN from the server environment. The token is never sent to the website frontend."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fields"],"properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}},"Translation":{"type":"object","required":["lang","slug"],"properties":{"lang":{"type":"string","enum":["en","da"]},"slug":{"type":"string"}}},"Topic":{"type":"object","required":["slug","lang","title","description","sortOrder","createdAt","updatedAt","href"],"properties":{"slug":{"type":"string"},"lang":{"type":"string","enum":["en","da"]},"title":{"type":"string"},"description":{"type":"string"},"illustration":{"type":"string","nullable":true,"enum":["everyday","work","agents","notes","message","checklist","calendar",null]},"sortOrder":{"type":"integer"},"translationOf":{"oneOf":[{"$ref":"#/components/schemas/Translation"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"href":{"type":"string"}}},"CoverImage":{"type":"object","required":["url","alt"],"properties":{"url":{"type":"string","example":"/media/2f1c0b4a-6a1e-4f0a-9c2d-0a9d1e5b7c31.webp"},"alt":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"srcset":{"type":"string"}}},"Source":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Article":{"type":"object","required":["slug","lang","title","description","topic","tags","status","createdAt","updatedAt","href"],"properties":{"slug":{"type":"string"},"lang":{"type":"string","enum":["en","da"]},"title":{"type":"string"},"description":{"type":"string"},"topic":{"type":"string","description":"Slug of a topic in the same language. category is accepted as an alias on write."},"bodyMarkdown":{"type":"string","description":"Present on a single article. Omitted from list results."},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","published"]},"coverImage":{"oneOf":[{"$ref":"#/components/schemas/CoverImage"},{"type":"null"}]},"videoUrl":{"type":"string","nullable":true},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"featured":{"type":"boolean"},"sample":{"type":"boolean"},"translationOf":{"oneOf":[{"$ref":"#/components/schemas/Translation"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":"string","format":"date-time","nullable":true},"href":{"type":"string"}}}}},"paths":{"/api/health":{"get":{"tags":["Health"],"summary":"Check the database and the media directory","responses":{"200":{"description":"Database and storage are usable."},"503":{"description":"Database or storage is not usable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/topics":{"get":{"tags":["Topics"],"summary":"List topics","parameters":[{"name":"lang","in":"query","schema":{"type":"string","enum":["en","da"]}}],"responses":{"200":{"description":"Topics, ordered by sortOrder then title."}}},"post":{"tags":["Topics"],"summary":"Create a topic","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Created."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This slug and language already exist. Use PUT."},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/topics/{lang}/{slug}":{"get":{"tags":["Topics"],"summary":"Get a topic","parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"The topic."},"404":{"description":"Not found."}}},"put":{"tags":["Topics"],"summary":"Update a topic, or create it if it does not exist","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Updated."},"201":{"description":"Created."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Topics"],"summary":"Delete a topic that has no articles","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Deleted."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The topic still has articles."},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/articles":{"get":{"tags":["Articles"],"summary":"List articles","description":"Without a token, only published articles are returned. status=draft and status=all require the token and otherwise return 404. A wrong token counts as a failed attempt and still returns the public list. A locked address that sends a token receives 429 blocked.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"lang","in":"query","schema":{"type":"string","enum":["en","da"]}},{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["published","draft","all"],"default":"published"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of article summaries. bodyMarkdown is omitted."},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Articles"],"summary":"Create an article","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Created."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This slug and language already exist. Use PUT."},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/articles/{lang}/{slug}":{"get":{"tags":["Articles"],"summary":"Get an article","description":"A draft returns 404 unless the request has the publishing token. A wrong token counts as a failed attempt and still returns the public article or 404. A locked address that sends a token receives 429 blocked.","security":[{},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"The article, including bodyMarkdown."},"404":{"description":"Missing, or a draft requested without the token."},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Articles"],"summary":"Update an article, or create it if it does not exist","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Updated."},"201":{"description":"Created."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Articles"],"summary":"Delete an article","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Deleted."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/articles/{lang}/{slug}/publish":{"post":{"tags":["Articles"],"summary":"Publish an article","description":"Sets publishedAt the first time. Repeating the call keeps the original publishedAt.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Published."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/articles/{lang}/{slug}/unpublish":{"post":{"tags":["Articles"],"summary":"Unpublish an article","description":"Status becomes draft. publishedAt is kept. Public pages and the public API return 404.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Unpublished."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/articles/{lang}/{slug}/preview":{"get":{"tags":["Preview"],"summary":"Preview a saved article","description":"Returns rendered HTML and a signed preview URL that expires in 15 minutes. The URL does not contain the API token.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"HTML and a short-lived preview URL."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/preview":{"post":{"tags":["Preview"],"summary":"Preview saved or unsaved Markdown","description":"Send lang and slug to preview a saved article. Send lang and bodyMarkdown to render text that is not saved yet. An unsaved preview has html and no previewUrl.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Rendered HTML, and a preview URL when the article is saved."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/media":{"post":{"tags":["Media"],"summary":"Upload an image","description":"Multipart fields file and alt. The image is stored as WebP at several widths. Use the returned url as coverImage.url or inside Markdown.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","alt"],"properties":{"file":{"type":"string","format":"binary"},"alt":{"type":"string"}}}}}},"responses":{"201":{"description":"Stored image."},"400":{"description":"Missing alt text or unreadable file."},"401":{"description":"The bearer token is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited after 30 token requests in one minute, or blocked for 15 minutes after 10 failed tokens in 10 minutes. Retry-After is seconds to wait. A blocked address is rejected even with the correct token.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}