TrakysBlog publishing API
Trakys can write and manage your site's blog — drafts, publishing, updates, deletion — while your site keeps the content. There is no Trakys API for you to consume: your site exposes a small write API described below, you paste its address and a token into Trakys, and Trakys calls you. If Trakys is ever down, your blog isn't.
How it fits together
In your Trakys project, under Sites, you enter your site's API base URL (for example https://site.com/api/trakys) and a bearer token your site will accept. Trakys stores the token encrypted, never shows it again, and authenticates every request with Authorization: Bearer <token>. Platforms with an existing content API (Shopify, WordPress) can be fronted by a thin adapter implementing this contract; a custom site implements it directly — it's five endpoints, and only two are mandatory.
trakys.com itself implements this exact contract at /api/trakys — the reference implementation is this very site's blog.
Discovery — GET /
Required. One request that announces the contract version, declares what your site can do, and proves it's alive. Trakys calls it before every publish, and shows the author anything your site can't take — nothing is ever dropped silently.
{
"contract": "1.0",
"capabilities": {
"read": true,
"update": true,
"delete": true,
"categories": true,
"media": false,
"fields": ["title", "handle", "summary", "body", "tags",
"category", "status", "published_at", "cover"]
},
"limits": { "body_bytes": 500000, "media_bytes": 10485760 }
}read: false puts the site into publish-only mode: Trakys will state plainly that it can't know what's on the site and that editing and deleting from Trakys are unavailable. Fields absent from fields are not sent, and the author is told which of their fields were skipped.
Posts
| Method | Path | Required | Purpose |
|---|---|---|---|
| GET | /posts?limit=&cursor=&status= | if read | List, cursor pagination |
| GET | /posts/{id} | if read | One post in full |
| POST | /posts | yes | Create — the response must carry {id, url, handle} |
| PATCH | /posts/{id} | if update | Partial update |
| DELETE | /posts/{id} | if delete | Delete |
The post body Trakys sends (markdown body, all fields optional except title):
{
"title": "Post title",
"handle": "post-title",
"summary": "One sentence for previews and meta description",
"body": "# Markdown\n\nThe post text.",
"tags": ["release", "teams"],
"category": "news",
"cover": { "url": "https://...", "alt": "description" },
"status": "published",
"published_at": "2026-07-12"
}handle is a wish. If it's taken or invalid, assign your own and return the one that actually applied — Trakys stores your answer. All later updates and deletes address your id, so renames never break the link.
Categories — GET /categories
Required if capabilities.categories. A flat list of what really exists — Trakys shows it as a dropdown, so an author can never send a category your site would have to invent or drop:
{ "items": [ { "id": "news", "title": "News" },
{ "id": "eng", "title": "Engineering" } ] }Media — POST /media
Required if capabilities.media. multipart/form-data with a file field; respond with { "url": "https://site.com/...", "alt": null } and Trakys puts that URL into the post body. If your site doesn't take uploads, authors use absolute external image URLs — Trakys refuses to publish a post whose body references a Trakys-internal file to a site without media support, loudly, so your readers never see a broken image.
Version conflicts
GET /posts/{id} responses carry updated_at. PATCH accepts an If-Unmodified-Since header with that exact value; if the post changed on your site after Trakys last read it, answer 409 — Trakys asks the author instead of overwriting.
Errors
One envelope for every failure, with a machine-readable code:
{ "code": "handle_taken", "message": "…", "details": null }Minimal vocabulary: unauthorized, not_found, handle_taken, validation_failed, unsupported, rate_limited, server_error.
Idempotency
POST /posts receives an Idempotency-Key header. A retry with the same key must return the same post, not create a second one — otherwise a network timeout during publishing mints duplicates.