API reference

Written for

integration-developer

Roles

owner, admin, member, elevated-client-user, agent

Requires

An API token for operations marked token-enabled; A browser session for everything else

Feature

api

This reference documents every HTTP operation of the SAQ API, grouped by resource. Every page follows the same pattern per operation: purpose, who may call it and with which token scope, parameters, a request example, a response example, and the errors it can return. The API is unversioned; workspace operations live under /api/w/{slug}/…, where {slug} is the workspace slug shown in the app's address bar (acme in every example here).

How the reference is organised

Shared conventions (ids, dates, pagination, filtering, rate limits, body limits) are on Conventions; authentication for integrations is on Authentication.

Which operations accept API tokens

An API token (Authorization: Bearer saq_YOUR_TOKEN) is accepted only on the operations below. Every other /api/w/{slug}/… operation answers 403 forbidden with the message "This operation is not available to API keys", and tokens can never reach /api/me/*.

All paths in the table are relative to /api/w/{slug}. A GET needs read; any other method needs write. A token without the needed scope gets 403 forbidden with the message "This token does not include that scope" and details.scope. Behind the scope check, the same role rules apply as in the app: a token acts as the person or agent account it belongs to and never sees more than they would.

Every operation page states "Token: yes" or "Token: no (browser session only)". Session-only operations are called by the app with a cookie session; integrators cannot call them.

The live OpenAPI document

GET /api/openapi.json returns the OpenAPI 3.1 document for the whole API, titled "SAQ API". It is public and needs no authentication, so you can fetch it in a build step and generate a client from it. It covers every operation, including the ones that stream a file, the MCP endpoint, and SCIM. The response is cacheable for five minutes. There is no hosted Swagger UI; load the document into the tool of your choice.

curl -s https://saq.no/api/openapi.json -o saq-openapi.json

Each operation declares what it accepts, so a generated client and an API explorer configure authentication on their own:

An operation that lists bearerAuth is one of the operations in the table above; the list in the document is generated from the same rule the server enforces, so the two cannot disagree. An operation with an empty requirement needs no credential at all.

The document describes operations, not your permissions: an operation listing bearerAuth does not mean your token may call it, because roles, scopes, and project restrictions still apply. This page and the pages under it state, per operation, who may call it. A check in SAQ's own build fails when the document and these pages disagree, so a route cannot be added, renamed, or removed without the documentation following it.

Error responses

Every error is JSON with a stable error code, usually a message, and sometimes details:

{
  "error": "invalid",
  "message": "Validation failed",
  "details": { "issues": [] }
}

details.reason is a stable snake_case slug (for example range_limit, closed_period_log, reset_requires_admin) and is listed per operation in this reference. details.field names the offending body field where one exists.

Schema names

Response and request shapes are named after the schemas in the OpenAPI document, for example TicketSummary, TicketPage, CreateTicket, TimeEntry, Document, Workflow, ApiToken. Each operation page lists the fields of the schemas it uses, so a page can be read on its own.