API Basics

Tokens, base URL, request conventions, errors, and permissions.

API Basics covers what every call needs: a token, the right header, the shape of requests and responses, what an error looks like, and which role the call requires.

Permissions

Reading requires membership of the site. Writing requires the editor role. A few operations require admin.

Conventions

Requests and responses are JSON, with two exceptions: media uploads are multipart/form-data, and the public contact endpoint is form-encoded. The API never picks a format from your Accept header. When an endpoint can return something other than JSON, you ask with a query parameter such as ?dl=yaml.

Errors

Every error uses the same shape -- RFC 9457 Problem Details -- and the content type application/problem+json.

First Request

Two calls are enough to confirm your token works before you write anything larger.

Tokens

Every API call must be authenticated. An anonymous request returns 401.