API conventions

These rules apply to every endpoint of the Sluby REST API. Each endpoint's own fields and responses are in the REST API reference.

Base URLCopy Anchor Link

The REST API lives under /api/v1 on your server's public URL. With the Docker Compose stack from Install Sluby, that is http://localhost:8080/api/v1. In production it is https://sluby.example.com/api/v1 for a server at sluby.example.com.

The API and playback paths are grouped by prefix. The server also answers /health and /metrics, described in Monitor and maintain.

A path under /api/v1 that no route serves answers 404 with {"error": "Route GET /api/v1/... not found"}, whether or not you send a key.

AuthenticationCopy Anchor Link

Every /api/v1 route needs credentials, except these:

• the sign-in routes under /api/v1/auth (some of them need the Studio session cookie, none of them accept an API key)
• GET /api/v1/openapi.json, GET /api/v1/docs and the script files that page loads from /api/v1/docs/scalar/
• tus OPTIONS requests to /api/v1/uploads

The server accepts two kinds of credentials: an API key in the Authorization header, and the Studio session cookie. When a request carries a live session cookie and a key, the session cookie wins.

API keysCopy Anchor Link

Send the key as a bearer token:

Authorization: Bearer sluby_...

The header must start with Bearer exactly. Create, rotate and revoke keys with the keys endpoints or in the Studio (Create and manage API keys). For what roles allow, see Accounts, roles and sessions.

ScopesCopy Anchor Link

A scope check is exact: manage does not include read, and read does not include upload. Give a key every scope it needs. A request without the scope answers 403 with {"error": "Requires 'read' scope"} (naming the missing scope). A tus upload request without upload answers 403 with the plain-text body API key does not have upload scope.

A Studio session holds all three scopes.

Admin-only endpointsCopy Anchor Link

Some endpoints also need the caller to act as an admin. Otherwise they answer 403 with {"error": "Only an admin may use this endpoint"}:

• GET /api/v1/metrics (needs read)
• POST /api/v1/reconciliation/run (needs manage)
• the members and invites endpoints (need manage)

Two endpoints answer everyone with the scope but return less to a member: GET /api/v1/system/status returns the health summary only, and GET /api/v1/reconciliation returns the account-level report instead of the deployment-wide one.

The OpenAPI document marks each operation with x-required-scope and, for admin-only operations, x-required-identity: admin.

Studio session cookieCopy Anchor Link

Signing in through the /api/v1/auth routes sets a session cookie. A browser on the same site sends it with every request, so the Studio needs no key.

The server checks on every request that the session is still live and the account is not removed. GET /api/v1/auth/sessions, DELETE /api/v1/auth/sessions/{id}, DELETE /api/v1/auth/sessions, GET /api/v1/auth/me and POST /api/v1/auth/password/change work with the session cookie only. For how sessions start and end, see Accounts, roles and sessions.

When AUTH_DISABLED is on, every request acts as the local development account, which is an admin with all three scopes, whatever credentials it carries (AUTH_DISABLED).

Cross-origin writesCopy Anchor Link

The server refuses a write that only ambient credentials (a cookie) could authorize. A request under /api answers 403 with {"error": "Cross-origin request refused"} when all of these hold:

• the method is not GET, HEAD or OPTIONS
• it has an Origin header
• it has no Authorization header
• the origin is not the origin of PUBLIC_URL, not the origin the request was addressed to, and not listed in CORS_ORIGIN

A request with an Authorization header, such as an API key, always passes this check.

ErrorsCopy Anchor Link

Error bodyCopy Anchor Link

Every REST error is JSON with an error string:

{
  "error": "title must be at most 200 characters",
  "details": [{ "field": "title", "message": "title must be at most 200 characters" }]
}

The tus upload protocol requests answer errors with a plain-text body, as the tus protocol does. These are the HEAD, PATCH and OPTIONS requests to /api/v1/uploads, and any request there with a Tus-Resumable header.

Status codesCopy Anchor Link

Each endpoint page in the REST API reference lists the codes that endpoint returns. @sluby/sdk turns these into error classes.

Authentication failuresCopy Anchor Link

The reason on a session 401 appears only when the request carries no Authorization: Bearer header. The sign-in routes and the member routes use more reason values (bad_credentials, disabled, bad_code, already_set_up, email_taken, no_password, used, last_admin, self); their endpoint pages list them.

PaginationCopy Anchor Link

Two list endpoints page with a cursor:

To page forward, pass the next_cursor of one response as cursor in the next request, with the same filters. has_more is false and next_cursor is null on the last page. Rows inserted or deleted between requests do not shift a cursor, because the cursor encodes the position of the last row returned (its creation time and id), not an offset.

Rules for GET /api/v1/assets:

• Send either cursor or page, not both. A request with both answers 400 with Use either cursor or page, not both.
• A cursor works only with the default order (sort=created_at, order=desc). With another order, use page: a cursor answers 400 with cursor paging only supports the default order; use page instead.
• With a cursor, page in the response is null.

A cursor the server cannot decode answers 400 with cursor is not valid; start again without it. Treat a cursor as opaque.

GET /api/v1/webhooks/{id}/deliveries takes only a limit (1 to 100, default 50) and returns the newest deliveries.

Rate limitsCopy Anchor Link

The backend keeps its counters in memory with fixed windows. A restart of the backend resets every window.

Every request through the per-key, per-session or per-IP limiter carries these headers:

Over the limit, the answer is 429 with a Retry-After header in seconds and this body:

{
  "error": "Too many requests. Try again in a few seconds.",
  "retry_after": 42,
  "retryAfter": 42
}

retryAfter is an older spelling of retry_after. The attempt limits answer 429 with Retry-After and a body of error (for example Too many attempts. Try again in 10 minutes.) and retry_after. The X-RateLimit-* headers on those answers describe the per-IP limit.

The per-IP limiter counts every /api/v1 request first and gives the count back once the request authenticates. So an address that has used up its per-IP window gets 429 for every /api/v1 request until the window resets, keyed requests included.

tus upload requests do not count against the per-key or per-session limit. The per-IP limit counts them unless the upload server answers 401 or 403.

The per-IP limits use the client address Express resolves through the proxies it trusts (TRUST_PROXY). The server operator changes the key cap and the per-IP limit with the variables linked in the table. A key cannot be created with a rate_limit above API_KEY_RATE_LIMIT_MAX (the API answers 400).

Proxy limitsCopy Anchor Link

The nginx proxy in the shipped Docker Compose stacks adds per-client-address limits in front of the backend:

Over these limits nginx answers 429 with Retry-After: 1 and {"error":"Too many requests. Try again in a few seconds."}. The server operator changes them with the variables in the table (Web proxy configuration).

ETags and If-MatchCopy Anchor Link

Assets carry a version so two editors cannot overwrite each other's changes.

The version is the asset's updated_at in milliseconds since the Unix epoch, in double quotes, for example "1767225600000". You can build it from any asset you already hold, including one from the list endpoint. Plays do not change it.

If-Match rules on PATCH:

• Without If-Match, or with If-Match: *, the update applies unconditionally.
• A comma-separated list matches when any entry matches. A weak tag (W/"1767225600000") counts as its strong form.
• A value that is not a quoted version answers 400 with If-Match must be the ETag of the video, such as "1767225600000".
• When the asset changed since that version, the answer is 412 with the current ETag header and this body:

{
  "error": "This video was changed somewhere else.",
  "current": { "id": "...", "title": "...", "updated_at": "..." }
}

current holds the full asset in the same shape as GET /api/v1/assets/{id}. Retry with its version once you have merged your change.

CORSCopy Anchor Link

The REST API (/api) decides CORS per request origin:

When CORS_ORIGIN lists any origin, or AUTH_DISABLED is on, responses carry Vary: Origin. See CORS_ORIGIN to set the list.

The delivery gateway (/v1/objects/, /v1/stream/, /v1/share/) answers any origin with Access-Control-Allow-Origin: *, never with credentials. It allows the request headers Range and Content-Type. /v1/objects/ and /v1/stream/ allow GET, HEAD and OPTIONS and expose Content-Length, Content-Range, Accept-Ranges and ETag. Behind the nginx proxy of the shipped stacks, /v1/share/ allows GET and OPTIONS and exposes the same headers without ETag.

Request size limitsCopy Anchor Link

A tus OPTIONS request to /api/v1/uploads returns the upload limit in the Tus-Max-Size header. The nginx proxy in the shipped stacks sets no body size limit of its own.

OpenAPI document and interactive referenceCopy Anchor Link

The server describes its API in an OpenAPI 3.1 document:

Both count against the per-IP limit. The interactive page uses bearerAuth by default, so you can paste a key and send requests from it.

The REST API reference on this site is generated from the same document, published here as /openapi.json.