The API

This page is for developers. If you're running a site rather than building software against one, you can safely skip it — nothing here is needed for ordinary use.

Looking for the exhaustive endpoint list? See the complete API reference. This page covers the concepts.

What the API is for

Every Basehim site exposes a REST API over its content, so other software can read and write it. That makes a few things possible:

• Publishing from a script, another system, or a mobile app.
• Pulling your content into a separate front end.
• Syncing posts between sites.
• Letting an AI agent manage content on your behalf.

Where it lives

REST endpoints sit under /api/v1/ on your own domain. Responses are JSON.

GET    /api/v1/posts            list posts
GET    /api/v1/posts/{slug}     a single post
POST   /api/v1/posts            create a post
PATCH  /api/v1/posts/{id}       update a post
GET    /api/v1/media            list uploaded files

Note the asymmetry, because it catches people out: you read a single item by its slug, but update and delete it by its numeric id.

Successful responses are wrapped in a data envelope — {"data": …} — and errors follow RFC 7807 problem details, with type, title, status and detail fields.

The OAuth and MCP endpoints are not under /api/v1; they sit at the root of your domain.

Authentication

Reading published content needs no authentication. Anything that writes — or reads drafts — requires credentials, and there are three kinds for three kinds of caller:

• API keys, generated in the admin and sent as Authorization: Bearer basehim_…. Best for scripts and server-to-server work.
• JWTs, obtained from POST /api/v1/auth/login and renewed at /auth/refresh. Best for something acting on behalf of a signed-in person.
• OAuth 2.1, used by AI agents connecting over MCP.

Tokens carry scopes, so a token issued for reading posts cannot modify settings. Issue the narrowest scope that does the job, and a separate token per integration so one can be revoked without disturbing the others.

MCP

Basehim also speaks MCP, the Model Context Protocol, which lets an AI agent work with your site directly through the same permission model rather than by scraping pages. Connect at /mcp.

It uses OAuth with dynamic client registration, which in practice means you paste the URL into your assistant and approve a consent screen — there is no client id or secret to configure. You'll be shown exactly which scopes are being requested.

The same advice applies as for apps: read what's being requested. An assistant that only needs to draft posts shouldn't be asking to change your settings. Installed apps can expose their own MCP tools and contribute their own scopes, so the list your site advertises may be longer than the built-in one.

Discovering what your site supports

Rather than trusting any document, including this one, ask the site:

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource

These return the endpoints, grant types and the full scope list your install actually advertises. That is the authoritative answer.

Rate limits and errors

Errors return standard HTTP status codes with a JSON body explaining what went wrong. 401 means the token is missing or expired; 403 means it's valid but lacks the scope for what you asked.

A note on tokens

A token is a password. Keep it out of client-side code, out of public repositories, and out of screenshots. If one leaks, revoke it in the admin area — it stops working immediately.