The scsiwyg API: a developer's walkthrough

The full API reference has all the details. This post is the story version — how the API fits together, what the design decisions are, and how to build on top of it.

Authentication

Write operations use Bearer token auth:

Authorization: Bearer your-token-here

Read operations are public. No auth needed to read published posts or site info. This means you can build a static site generator that pulls from scsiwyg, a feed reader that aggregates scsiwyg blogs, or a search engine that indexes scsiwyg content — all without authentication.

The post lifecycle

Create

bash

POST /api/username/posts

Required fields: slug, title, body. Optional: tags, images, visibility, date, draft.

A post is published immediately unless you include "draft": true. Published means publishedAt is set. Unpublished means it's null.

Read

GET /api/username/posts/slug

Returns the full post object. Public endpoint. Only published posts are visible to unauthenticated readers. Drafts return 404 unless you're the owner with a valid Bearer token.

Update

bash

PUT /api/username/posts/slug

Send only the fields you want to change. The slug is immutable (it's the URL). Everything else can be updated.

Want to unpublish? Send "published": false. Want to re-publish? Send "published": true.

Delete

bash

DELETE /api/username/posts/slug

Gone. No soft delete. No trash folder. No "are you sure?" The API trusts you.

The images field

Images are embedded as a JSON array of objects:

json

{
  "images": [
    {
      "id": "hero",
      "name": "hero.jpg",
      "data": "data:image/jpeg;base64,/9j/4AAQ..."
    }
  ]
}

Reference them in your markdown body with the data URI or by convention. The image data travels with the post — no external hosting required.

Error responses

Every error returns a JSON object with an error field:

json

{ "error": "Slug already exists on this site" }

Status codes are standard HTTP:

400 — bad request (missing fields, invalid values)
401 — no token or invalid token
403 — valid token but you don't own this site
404 — site or post not found
409 — slug conflict

Building on top of it

The API is simple enough that you can build a publishing pipeline in a few hours:

Git-based workflow: Write posts as JSON files in a repo. CI publishes on push to main.
AI agent: An LLM reads your notes/docs and generates blog posts, publishing via the API.
Cross-poster: A script that reads from one scsiwyg blog and republishes (with attribution) to another.
Static site generator: Pull all posts via GET, render with your own templates.

The API is deliberately minimal. It does CRUD on posts and sites. Everything else — the workflow, the automation, the tooling — is yours to build.