API for Developers

InterlinedList exposes an HTTP API that lets you build integrations, native clients, scripts, and automations on top of the platform. All request and response bodies are JSON unless noted otherwise.

This page is an index. Pick the section you need from the sidebar (or the list below) for full request/response details.

Interactive explorer: Try endpoints live in the browser with the Swagger / OpenAPI explorer at /api-docs. Authorize with a sync token and send real requests. The raw machine-readable spec is served at /api/openapi.json.

Base URL

Paths are relative to the InterlinedList deployment you are targeting:

https://interlinedlist.com

For example: https://interlinedlist.com/api/messages

Authentication at a glance

Two methods are supported. See Authentication & OAuth for details.

• Session cookie: set by POST /api/auth/login; used by the web app and any browser client on the same origin.
• Bearer token: obtained from POST /api/auth/sync-token; used by native, mobile, and CLI clients. Send as Authorization: Bearer <token>.

Endpoints documented as Session or Bearer accept either. Endpoints documented as Session only require the cookie.

Response conventions

Success envelopes — there are three

Which one an endpoint uses is documented per operation in the OpenAPI spec and shown in the explorer. You cannot guess it from the URL:

Every date is an ISO-8601 UTC string, so a single global date strategy decodes the whole API. A column that is optional in the database is nullable on the wire and is typed ["string", "null"] (or similar) in the spec — a strict decoder such as Swift Codable or kotlinx will not trip on it.

Errors

Errors always return JSON with an error field:

{ "error": "Not authenticated" }

Common status codes: 400 bad request, 401 not authenticated, 403 forbidden (e.g. email not verified, subscriber feature), 404 not found, 409 conflict, 413 payload too large, 429 rate limited, 500 server error.

Many error responses also include a machine-readable code alongside the human-readable error string, so clients can switch on the reason without parsing prose:

{ "error": "Your account is restricted and is currently read-only.", "code": "account_restricted" }

Account-status error codes

Accounts have a status lifecycle (probation, active, restricted, suspended, banned) that can limit or block write actions. When it does, the response carries one of these codes. These codes are only returned when the server has account-status enforcement enabled; on a server where it is off, none of them appear.

Read (GET) endpoints are never blocked by account status.

Paginated lists include a pagination object alongside the data array:

{
  "data": [ ... ],
  "pagination": {
    "total": 84,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Use limit and offset (or page) as query parameters to page through results.

Subscriber-only features

Some features require an active paid subscription. Check GET /api/user for the customerStatus field:

Any non-"free" status grants subscriber access. Features gated behind a subscription include image and video attachments on messages, scheduled posts, cross-posting to Mastodon/Bluesky/LinkedIn/X (Twitter), and document creation. Sending a subscriber-only field as a free user returns 403 Forbidden:

{ "error": "This feature requires an active subscription." }

Quick start

POST /api/auth/sync-token
Content-Type: application/json

{ "email": "you@example.com", "password": "yourpassword" }

Then:

GET /api/user
Authorization: Bearer 3f1c9e...<64 hex chars>...a8

POST /api/messages
Authorization: Bearer 3f1c9e...<64 hex chars>...a8
Content-Type: application/json

{ "content": "Hello from the API!", "publiclyVisible": true }

See Messages for the full message body reference.

Reference by category

Canonical reference and the interactive explorer

These per-category pages are the canonical human reference for the InterlinedList HTTP API. For the machine-readable contract and a live "try it" console, use:

• Interactive API explorer: Swagger UI rendered from the OpenAPI 3.1 spec, with authorization and live requests.
• OpenAPI spec: the raw OpenAPI 3.1 document. Every operation carries a response schema, and the client-critical endpoints carry a worked example taken from the handler that produces it — so a generated client (npx openapi-typescript) types responses rather than falling back to any.