# Use Sluby with AI agents (/developers/ai-agents)

The Sluby agent skill teaches a coding agent (Claude Code, Claude, Codex, Gemini CLI, GitHub Copilot and others that read Agent Skills) how to build on a Sluby server: which calls to make, which scopes they need, and the mistakes to avoid. This site also serves every page as plain markdown for agents that read docs directly.

## What the skill covers [#what-the-skill-covers]

The skill is a `SKILL.md` file plus four reference files in the [Agent Skills](https://agentskills.io/specification) format. An agent loads `SKILL.md` when a task involves Sluby, and opens a reference file only when the task needs it.

| File                     | What it teaches                                                                                                                                                                                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SKILL.md`               | Authenticating with an API key, the upload and wait-for-ready flow with `@sluby/sdk`, managing assets, playing videos, webhooks, the SDK's error classes, and the rules that prevent common mistakes: keys stay on the server, the smallest scopes, rate limits, signed URLs for private videos |
| `references/rest-api.md` | The REST API: authentication, what each scope allows, the main endpoints, errors, listing and cursor paging, ETags with `If-Match`, rate limit headers, and where each server publishes its OpenAPI document                                                                                    |
| `references/uploads.md`  | Upload rules and limits, the SDK upload handle (progress, pause, resume, abort), uploading with any tus client or with `curl`, following processing and retrying                                                                                                                                |
| `references/playback.md` | Playback URLs, `@sluby/player` in React for public and private videos, signed URLs and their renewal, the watch page in an iframe, playback ids, revoking access, streaming straight from Sia                                                                                                   |
| `references/webhooks.md` | Webhook events, registering an endpoint, verifying `X-Sluby-Signature-V1` with and without the SDK, retries and duplicate events                                                                                                                                                                |

## Download the skill [#download-the-skill]

- [sluby.zip](/skills/sluby.zip): the whole skill, with a `sluby` folder at the top.
- [SKILL.md](/skills/sluby/SKILL.md): the main file alone.
- [Source on GitHub](https://github.com/justmert/Sluby/tree/main/docs/public/skills/sluby).

## Install the skill [#install-the-skill]

Pick your agent. Each method installs the full skill, reference files included.

<Tabs items={['Claude Code', 'Claude', 'Codex', 'Gemini CLI', 'GitHub Copilot', 'Other agents']}>
<Tab value="Claude Code">

Download [sluby.zip](/skills/sluby.zip), then unzip it into your personal skills folder to use it in every project:

```sh
mkdir -p ~/.claude/skills && unzip sluby.zip -d ~/.claude/skills
```

Or into one project (commit the folder so everyone who works in that repository gets it):

```sh
mkdir -p .claude/skills && unzip sluby.zip -d .claude/skills
```

Claude Code picks up the new skill in the current session, without a restart. If the `skills` folder did not exist when the session started, run `/reload-skills`.

</Tab>
<Tab value="Claude">

1. On Free, Pro and Max plans, turn on **Code execution and file creation** under **Settings**, **Capabilities**. On Team and Enterprise plans, an organization owner turns on **Cloud code execution and file creation** and **Skills** under **Organization settings**, **Plugins & skills**, in the **Policy** tab.
2. Download [sluby.zip](/skills/sluby.zip).
3. In Claude, open **Customize**, then **Skills**.
4. Click **+**, then **+ Create skill**, then **Upload a skill**.
5. Upload `sluby.zip`.

</Tab>
<Tab value="Codex">

Download [sluby.zip](/skills/sluby.zip), then unzip it into your personal skills folder:

```sh
mkdir -p ~/.agents/skills && unzip sluby.zip -d ~/.agents/skills
```

Or into a repository, so Codex uses it there:

```sh
mkdir -p .agents/skills && unzip sluby.zip -d .agents/skills
```

</Tab>
<Tab value="Gemini CLI">

```sh
gemini skills install https://github.com/justmert/Sluby.git --path docs/public/skills/sluby
```

This installs for your user. Add `--scope workspace` to install into the current project instead.

</Tab>
<Tab value="GitHub Copilot">

With GitHub CLI's `skill` command:

```sh
gh skill install justmert/Sluby sluby --scope user
```

Leave out `--scope user` to install into the current project. Without `--agent`, the command asks which agent to install for when you run it in an interactive terminal, and installs for GitHub Copilot otherwise. Pass `--agent` to pick another one ([`gh skill install`](https://cli.github.com/manual/gh_skill_install) lists the agent names).

</Tab>
<Tab value="Other agents">

The [`skills`](https://github.com/vercel-labs/skills) command line tool installs into many agents, including Cursor, OpenCode, goose and Windsurf. It needs Node.js 22.20 or later.

```sh
npx skills add https://github.com/justmert/Sluby/tree/main/docs/public/skills/sluby
```

Pass `-a <agent>` to choose the agents (for example `-a cursor`), and `-g` to install for your user instead of the current project.

</Tab>
</Tabs>

## Give the agent your server's address [#give-the-agent-your-servers-address]

The skill does not know where your Sluby server runs. Tell the agent its address, for example `https://sluby.example.com`, and keep the API key in an environment variable such as `SLUBY_API_KEY` rather than in the chat. To create a key, see [Create and manage API keys](/studio/api-keys).

Each Sluby server publishes its own OpenAPI document, and the skill tells the agent to read it for anything the skill does not show. Where it lives is on [API conventions](/developers/reference/api-conventions#openapi).

## Docs for agents [#docs-for-agents]

This site serves its pages in forms that agents and other tools read without a browser:

| Path                               | Contents                                                                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)           | An index of every page, with links and one-line descriptions                                                                  |
| [`/llms-full.txt`](/llms-full.txt) | Every page in one plain text file                                                                                             |
| `/llms.mdx/<page path>/content.md` | One page as markdown. For this page: [`/llms.mdx/developers/ai-agents/content.md`](/llms.mdx/developers/ai-agents/content.md) |
| [`/openapi.json`](/openapi.json)   | The OpenAPI document behind the [REST API reference](/developers/reference/api/assets/get-assets)                             |

To give an agent one page, take the page's path and wrap it: `/developers/guides/webhooks` becomes `/llms.mdx/developers/guides/webhooks/content.md`.


# Accounts, roles and sessions (/developers/concepts/accounts-and-roles)

This page explains who can do what on a Sluby server: how one install maps to one team, what the admin and member roles allow, how the backend decides who made a request, and how sign-in, Studio sessions, the setup code, invite links and reset links work. For the Studio screens that manage members, see [Invite and manage members](/studio/members). For how an operator sets up sign-in, see [Set up sign-in](/self-hosting/sign-in).

## One install is one team [#one-install-is-one-team]

A Sluby install serves one team, called the workspace. Every video, API key, webhook endpoint and upload belongs to the workspace, and every caller (a member's Studio session, an API key, or the local development account) acts as the workspace. Each person who can sign in is a row in the `users` table with a role. The role decides what a person can do, not which videos they see: every member sees the whole library.

## Roles and what each can do [#roles]

There are two roles, `admin` and `member`.

| Capability                                                               | Admin                                                                                                                    | Member                                                                                                                            |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Upload, list, edit, retry and delete videos                              | Yes                                                                                                                      | Yes                                                                                                                               |
| Create and revoke playback ids, mint signed URLs and share URLs          | Yes                                                                                                                      | Yes                                                                                                                               |
| Create, list, rotate and revoke the workspace's API keys                 | Yes                                                                                                                      | Yes                                                                                                                               |
| Create and manage webhook endpoints, read their delivery logs            | Yes                                                                                                                      | Yes                                                                                                                               |
| Read library stats and daily play counts                                 | Yes                                                                                                                      | Yes                                                                                                                               |
| Read system status (`GET /api/v1/system/status`)                         | Full status: database, Redis, the Sia indexer's account usage and hosts, the last reconciliation run, the delivery cache | Health summary only: overall status, version, database, Redis and indexer health, the indexer's network and its host pool summary |
| Read the reconciliation report (`GET /api/v1/reconciliation`)            | The whole deployment                                                                                                     | Missing objects of the workspace's videos only                                                                                    |
| Start a reconciliation run                                               | Yes                                                                                                                      | No                                                                                                                                |
| Read process metrics as JSON (`GET /api/v1/metrics`)                     | Yes                                                                                                                      | No                                                                                                                                |
| List members, change roles, remove and restore members, make reset links | Yes                                                                                                                      | No                                                                                                                                |
| Create, list and withdraw invites                                        | Yes                                                                                                                      | No                                                                                                                                |

An endpoint reserved for admins answers a member with `403` and `Only an admin may use this endpoint`. [API conventions](/developers/reference/api-conventions#scopes) lists the scopes an API key needs for each endpoint. [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation) describes the reconciliation report.

The backend reads the role on every request. A role change applies to the member's sessions and API keys on their next request.

## Who a request acts as [#callers]

Every request under `/api/v1` (except the `/api/v1/auth` routes, the OpenAPI document at `/api/v1/openapi.json` and the reference page at `/api/v1/docs`) and every tus upload request goes through the same check, in this order:

```mermaid
flowchart TD
  A[Request] --> B{AUTH_DISABLED on?}
  B -->|yes| C[Local development account, admin, all scopes]
  B -->|no| D{Live session cookie?}
  D -->|yes| E[That member, all scopes, admin if their role is admin]
  D -->|no| F{Authorization: Bearer key?}
  F -->|no| G[401 with a reason]
  F -->|yes| H{Key known, active and not expired?}
  H -->|no| I[401]
  H -->|yes| J{Key has a creator?}
  J -->|no| K[Admin, the key's scopes]
  J -->|yes| L{Creator removed?}
  L -->|yes| M[401: the key's creator was removed]
  L -->|no| N[Creator's current role, the key's scopes]
```

- **Studio session.** A valid session cookie wins over an API key. A session carries all three scopes (`upload`, `read` and `manage`), and acts as an admin when the member's role is `admin`.
- **API key.** A key carries the scopes it was created with. It acts with its creator's role as it stands at that request. Removing the creator stops the key with `401` and `This API key's creator was removed from this workspace`; restoring the creator makes the key work again. A key with no creator acts as an admin: these are keys made on the server itself, from [`BOOTSTRAP_API_KEY`](/self-hosting/configuration#bootstrap_api_key) or the [seed script](/self-hosting/sign-in#create-an-admin-api-key-from-the-command-line).
- **AUTH_DISABLED.** With `AUTH_DISABLED` on, every request acts as one local development account with the admin role and all scopes. A server with `NODE_ENV=production` refuses to start with it (see [Configuration](/self-hosting/configuration#auth_disabled)).

## Sign-in methods [#sign-in-methods]

A member can have more than one way to sign in. Each way is a row in `user_identities`, linked to the member's `users` row.

### Email and password [#email-and-password]

- The server trims and lowercases the email, and each email belongs to a single account.
- A new password must have 10 to 256 characters.
- The server stores passwords as scrypt hashes (N=32768, r=8, p=1, 16-byte random salt).
- A wrong email and a wrong password get the same answer, `401` with `Wrong email or password`. An unknown email costs the same hashing time as a known one, so response timing does not reveal which emails exist.
- A removed member's correct password gets `403` with `This account was removed from this workspace`.
- Changing the sign-in email (`POST /api/v1/auth/email/change`) also needs the current password, counts against the same attempt limits, and keeps the password. Another account's email gets `409` with `reason: email_taken`.
- A member changes their own name with `PATCH /api/v1/auth/me`.
- Changing the password (`POST /api/v1/auth/password/change`) needs the current password, and ends every other session of the account while keeping the current one. A member who signs in with GitHub only has no password yet and gets `409` with `This account has no password yet. Ask an admin for a reset link to set one.`

### GitHub [#github]

The server offers GitHub sign-in only when it has both `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` set. `GET /api/v1/auth/config` reports it in `methods.github`.

- Sluby asks GitHub for the `read:user` scope only.
- Sluby identifies a GitHub account by its numeric account id, not its login, so renaming a GitHub login does not change who it signs in as. Sluby stores the login for display and refreshes it at each sign-in. The member's name stays the one they chose.
- A member removes GitHub from their account with `DELETE /api/v1/auth/identities/github`. Sessions that signed in with GitHub end. The server refuses with `409` when this browser signed in with GitHub (`current_sign_in`) or when GitHub is the account's only way to sign in (`last_sign_in`).
- Signing in with GitHub never creates an account. Sign-in refuses a GitHub account that belongs to no member (`not_a_member`). A person joins with GitHub through an invite link, and an existing member adds GitHub from their account settings.
- The sign-in keeps its state in a cookie named `sluby_signin` in the browser that started it (path `/api/v1/auth`, HttpOnly, valid for 10 minutes). The callback accepts only the state that cookie holds, so it refuses a callback opened in another browser, or after 10 minutes, with `expired_handshake`.

## Sessions and cookies [#sessions]

Each Studio sign-in creates a row in `studio_sessions` with the member, the sign-in method used, the browser's user agent (first 500 characters) and its expiry.

The browser gets the `sluby_session` cookie ([its attributes](/developers/reference/api-conventions#session-cookie)). The cookie value holds the session row id, the account id and the expiry, signed with HMAC-SHA256 using `SESSION_SECRET`.

On every request the backend checks the signature and the expiry, then that the session row is neither ended nor expired, then that the member is not removed. Because the backend checks the row each time, the server can end a session at any moment.

- **Lifetime.** A session lasts 7 days from sign-in. Using it does not extend it.
- **Last seen.** The backend updates the session's `last_seen_at` at most once every 5 minutes. The Settings page shows it in the list of signed-in browsers.
- **Ending sessions.** A session ends when the member signs out (`POST /api/v1/auth/logout`), ends one session (`DELETE /api/v1/auth/sessions/{id}`), signs out everywhere (`DELETE /api/v1/auth/sessions`, which leaves API keys untouched), changes their password (every other session ends), uses a reset link (every session ends), or is removed by an admin (every session ends).
- **Why a session stopped working.** A request with a cookie that no longer works gets `401` with a `reason`: `missing` (no cookie, or a cookie this server did not sign), `expired`, `revoked` (signed out here or elsewhere), or `not_allowed` (the member was removed).
- **Cleanup.** Ended sessions keep their rows for 30 days, then the hourly sweep deletes them.
- **Changing SESSION_SECRET.** The backend signs every cookie with `SESSION_SECRET`, so changing it signs every member out. [Security model](/developers/concepts/security#session-secret) lists what else depends on it.

## First admin and the setup code [#setup-code]

A fresh install has no admin. While sign-in is on and no admin who can sign in exists, the backend writes a setup code to its log at every start, and `GET /api/v1/auth/config` reports `setup_required: true`. An admin counts as able to sign in when the account is not removed and has at least one sign-in method; the local development account of an `AUTH_DISABLED` run does not count.

- The backend derives the code from `SESSION_SECRET` with HMAC-SHA256, so only someone who can read the server's logs or environment has it. It is 10 characters from the Crockford base32 alphabet, shown as `XXXXX-XXXXX`.
- When checking a typed code, the server ignores case, spaces and dashes, and reads `I` and `L` as `1` and `O` as `0`.
- `POST /api/v1/auth/setup` takes the code, a name, an email and a password, creates the first admin and signs them in. Once an admin who can sign in exists, setup answers `409` with `This server already has an admin. Sign in instead.`, so the code stops working the moment it is used.

[Set up sign-in](/self-hosting/sign-in) describes where the operator finds the code.

## Invites and reset links [#invites-and-reset-links]

Admins hand out two kinds of links: invite links, which let new people join, and reset links, which let one member set a password. Both are rows in the `invites` table and share these rules:

- The token is 32 random bytes in base64url (43 characters). The server stores only its SHA-256 hash, so the table alone is not enough to join or to take over an account.
- The full URL appears once, in the response that creates it. No later response shows it again.
- A reset link works once, for 7 days. An invite link works for 1, 7 or 30 days (7 by default) and for as many people as the admin chose (see [Invite links](#invite-links)).
- Using a link locks its row for the transaction, so two browsers using its last place at the same moment cannot both succeed.
- A link that does not exist answers `404` with `This link does not exist. Ask an admin for a new one.` A used-up, expired or withdrawn link answers `410` with `This link was already used.`, `This link has expired.` or `This link was withdrawn.`, each followed by `Ask an admin for a new one.`

### Invite links [#invite-links]

An admin creates an invite with a role (`POST /api/v1/invites`, [endpoint reference](/developers/reference/api/members/post-invites)). The link has the form `https://sluby.example.com/studio/join/<token>`. Each new member joins with a name, email and password, or with GitHub.

- `max_uses` sets how many people can join with the link: 1 (the default), a number up to 1000, or `null` for anyone with the link until it expires or is revoked. The row counts joins in `use_count` and sets `used_at` when the last allowed person joins.
- Only a member invite can let more than one person join, because anyone can pass a link on. An admin invite with `max_uses` set to `null` or to a number from 2 to 1000 answers `400` with `An admin invite lets one person join. Invite more people as members.`, and the database refuses such a row as well.
- `expires_in_days` is 1, 7 or 30, and 7 when left out.
- A GitHub account that already belongs to a member cannot join a second time, and that attempt does not count as a join.

Admins list the invites that still let someone join, with `max_uses` and `uses` for each, and can withdraw any of them. Withdrawing stops new joins. People who already joined stay members.

### Reset links [#reset-links]

A reset link lets one member set a new password. An admin creates it for a member (`POST /api/v1/members/{id}/reset-link`, [endpoint reference](/developers/reference/api/members/post-members-id-reset-link)), and an operator who is locked out can print one on the server for an account that signs in with an email ([Make a reset link from the command line](/self-hosting/sign-in#make-a-reset-link-from-the-command-line)). The link has the form `https://sluby.example.com/studio/reset/<token>`.

- A member who already has a password sets a new one.
- A member who signs in with GitHub only sets their first password and chooses the email they will sign in with.
- Using the link ends every session the member had, then signs the current browser in.
- The API refuses a reset link for a removed member with `403` and `This account was removed from this workspace`.

## Removing members and the last-admin protection [#removing-members]

Admins remove members rather than delete them:

- **Remove.** The member's row stays, so their API keys and history keep a name. They can no longer sign in, every session they have ends at once, and their API keys stop working. An admin cannot remove themselves; the API answers `409` with `You cannot remove yourself. Ask another admin.`
- **Restore.** The member comes back with the role they had, and their API keys work again.

The API refuses a role change or a removal that would leave the workspace with no admin who can sign in, with `409` and `This is the last admin who can sign in. Make someone else an admin first.` These changes run one at a time, so two admins demoting each other at the same moment cannot both succeed.


# Architecture (/developers/concepts/architecture)

A Sluby server is a small set of containers: a web proxy, one backend process, PostgreSQL and Redis. The backend stores every video on the Sia network through a Sia indexer. This page explains what each part does and how they connect.

## The parts at a glance [#the-parts-at-a-glance]

```mermaid
flowchart LR
  browser["Browser: Studio, watch page, @sluby/player"]
  yourapp["Your server: @sluby/sdk or REST"]
  caddy["caddy (production only): TLS"]
  web["web: nginx<br/>Studio files, proxy, delivery cache"]
  subgraph backend["backend: one Node.js process"]
    api["REST API and tus uploads<br/>/api/v1"]
    gateway["Delivery gateway<br/>/v1/objects, /v1/stream, /v1/share"]
    watch["Watch page<br/>/watch"]
    workers["Queue workers<br/>transcode, upload-segments, finalize,<br/>deletion, reconcile, webhooks"]
  end
  pg[("PostgreSQL")]
  redis[("Redis")]
  disk[("Volumes: uploads, transcode-output")]
  indexer["Sia indexer"]
  hosts["Sia hosts"]
  receivers["Your webhook receivers"]

  browser --> caddy
  yourapp --> caddy
  caddy --> web
  web --> api
  web --> gateway
  web --> watch
  api --> pg
  api --> redis
  api --> disk
  api --> indexer
  workers --> redis
  workers --> pg
  workers --> disk
  workers --> indexer
  workers --> hosts
  workers --> receivers
  gateway --> pg
  gateway --> indexer
  gateway --> hosts
  watch --> pg
  browser -.->|"direct and hybrid playback"| indexer
  browser -.->|"direct and hybrid playback"| hosts
```

Without the production override there is no caddy container: browsers and your server talk to the `web` container directly, which publishes its port on `127.0.0.1` (`http://localhost:8080` by default). With `docker-compose.prod.yml`, caddy is the only container that publishes ports (80 and 443) and terminates TLS for your domain. See [Run in production](/self-hosting/production).

Two Sia terms appear throughout:

- A **host** is a storage provider on the Sia network. The Sia SDK uploads the encoded pieces of each file to hosts and downloads them from hosts.
- An **indexer** is the Sia service that Sluby registers with as an app. It keeps the list of objects (stored files) that Sluby has pinned on its account and tells the SDK which hosts hold them. Sluby connects to `https://sia.storage` or to another indexer URL you configure.

[Storage on Sia](/developers/concepts/storage-on-sia) explains objects, pinning and redundancy in detail.

## The web proxy (nginx) [#the-web-proxy-nginx]

The `web` container runs nginx with the Studio build baked into the image. It does three jobs:

- **Serves the Studio.** `/` redirects to `/studio`, and every route under `/studio` answers with the single-page app.
- **Proxies to the backend.** `/api/`, `/v1/`, `/watch/` and `/health` go to the backend on port 3000. nginx never caches anything under `/api/`, sets no body size limit there and forwards request bodies without buffering them, so large uploads stream straight to the backend.
- **Caches delivery.** Responses under `/v1/objects/`, `/v1/stream/` and `/v1/share/` pass through an on-disk cache, and per-client rate limits apply to `/v1/` and `/api/v1/auth/`. [Playback and delivery](/developers/concepts/playback) describes what the cache keeps and for how long.

nginx passes the client address and the `X-Forwarded-Proto` header that caddy sends on to the backend. The backend uses the address for its per-client API rate limit and the scheme to recognize write requests that come from its own origin. nginx re-resolves the backend's address every 10 seconds, so a recreated backend container is found without restarting the proxy.

## The backend process [#the-backend-process]

The backend is one Node.js process (Express). The same process serves HTTP and runs every queue worker, so one `backend` container handles both requests and background jobs.

On start, the container first runs the database migrations, then starts the server. Before it accepts requests the process loads the session secret it keeps in the database when `SESSION_SECRET` is not set, seeds `BOOTSTRAP_API_KEY` when you set one, takes over the access settings of an older version once, and, with sign-in on, logs the setup code when the install has no admin yet. It then listens on `PORT` (3000 in the compose files) and, when `SIA_APP_KEY` is set, connects to the Sia indexer.

### HTTP surfaces [#http-surfaces]

| Path                                                                             | What it serves                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/v1`                                                                        | The REST API used by the Studio, `@sluby/sdk` and your own code. See [API conventions](/developers/reference/api-conventions).                                                                                                                                                            |
| `/api/v1/uploads`                                                                | Resumable uploads over the [tus protocol](https://tus.io). A request that carries the `Tus-Resumable` header, or uses `HEAD`, `PATCH` or `OPTIONS`, goes to the tus server. Any other request, such as the upload status `GET`, goes to the REST routes.                                  |
| `/v1/objects/:objectId`, `/v1/stream/:videoAssetId/master.m3u8`, `/v1/share/:id` | The delivery gateway: HLS manifests and media read from Sia, and share maps for direct playback.                                                                                                                                                                                          |
| `/watch/:id`                                                                     | The public watch page that other sites can embed in an iframe.                                                                                                                                                                                                                            |
| `/health`                                                                        | The health check. The Docker health checks of both the `backend` and the `web` container call it (the `web` one through nginx).                                                                                                                                                           |
| `/metrics`                                                                       | Prometheus metrics. A scraper inside the Docker network reaches it on the backend's port 3000. nginx forwards it too, but without [`METRICS_TOKEN`](/self-hosting/configuration#metrics_token) the backend answers a forwarded request `404`; with it, every request must send the token. |

### Queues and workers [#queues-and-workers]

The backend uses [BullMQ](https://docs.bullmq.io) queues stored in Redis. The backend process runs a worker for every queue.

| Queue             | What a job does                                                                                                          | Who adds jobs                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `transcode`       | Runs FFmpeg on an uploaded source to produce the HLS renditions and thumbnails.                                          | The tus server, when an upload completes, and the retry endpoint.                       |
| `upload-segments` | Uploads a finished transcode to Sia.                                                                                     | The `transcode` worker, and the retry endpoint when a finished transcode can be reused. |
| `finalize`        | Records the uploaded objects on the video, marks it `ready` and sends `asset.ready`.                                     | The `upload-segments` worker.                                                           |
| `deletion`        | Unpins a deleted video's Sia objects and removes its rows. A repeating `gc` job re-drives deletions that never finished. | Deleting a video, cancelling or abandoning an upload, and the `gc` schedule.            |
| `reconcile`       | Compares the objects Sluby tracks with the objects pinned on the indexer.                                                | A repeating schedule and the manual trigger.                                            |
| `webhooks`        | Sends one event to one webhook endpoint, with retries.                                                                   | Every place that emits an event, and a manual resend of an earlier delivery.            |

Each pipeline stage hands off to the next under a fixed job id, so a stage that runs twice starts its successor once. [Upload pipeline](/developers/concepts/upload-pipeline) follows a video through the three processing queues, and [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation) covers the `deletion` and `reconcile` queues.

The process also runs an hourly timer that removes expired incomplete uploads and their rows, removes finished source files, prunes ended Studio sessions and drops old webhook delivery logs.

### Local files [#local-files]

Two Docker volumes hold files that live only on the backend's disk:

- `uploads` (`UPLOAD_DIR`): incoming tus uploads and their source files.
- `transcode-output` (`TRANSCODE_OUTPUT_DIR`): FFmpeg output waiting to be uploaded to Sia.

Once processing finishes, the backend serves the video from Sia, not from these volumes.

## PostgreSQL and Redis [#postgresql-and-redis]

PostgreSQL holds the durable state: videos, renditions, the map from every Sia object id to its video, accounts, sessions, API keys, webhooks and reconciliation runs. [Data model](/developers/concepts/data-model) describes the tables.

Redis holds the BullMQ queues, the schedules of the repeating jobs, and short-lived leases. One lease stops a second execution of an upload job (BullMQ starts one when the job's lock expires) from uploading the same video to Sia while the first execution is still running; the others hold back a slab prune (the cleanup of stored Sia data that no object uses any more) while any upload is in flight. The compose file starts Redis with append-only persistence and the `noeviction` memory policy, so queued jobs survive a restart and are never evicted.

## Sia [#sia]

The backend talks to Sia through the official `@siafoundation/sia-storage` SDK. It connects to the indexer at `SIA_INDEXER_URL` with the app key from `SIA_APP_KEY`, which the connect step prints when you register the server with the indexer (see [Connect Sia storage](/self-hosting/sia-storage)). The SDK uploads the pieces of each file to hosts and reports, for each piece, the host that stored it.

Two paths read from Sia:

- **The delivery gateway** looks each object up on the indexer, downloads the requested bytes from hosts, and streams them to the viewer through nginx.
- **The browser** can download from Sia itself. The player fetches a share map from `/v1/share/:id`, which lists a time-limited `sia://` share URL for each object of the video, then uses the Sia SDK in the browser with a separate viewer identity to download from the indexer and hosts. The backend stays out of the byte path.

[Playback and delivery](/developers/concepts/playback) explains the gateway, direct and hybrid modes, and [Stream from Sia in the browser](/self-hosting/direct-playback) shows how to turn on the browser path.

## Webhook receivers [#webhook-receivers]

The `webhooks` worker sends HTTP requests from the backend to the URLs you register. See [Receive webhooks](/developers/guides/webhooks) and [Webhook events](/developers/reference/webhook-events).


# Data model (/developers/concepts/data-model)

Sluby keeps its durable state in PostgreSQL. Video bytes live on Sia; the database holds the records that describe each video and map it to the Sia objects it is stored as, plus accounts, keys, webhooks and reconciliation history. This page describes the tables and how they relate. `backend/src/db/schema.ts` defines the schema with Drizzle.

A Sia **object** is one stored file on the Sia network, identified by an object id. Every manifest, playlist, media file and thumbnail of a video is its own object. **Pinning** an object keeps it stored under Sluby's account on the Sia indexer; unpinning it releases it. [Storage on Sia](/developers/concepts/storage-on-sia) explains objects in detail.

## Ownership [#ownership]

One install is one team's workspace. Every video, API key and webhook endpoint carries the owner address `workspace` in its `creator_address` column (an upload carries it in its metadata), and every caller acts as that owner. What a caller can do depends on their role, not on which rows they own. See [Accounts, roles and sessions](/developers/concepts/accounts-and-roles).

## How the tables relate [#how-the-tables-relate]

The diagram shows every foreign key in the schema. Tables without foreign keys are listed after it.

```mermaid
erDiagram
  video_assets ||--o{ upload_sessions : "video_asset_id (set null)"
  video_assets ||--o{ processing_jobs : "video_asset_id (cascade)"
  upload_sessions ||--o{ processing_jobs : "upload_session_id (cascade)"
  video_assets ||--o{ renditions : "video_asset_id (cascade)"
  video_assets ||--o{ artifacts : "video_asset_id (cascade)"
  renditions ||--o{ artifacts : "rendition_id (cascade)"
  video_assets ||--o{ playback_ids : "video_asset_id (cascade)"
  video_assets ||--o{ asset_plays_daily : "video_asset_id (cascade)"
  users ||--o{ user_identities : "user_id (cascade)"
  users ||--o| password_credentials : "user_id (cascade)"
  users ||--o{ studio_sessions : "user_id (cascade)"
  user_identities ||--o{ studio_sessions : "identity_id (cascade)"
  users ||--o{ invites : "user_id (cascade)"
  users ||--o{ invites : "created_by (set null)"
  users ||--o{ api_keys : "created_by (set null)"
  api_keys ||--o{ api_keys : "replaced_by_id (set null)"
  api_keys ||--o{ webhook_endpoints : "api_key_id (set null)"
  webhook_endpoints ||--o{ webhook_deliveries : "webhook_endpoint_id (cascade)"
```

The label on each line names the foreign key column and what happens to the row when the referenced row is deleted: `cascade` deletes it, `set null` clears the column.

Tables without foreign keys: `pending_objects`, `reconciliation_runs`, `indexer_objects`, `reconcile_feed`, `bootstrap_keys`, `instance_meta` and `allowlist_pins`.

## Videos [#videos]

### video_assets [#video_assets]

One row per video: title, description, duration, resolution, status, access tier (`public` or `private`), the owner, and the Sia objects the video is stored as (`manifest_object_id`, `thumbnail_object_ids`, `sia_object_ids`), with `segment_count` and `total_storage_bytes`.

The `status` column is `created`, `uploading`, `processing`, `ready` or `failed`. [Asset status](/developers/concepts/upload-pipeline#asset-status) lists when each one is set.

Other columns worth knowing:

- `signing_generation` is part of every signed URL of the video. Raising it invalidates every URL signed before. [Playback and delivery](/developers/concepts/playback) explains signed URLs and revocation.
- `deleted_at` marks a deletion in progress. While it is set, every API read leaves the video out; the deletion worker removes the row once the video's Sia objects are unpinned. See [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation).
- `last_played_at` records the newest counted play. It is written without touching `updated_at`, so a play never changes the video's ETag.

### upload_sessions [#upload_sessions]

One row per tus upload: the file path on the backend's disk, the file size, bytes received so far, the SHA-256 of the finished file, an expiry time and a status (`uploading`, `completed`, `cancelled` or `failed`). `video_asset_id` is cleared, not deleted, when its video row is removed.

### processing_jobs [#processing_jobs]

The record of a video's processing run, which the API reads for progress: `status` (`queued`, `processing`, `completed`, `failed` or `retrying`), `progress_percent`, `error_message`, `retry_count`, a `retryable` flag (false when the source is not a readable video) and `logs`, a list of timestamped messages per stage. The queue jobs themselves live in Redis; this table mirrors their state. See [Upload pipeline](/developers/concepts/upload-pipeline).

### renditions [#renditions]

One row per quality level of a video: `name`, `width`, `height`, `video_bitrate_kbps`, `segment_count`, `byte_size`, and two object ids: `data_object_id` (the rendition's single media file) and `playlist_object_id` (its variant playlist). [Upload pipeline](/developers/concepts/upload-pipeline) describes the ladder of renditions.

### artifacts [#artifacts]

The map from every stored Sia object id to its video, its rendition when it has one, and its role. The role is empty only for objects of videos stored before this table existed.

| Role               | Object                    |
| ------------------ | ------------------------- |
| `master_manifest`  | The HLS master playlist.  |
| `variant_playlist` | A rendition's playlist.   |
| `rendition_data`   | A rendition's media file. |
| `thumbnail`        | A thumbnail image.        |

Every object id in a video's `manifest_object_id`, `thumbnail_object_ids` and `sia_object_ids` has a row here. The delivery gateway finds the video behind a requested object id in this table to decide access, the per-video storage breakdown reads it, deletion collects the object ids to unpin from it, and reconciliation compares its object ids with the indexer's.

### pending_objects [#pending_objects]

Sia objects that are pinned but not recorded in `artifacts`, and objects waiting to be unpinned. The upload stage writes a row right before it pins each object, and `finalize` moves the object into `artifacts`. `state` is `uploading` while the run that pinned the object can still record it, and `release` once nothing will and the object must be unpinned. The table has no foreign key on purpose: a row has to outlive its video, because an upload can still pin an object after the video row is gone, and the deletion `gc` sweep unpins what is left here.

### playback_ids [#playback_ids]

Public handles for a video, each with a `playback_id` value of the form `pb_...`, a `policy` (`public` or `signed`) and a `name`. You can create several per video and delete one without changing the video. See [Playback and delivery](/developers/concepts/playback).

### asset_plays_daily [#asset_plays_daily]

Play counts per video and UTC day, one row per video and day (primary key `video_asset_id`, `day`).

## Accounts and access [#accounts-and-access]

### users [#users]

One row per member of the workspace: `display_name`, `role` (`admin` or `member`) and `disabled_at`, set when an admin removes the member. A removed member's row stays, so their keys and history still point at a name and restoring them is one update.

### user_identities [#user_identities]

The ways an account signs in. Each row has a `provider`, the provider's stable `subject` for the person (for GitHub, the numeric account id) and the `username` reported at the last sign-in, kept for display. The pair `provider`, `subject` is unique.

### password_credentials [#password_credentials]

The email and password hash of an account that signs in with a password. The email is lowercase and unique.

### studio_sessions [#studio_sessions]

One row per Studio sign-in. The signed session cookie names its row ([Sessions and cookies](/developers/concepts/accounts-and-roles#sessions)), so the server can end a session on sign-out, from the sessions list, or when an admin removes the member. Each row records the account, the identity used to sign in, the user agent, `expires_at`, `revoked_at` and `last_seen_at`.

### invites [#invites]

Links an admin hands out. `kind` is `invite` (new people join with `role`) or `reset` (the member `user_id` sets a new password). The table stores only the SHA-256 hash of the token, so nobody can sign in with what it holds. Each row has `expires_at`, `used_at` and `revoked_at`, plus `max_uses` (how many people can join: 1 by default, `null` for no limit) and `use_count` (how many times the link was used). A check constraint allows a `max_uses` other than 1 only on a member invite, and `used_at` is set when the last allowed use happens ([Invites and reset links](/developers/concepts/accounts-and-roles#invites-and-reset-links)).

### api_keys [#api_keys]

API keys, stored as SHA-256 hashes. The API returns the raw key once, at creation. Each row has a `name`, `scopes`, a `rate_limit`, `is_active`, an optional `expires_at`, `prefix` (the first 12 characters of the raw key), `last_used_at`, `created_by` (the member who made the key) and `replaced_by_id` (the key that replaced it in a rotation). A key acts with its maker's current role and stops working while the maker is removed; a key with no maker, such as one seeded from the server, acts as an admin. [API conventions](/developers/reference/api-conventions) describes scopes.

### bootstrap_keys [#bootstrap_keys]

The hash of every `BOOTSTRAP_API_KEY` ever seeded. A hash listed here is never seeded again, so deleting or rotating away the bootstrap key stays in effect across restarts while the variable is still set.

## Webhooks [#webhooks]

### webhook_endpoints [#webhook_endpoints]

The workspace's webhook URLs: `url`, `events` (the event types the endpoint receives), its signing `secret`, `is_active`, and `api_key_id`, the key it was registered with (empty when someone registered it from the Studio). The link records who registered it, not who owns it, so revoking the key keeps the endpoint.

### webhook_deliveries [#webhook_deliveries]

One row per delivery attempt: `event_type`, `payload`, the receiver's `status_code`, an `error` message written by Sluby, `delivered_at`, `retry_count` and `manual` (a resend someone asked for). Sluby never stores the receiver's response body. Retries wait in Redis, not in this table. See [Delivery log](/developers/reference/webhook-events#delivery-log).

## Reconciliation [#reconciliation]

### reconciliation_runs [#reconciliation_runs]

One row per reconciliation pass: start and finish time, `status` (`ok`, `drift` or `failed`), object counts (`db_object_count`, `indexer_object_count`, `in_sync_count`, `orphan_count`, `missing_count`), the full lists `orphaned_ids` and `missing_ids`, and `error_message` for a failed run.

### indexer_objects and reconcile_feed [#indexer_objects-and-reconcile_feed]

`indexer_objects` is reconciliation's copy of the indexer's object inventory: for each object id, whether its latest event was a deletion and when that event happened. `reconcile_feed` is a single row naming the indexer feed (the indexer URL and account key) that copy was built from, and a cursor for where the next run resumes reading. A run against a different feed starts the copy over. See [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation).

## Install state [#install-state]

- `instance_meta` stores one-off facts about the install as key and JSON value pairs, such as the session secret the install generated when `SESSION_SECRET` is not set, and whether the access settings of an older version were already adopted.
- `allowlist_pins` ties a GitHub login from the old allowlist setting to the account that held it. Startup reads it only to adopt an install that used the allowlist.

## Migrations [#migrations]

Migrations live in `backend/drizzle` as SQL files. The backend container runs them on every start before it starts the server; the `__drizzle_migrations` table records the applied migrations, so the step changes nothing in a database that is up to date. The migration step takes a PostgreSQL advisory lock first, so several backend containers starting together migrate one at a time.


# Deletion and reconciliation (/developers/concepts/deletion-and-reconciliation)

This page explains what Sluby does, step by step, when you delete a video, how a background sweep finishes deletions that stopped part way, and how reconciliation compares the objects Sluby records in PostgreSQL with the objects the Sia indexer holds for your account.

Two Sia terms appear throughout. The **indexer** is the Sia service Sluby stores data through: a self-hosted `indexd` or the hosted `sia.storage`. An **object** is one stored file (a playlist, a media segment, a thumbnail), named by a 64-character hex object id. While an object is **pinned**, the indexer keeps it for your account; **unpinning** tells the indexer to drop it. For the full storage model, see [Storage on Sia](/developers/concepts/storage-on-sia).

## What starts a deletion [#what-starts-a-deletion]

Every path below calls the same deleter:

- `DELETE /api/v1/assets/{id}` with the `manage` scope ([endpoint reference](/developers/reference/api/assets/delete-assets-id)). The Studio and the `@sluby/sdk` method `assets.delete()` both call this endpoint.
- Cancelling an upload that is still in progress, with a `DELETE` request on the upload URL of the tus resumable upload protocol, or with `DELETE /api/v1/uploads/{id}` ([endpoint reference](/developers/reference/api/uploads/delete-uploads-id)). The deleter removes the video the upload created.
- An upload that expires before it finishes. The hourly upload sweep marks the upload session `failed` and deletes the video when its status is still `created` or `uploading`.
- An upload creation request that fails after Sluby created the video row.

## Step 1: the video disappears at once [#step-1-the-video-disappears-at-once]

The deleter sets the video's `deleted_at` timestamp in the same request. From that moment:

- Every read in the API treats the video as gone. `GET /api/v1/assets/{id}` and the playback routes answer `404`.
- The response to `DELETE /api/v1/assets/{id}` is `200` with `{"success": true, "status": "deleting"}`. The `deleting` status tells you the rest of the work runs in the background.
- A second `DELETE` for the same video answers `404`, because only a video that is not already being deleted matches.

The deleter then queues a job named `delete` on the `deletion` queue, with the job id `delete-<video id>`.

## Step 2: the deletion job [#step-2-the-deletion-job]

The deletion worker runs up to two jobs at once. Each job does the following, in this order:

```mermaid
flowchart TD
  A[Collect the video's object ids] --> B[Remove the source upload files]
  B --> C[Remove the transcode output directory]
  C --> D{For each object id}
  D --> E[Unpin the object at the indexer]
  E -->|unpinned, or the indexer does not have it| F[Evict it from the delivery cache]
  F --> G[Remove the id from the video's records]
  G --> D
  E -->|error| H[Note the object as failed]
  H --> D
  D -->|all ids tried| I[Prune slabs]
  I --> J{Any object failed?}
  J -->|yes| K[Job fails and keeps the row for a retry]
  J -->|no| L[Delete the video row]
```

1. **Collect the object ids.** The job reads them fresh on every attempt from every place Sluby records an object id: the `artifacts` rows, the `pending_objects` rows (objects a processing run pinned but has not recorded yet), the master manifest id, the thumbnail ids, and the older flat `sia_object_ids` list. The job drops duplicates and empty values.
2. **Remove local files.** The job deletes the source upload still on disk (a failed video keeps it for a retry) and the video's transcode output directory.
3. **Unpin each object.** The job unpins each object separately, so an object that fails does not stop the others. An object the indexer reports as not found counts as unpinned. After each successful unpin, the job evicts the object from the delivery cache and removes its id from the `artifacts` row, the `pending_objects` row and the video's id fields. Recording each object as it goes means a retry only tries the objects that remain.
4. **Prune slabs.** A **slab** is an erasure-coded segment of stored data; objects from a packed upload share slabs. Pruning asks the indexer to unpin every slab of the account that no object uses anymore. When an upload to the same Sia account is running on any backend process, the prune does not run at once: it runs when the last upload ends, and the job continues without waiting for it. The job logs a pruning failure and carries on. [Storage on Sia](/developers/concepts/storage-on-sia#slab-pruning) explains pruning in full.
5. **Delete the row, or retry.** When every object is unpinned, the job deletes the video row. The database removes the video's renditions, artifacts, processing jobs, playback ids and daily play counts with it. The video's upload session rows stay, with their link to the video cleared and their metadata emptied; the hourly upload sweep deletes them once their files are gone. When any object failed, the job throws an error and the row stays, still marked deleted.

The queue runs a failed job up to 3 attempts in total, with exponential backoff that starts at 30 seconds. After that, the garbage-collection sweep below takes over.

### A video deleted while it is processing [#a-video-deleted-while-it-is-processing]

Each processing stage (transcode, Sia upload, finalize) first checks that its video still exists and is processing. A stage for a deleted video stops without doing its work. When finalize finds the video gone, it unpins the objects its run uploaded and removes the video's transcode output. The [upload pipeline](/developers/concepts/upload-pipeline) page describes the stages.

## The garbage-collection sweep [#the-garbage-collection-sweep]

The deletion queue also carries a scheduled `gc` job. Each run of it does three things, and runs every part even when an earlier part fails:

1. **Re-drives stuck deletions.** It finds videos that were marked deleted longer ago than [`DELETION_STUCK_THRESHOLD_MS`](/self-hosting/configuration#deletion_stuck_threshold_ms) and still have a row. For each such video whose `delete` job is not waiting, delayed or running, it queues a new `delete` job under the id `redrive-<video id>`, so two deletions of one video never run at the same time. From the fifth re-drive of one video on, each re-drive logs the error `Asset deletion keeps failing; check the deletion job errors`.
2. **Releases leftover objects.** It marks for release every object a processing run pinned and can no longer record (its video is gone, being deleted, or no longer processing), then unpins every object marked for release. An object that fails to unpin stays marked, and the next run tries it again.
3. **Removes unused transcode output.** It deletes the transcode output directories of videos that are ready, deleted or missing. It keeps the output of every other video, such as one that is processing or failed, because the pipeline or a retry reads it.

`DELETION_GC_ENABLED` turns the sweep on or off and `DELETION_GC_INTERVAL_MS` sets how often it runs (see [Configuration](/self-hosting/configuration#deletion_gc_enabled)). The backend writes the schedule to Redis at every start: a changed interval replaces the old schedule, and turning the sweep off removes it.

## What happens to links, playback and webhooks [#what-happens-to-links-playback-and-webhooks]

- **Playback ids, signed URLs and share URLs.** Once a video is marked deleted, the API stops minting signed URLs and `sia://` share URLs for it, and its playback ids stop resolving. The database deletes the playback id rows with the video row. Deletion does not revoke `sia://` share URLs minted before it; [Playback and delivery](/developers/concepts/playback) describes their lifetime.
- **Watch page and stream entry.** `/watch/{id}` answers `404` with the message "This video is not available". `/v1/stream/{id}/master.m3u8` answers `404` with `Video asset not found or not ready`.
- **Object delivery.** The gateway answers `404` with `Object not found` for every object of a video that is being deleted. The backend process that handled the delete applies this immediately. Another backend process sharing the database applies it within a minute, when its cached state of the video expires. Behind the bundled nginx, nginx keeps serving a small public object (a manifest, playlist or thumbnail) it already holds in its cache for up to 60 seconds.
- **Webhooks.** Deleting a video sends no webhook event. The `DELETE` response is the confirmation. [Webhook events](/developers/reference/webhook-events) lists the events Sluby sends.

## Reconciliation [#reconciliation]

Reconciliation compares the object ids PostgreSQL records with the objects the indexer reports as pinned for the Sia account, and saves the result as a report. It only reports. It never pins, unpins or deletes anything, so an operator decides what to do about drift.

### How a run works [#how-a-run-works]

1. **Read the database.** The run reads the `pending_objects` rows first, then every recorded object id: the `artifacts` rows plus the manifest, thumbnail and older flat ids on every video row.
2. **Update the saved copy of the indexer's inventory.** The Sia SDK has no call that lists every object. The indexer offers an object event feed instead, with one event per object (its latest pin or delete). Sluby keeps a copy of the inventory in the `indexer_objects` table and the feed position in `reconcile_feed`, so each run reads only the events since the last one. The run reads the feed in pages of at most 500 events ([`RECONCILE_PAGE_SIZE`](/self-hosting/configuration#reconcile_page_size)). When the indexer URL or the Sia account changes, the saved copy starts over from the beginning of the feed.
3. **Compare the two sides** and save the run in `reconciliation_runs`. The table keeps the latest 100 runs.

### Drift kinds [#drift-kinds]

The comparison sorts each object id into one of four groups. A one-hour grace window keeps work in progress out of the drift lists: an upload pins its objects minutes before finalize records them, and a deletion unpins objects moments before it forgets them.

| Group     | Meaning                                                                                                                                                                                                                                                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| In sync   | Recorded in the database and pinned at the indexer.                                                                                                                                                                                                                                                                                              |
| Missing   | Recorded in the database, but the indexer does not report it as pinned, and the indexer has not changed it within the last hour. This is the case to investigate: data loss, or an object that never finished pinning.                                                                                                                           |
| Orphaned  | Pinned at the indexer, not recorded in the database, not changed within the last hour, and not owned by a processing run. Objects of a run that is still uploading never count as orphaned, however long the upload takes. An object marked for release that is still pinned after the hour counts as orphaned, because its unpin keeps failing. |
| In flight | Not in sync, and either changed at the indexer within the last hour or still owned by a processing run. Counted, but left out of the missing and orphaned lists.                                                                                                                                                                                 |

A run ends with one of three statuses: `ok` when nothing is missing or orphaned, `drift` when something is, and `failed` when the run could not finish (for example, the indexer did not answer). Sluby saves a failed run too, with zero counts and its error message, so an outage shows up as a failed report rather than a stale one.

### Schedule and on-demand runs [#schedule-and-on-demand-runs]

`RECONCILE_ENABLED` turns the scheduled run on or off and `RECONCILE_INTERVAL_MS` sets how often it runs (see [Configuration](/self-hosting/configuration#reconcile_enabled)). Like the deletion sweep, the schedule lives in Redis and is rewritten at every start.

An admin can also start a run with `POST /api/v1/reconciliation/run` ([endpoint reference](/developers/reference/api/reconciliation/post-reconciliation-run)). It needs the `manage` scope and an admin caller. It answers `202` with `enqueued` and `already_pending`. At most one run waits or runs at a time: a trigger or a scheduled tick that arrives while a run is pending adds nothing, and the response says `"already_pending": true`. The queue runs each run once and does not retry a failed one.

### Reading the report [#reading-the-report]

`GET /api/v1/reconciliation` ([endpoint reference](/developers/reference/api/reconciliation/get-reconciliation)) returns the latest saved run, including a failed one, and needs the `manage` scope. It answers `404` with `No reconciliation run has completed yet` until Sluby saves the first run. What the report contains depends on the caller's role ([roles](/developers/concepts/accounts-and-roles)):

- **Admin:** `scope` is `deployment`. The report has every count (`db_object_count`, `indexer_object_count`, `in_sync_count`, `orphan_count`, `missing_count`), `missing_ids`, `orphaned_ids`, `error_message`, and `missing_objects`, which pairs each missing object id with the video that holds it (`video_asset_id` and `title`, or `null` when no live video holds it).
- **Member:** `scope` is `account`. The report has `status`, `missing_count`, `missing_ids` and `missing_objects`, limited to object ids that belong to the workspace's videos. `status` is `failed` when the run failed, `drift` when one of those ids is missing, and `ok` otherwise. The report leaves out the deployment-wide counts, the orphans and the error message.

For what to do about drift on a running server, see [Monitor and maintain](/self-hosting/operations).


# Playback and delivery (/developers/concepts/playback)

This page explains every path a video takes from Sia storage to a player: the delivery gateway on your Sluby server, direct playback from Sia in the browser, and hybrid playback that mixes the two. It also covers what makes a private video private: signed URLs, their lifetime and revocation, share URLs, playback ids, the public watch page, caching and play counting.

A few Sia terms first. Sia is a decentralized storage network: independent storage providers, called hosts, keep the data. An **object** is one stored file on Sia, named by an object id of 64 lowercase hex characters. The **indexer** is the service that Sluby's backend and the browser connect to in order to look objects up and reach the hosts that hold them. A **share URL** is a signed `sia://` URL, made by the Sia SDK, that lets a Sia client read one object until a set time.

## What a stored video looks like [#what-a-stored-video-looks-like]

Every rendition of a video is stored on Sia as one data file plus one HLS playlist, and the video has one HLS master playlist that lists the rendition playlists. Each file is its own Sia object. The playlists Sluby stores name the other objects by root-relative gateway paths of the form `/v1/objects/{objectId}`, and they address the segments of a data file with byte ranges. Because the paths carry no host name, the same stored playlists play through any origin that serves the gateway, and the direct-from-Sia player reads the object id out of the path. How the files are produced is on [Upload pipeline](/developers/concepts/upload-pipeline).

## Delivery modes [#delivery-modes]

| Mode    | Where the bytes come from                                                         | When it applies                                                                                                                                 |
| ------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Gateway | Your Sluby server reads from Sia and streams to the player over HTTP              | Always available. The watch page, plain hls.js, Safari's native HLS, and any player without a Sia viewer session use it.                        |
| Direct  | The browser downloads every playlist and segment from Sia itself, with share URLs | `@sluby/player` with a Sia viewer session and `siaDelivery="direct"` (the default when a session exists)                                        |
| Hybrid  | Playlists and urgent segments from the gateway, the rest from Sia                 | `@sluby/player` with a Sia viewer session and `siaDelivery="hybrid"`. The Studio plays videos this way when it is built with a viewer identity. |

The player reports the mode it ends up using through `onDeliveryChange` with `sia`, `hybrid` or `gateway`. Props and callbacks are listed on the [player reference](/developers/reference/player); enabling a viewer identity for your server is on [Stream from Sia in the browser](/self-hosting/direct-playback).

```mermaid
flowchart LR
  Player[Browser player]
  subgraph Server[Your Sluby server]
    Nginx[nginx web container]
    Gateway[Backend: gateway and API routes]
  end
  DB[(PostgreSQL)]
  Sia[Sia indexer and hosts]

  Player -- "gateway and hybrid: /v1/stream, /v1/objects" --> Nginx
  Player -- "direct and hybrid: share map from /v1/share or /api/v1/playback/{id}/share" --> Nginx
  Nginx --> Gateway
  Gateway -- "who owns the object, tier, signing state" --> DB
  Gateway -- "object reads, share URL minting" --> Sia
  Player -- "direct and hybrid: byte ranges with sia:// share URLs" --> Sia
```

### Gateway [#gateway]

The gateway is the set of unauthenticated `/v1/` routes on the backend, behind the nginx web container. It needs no API key, so a plain `<video>` element or hls.js can play a public video.

Every request to `GET /v1/objects/{objectId}` first settles access from the asset that owns the object:

- An id that is not 64 lowercase hex characters gets `400`.
- An object that no live asset claims, or whose asset is being deleted, gets `404` with `Object not found`.
- An object of a public asset is served.
- An object of a private asset needs a valid signed URL (see [Signed URLs](#signed-urls)), or the gateway answers `403` with `This object requires a valid signed URL` and a `reason`.
- When the database cannot be read, the answer is `503` with `Delivery is unavailable right now; try again`, so the gateway never serves or refuses on a guess.

Then it sends the bytes by request shape:

- **Range request** (`bytes=N-M`, `bytes=N-` or `bytes=-N`): the gateway looks the object up once and downloads only the part of the object the range covers from the Sia hosts, streaming it to the player as it arrives, with `206`. HLS players send a range for every segment, so this is the media path. A range that starts past the end gets `416`. The gateway ignores a multi-range or malformed header and sends the whole object.
- **Whole object** (no usable `Range`): an object of up to 8 MB (playlists, thumbnails) is read once into an in-memory cache and served from there. A larger object streams from Sia without being kept.
- **HEAD**: the whole-object path without a body.

A failure on the Sia side returns `502` with `The Sia network did not answer; try again`, and an object the indexer no longer has returns `404`. The optional `type` query (`?type=manifest` on playback URLs) sets the `Content-Type` of the answer.

`GET /v1/stream/{id}/master.m3u8` serves a video's master playlist by asset id or playback id, so you can build a playback URL without knowing any object id. Its access rules are in [Playback ids](#playback-ids).

The gateway answers requests from any origin, without credentials, so you can embed a player on any site. The exact CORS headers are on [API conventions](/developers/reference/api-conventions#cors).

Endpoint details: [`GET /v1/objects/{objectId}`](/developers/reference/api/delivery/get-objects-objectid), [`GET /v1/stream/{id}/master.m3u8`](/developers/reference/api/delivery/get-stream-videoassetid-master-m3u8).

### Direct from Sia [#direct-from-sia]

In direct mode, `@sluby/player` replaces hls.js's HTTP loader with one that fetches every playlist and segment from Sia through the SDK's Sia session. The backend is not in the byte path. It only hands out the share map (see [Share URLs](#share-urls)).

1. The browser connects to the indexer with a viewer app key. This is a separate Sia app identity from the one the backend uploads with, created with the `provision-viewer` script and given to the SDK as `SlubyConfig.sia` (`indexerUrl`, `appId`, `appKey`). The Sia SDK runs in the browser as WebAssembly and loads on first use.
2. The player fetches the asset's share map: one `sia://` share URL per object, plus the id of the master playlist object.
3. For each request hls.js makes, the loader takes the object id out of the `/v1/objects/{objectId}` path, resolves that object from its share URL, and downloads the requested byte range straight from the hosts.

The player prepares the session before playback starts. If the connection or the share map fails, the player logs `Sluby: direct-from-Sia delivery unavailable, using the gateway.` and plays the video through the gateway. Safari's native HLS path cannot use a custom loader, so it always plays through the gateway.

A failed Sia read reaches hls.js as status `502`, which hls.js retries. A refused share map or signature keeps its own 4xx status, which hls.js does not retry.

### Hybrid [#hybrid]

Hybrid mode starts as fast as the gateway and still takes most bytes from Sia. The player plays through the gateway at once and connects to Sia while the video plays. For each request:

- Playlists always come from the gateway.
- A media segment comes from Sia only when all of these hold: no other Sia read is running, Sia is not paused, the hosts of that object have already answered a one-byte warm-up read, and the buffer holds at least `minBufferSec` seconds ahead of the playhead. Otherwise (the start, a seek, a nearly empty buffer, Sia still connecting) the segment comes from the gateway.
- A Sia read gets a time budget of `maxSiaWaitMs`, or the buffered seconds minus `safetyMarginSec`, whichever is smaller. The player cancels a read that fails or runs past its budget and fetches the same segment from the gateway, so playback does not wait on a slow host.
- After `maxFailures` failures in a row, the player pauses Sia for `pauseMs`. A failed session start also pauses Sia for `pauseMs`, and the player retries the start after that.

The defaults of these policy fields are in the [player reference](/developers/reference/player#hybrid-types). You can override any field with the player's `hybridPolicy` prop. The player reports how many bytes and segments came from each side, and how many segments fell back to the gateway, through `onDeliveryStats`.

## Access tiers [#access-tiers]

Every asset is `public` or `private`, and this tier alone decides how the gateway serves its objects.

- **Public**: anyone with an object URL or the master URL can play it, without a key or signature.
- **Private**: every object URL needs a valid signature. The unsigned `playback_url` that `GET /api/v1/playback/{id}` returns for a private asset is refused by the gateway, so `@sluby/player` asks for a signed URL on its own when it sees `access_tier: "private"`.

You change the tier with [`PATCH /api/v1/assets/{id}`](/developers/reference/api/assets/patch-assets-id). A change of tier also revokes every signed URL of the asset, but not share URLs already handed out (see [Revocation](#revocation)).

## Signed URLs [#signed-urls]

A signed URL is a gateway URL with `expires` and `sig` query values that grants access to one object until a time.

### Minting [#minting]

[`GET /api/v1/playback/{id}/signed`](/developers/reference/api/playback/get-playback-id-signed) takes an asset id or a playback id and returns:

- `signed_url`: the master playlist as `{PUBLIC_URL}/v1/objects/{manifestObjectId}?type=manifest&expires=...&sig=...`
- `poster_url`: the first thumbnail, signed the same way, or `null`
- `expires_at`: when both stop working

The asset must have finished processing; otherwise the answer is `409` with `Video is not ready for playback`.

### Lifetime [#signed-url-lifetime]

|                      | Seconds             |
| -------------------- | ------------------- |
| Default `expires_in` | `3600` (one hour)   |
| Minimum              | `60`                |
| Maximum              | `21600` (six hours) |

The backend clamps an `expires_in` outside the range to it. It refuses a value that is not a whole number of seconds with `400` and `expires_in must be a whole number of seconds`. The gateway also refuses any URL whose expiry lies more than six hours ahead, whatever minted it, so no signed URL outlives the cap.

For a video longer than the lifetime, `@sluby/player` renews a URL it signed itself before it expires. For a URL you sign on your server, you pass a renewal callback. See [Serve private videos](/developers/guides/private-videos).

### How the signature works [#how-the-signature-works]

The signature is an HMAC-SHA256 over the object id, the expiry and the asset's signing generation, with a key derived from `SESSION_SECRET` for URL signing alone. So a signature:

- works for one object only, and its expiry cannot be extended;
- stops working when the asset's signing generation changes;
- stops working for every asset if you change `SESSION_SECRET` ([configuration](/self-hosting/configuration#session_secret)).

The gateway checks the signature before it looks at the expiry. A request without `expires` or `sig` fails with `reason: "missing"`, a wrong signature with `"invalid"`, and a good signature past its time with `"expired"`. So an attacker cannot use the error to learn which object ids exist.

### One signed link for the whole video [#one-signed-link-for-the-whole-video]

A signed URL covers only its own object, but a video is many objects. When the gateway serves a private playlist through a valid signed URL, it signs every `/v1/objects/...` URL inside the playlist body with the same expiry before sending it. The rendition playlists are then signed again the same way when they load. One signed master URL therefore unlocks the whole video until its expiry, and nothing longer.

The gateway checks the signature against the master playlist object, so the same `expires` and `sig` pair also opens `/v1/stream/{id}/master.m3u8`, `/v1/share/{id}` and `/watch/{id}` for that video.

### Revocation [#revocation]

[`POST /api/v1/playback/{id}/signed/revoke`](/developers/reference/api/playback/post-playback-id-signed-revoke) raises the asset's signing generation by one and returns `{ "success": true, "signing_generation": N }`. Every signed URL minted before stops verifying, and you can mint new ones right after. A `PATCH` that changes the tier raises the generation in the same database statement as the change.

The backend drops its cached copy of the asset's access state at once, so the next request sees the change. If you run more than one backend process, the others read the new state within a minute, when their cached copy expires. When a public asset becomes private, nginx can still serve its playlists and thumbnails from its cache for up to 60 seconds (see [Caching](#caching)).

Revocation and a tier change do not reach `sia://` share URLs that were already minted: the Sia SDK has no call that revokes a share URL, so each one keeps working until its own `expires_at`. That bound depends on the tier at the moment the map was minted:

- A map minted while the asset was private expires at most one hour after minting.
- A map minted while the asset was public expires at most six hours after minting. Making the asset private afterwards does not shorten it, so its share URLs can keep reading the objects from Sia for up to six hours after the switch.

Maps minted after the switch get the private one-hour cap. The [Share URL lifetime](#share-url-lifetime) table lists every bound.

## Share URLs [#share-urls]

Direct and hybrid playback need a **share map**: a `sia://` share URL for every object of the asset, the `master_object_id`, and `expires_at`. A share URL works for anyone who holds it until it expires, so the backend mints share URLs per playback with a short lifetime and never writes them into the stored playlists.

You get a share map from one of two routes:

| Route                                                                                         | Authentication            | Gated when                                                                |
| --------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
| [`GET /api/v1/playback/{id}/share`](/developers/reference/api/playback/get-playback-id-share) | API key or Studio session | the asset is private                                                      |
| [`GET /v1/share/{id}`](/developers/reference/api/delivery/get-share-id)                       | none                      | the asset is private, or `{id}` is a playback id with the `signed` policy |

On both routes, a gated map gets the shorter maximum lifetime in the table below. On the public route, a gated map also needs the `expires` and `sig` of the video's signed master URL, and its share URLs never outlive that signature. The SDK builds this URL for you from the playback URL you play, so a page with no API key can play straight from Sia.

### Share URL lifetime [#share-url-lifetime]

|                       | Seconds |
| --------------------- | ------- |
| Default `expires_in`  | `3600`  |
| Minimum               | `60`    |
| Maximum, public asset | `21600` |
| Maximum, gated        | `3600`  |

The backend rounds the expiry up to a five-minute grid, and never past the maximum or the signature's own expiry. Callers asking for roughly the same lifetime get the same map. Each backend process keeps up to 5000 maps in memory, each until it expires. Minting a map costs one indexer lookup per object, so a repeat request in the same five-minute slot gets the kept map instead of a new mint.

When the SDK needs a map within one minute of its expiry, it fetches a new one; on the public route it marks that request with `renew=1`. If a share URL fails near the end of its life, or an object is missing from the map, the SDK fetches the map again once and retries.

Share maps from `/v1/share/{id}` carry `Cache-Control: no-store` (`private, no-store` when gated). The authenticated route sends `Cache-Control: private, no-store` for a private asset. Minting failures return `502` with `The Sia indexer did not answer while minting share URLs; try again`, or `503` when the database did not answer.

## Playback ids [#playback-ids]

A playback id is a public handle for an asset of the form `pb_` followed by 21 URL-safe characters. You can hand one out instead of the asset id, give one asset several, and delete one to cut off the links that use it without touching the asset.

Each playback id has a `policy` of `public` (the default) or `signed`, and an optional `name`. You manage them with [`POST /api/v1/assets/{id}/playback-ids`](/developers/reference/api/playback/post-assets-id-playback-ids), [`GET /api/v1/assets/{id}/playback-ids`](/developers/reference/api/playback/get-assets-id-playback-ids) and [`DELETE /api/v1/playback-ids/{playbackId}`](/developers/reference/api/playback/delete-playback-ids-playbackid).

A playback id works wherever an asset id does on these routes: `/v1/stream/{id}/master.m3u8`, `/v1/share/{id}`, `/watch/{id}` and the `/api/v1/playback/{id}` routes. On the three public routes:

- The entry point needs a signature when the asset is private, or when the playback id's policy is `signed`, even on a public asset.
- A deleted playback id answers `404` at once; the gateway looks the id up on every request.

A playback id gates only its entry points. The objects themselves follow the asset's tier, so the objects of a public asset stay reachable by their `/v1/objects/{objectId}` URLs whatever playback ids point at it. To keep the bytes behind signatures, make the asset private.

## The watch page [#the-watch-page]

`GET /watch/{id}` is a public HTML page that plays one video, by asset id or playback id. You can send it as a link or embed it in an `<iframe>` on any site. It plays `/v1/stream/{id}/master.m3u8` through the gateway with hls.js served from your Sluby server (or the browser's own HLS where hls.js cannot run), so it loads nothing from a CDN.

- **Public video**: the page needs nothing, carries Open Graph tags (title, URL, and the poster when the video has one) for link previews, and is sent with `Cache-Control: no-cache`, so making the video private or deleting it takes effect on the next load.
- **Private video or signed playback id**: the page needs the `expires` and `sig` of the video's signed master URL, as `/watch/{id}?expires=...&sig=...`. It passes them on to the stream and signs the poster with the same expiry. The page is sent with `Cache-Control: private, no-store` and `noindex`, and has no Open Graph tags.

The page takes the query options `autoplay`, `muted` and `loop`; [Change how the embed plays](/studio/share#change-how-the-embed-plays) describes each.

What a viewer sees when the page cannot play:

| Situation                                            | Status | Heading                             |
| ---------------------------------------------------- | ------ | ----------------------------------- |
| Unknown id, deleted video, or no master playlist yet | `404`  | This video is not available         |
| Signed link past its expiry                          | `403`  | This link has expired               |
| Missing or wrong signature                           | `403`  | This video needs a signed link      |
| Database unavailable                                 | `503`  | This video is unavailable right now |

The page's Content Security Policy loads scripts, styles, images and media only from its own origin (plus `data:` images and `blob:` media and workers, which hls.js uses) and sets `frame-ancestors *`, so any site can frame it.

## Caching [#caching]

Sia objects never change under their id, so every layer can keep bytes, but every layer re-checks access before reuse.

### Browsers and CDNs [#browsers-and-cdns]

- Public responses carry `Cache-Control: public, no-cache` and a strong `ETag` (the object id). A client must revalidate before reusing a copy, and the gateway answers `304` only after checking access again.
- Responses for private assets, and signed responses from `/v1/stream`, carry `Cache-Control: no-store`.
- Error responses carry `Cache-Control: no-store`.

### nginx [#nginx]

The web container keeps small public whole objects (rendition playlists and thumbnails) for 60 seconds, because the gateway marks exactly those with `X-Accel-Expires: 60`. After that it revalidates, and the gateway answers `304` only while the object is still public. So making an asset private, revoking, or deleting reaches every viewer within that minute. nginx never serves a stale copy in place of an answer, even when the backend is down.

nginx never stores:

- range requests (the media data) and objects larger than 8 MB, which stream through;
- signed requests (any request with `sig`);
- master playlists and share maps, so each player load reaches the backend and is counted.

For objects, the cache key is the method, the path and the `type` query value, so adding random query values cannot force misses. The cache lives in the `nginx-cache` volume, up to 10 GB, and drops entries not used for 24 hours.

### Backend memory [#backend-memory]

- The backend keeps whole objects up to 8 MB in an in-memory LRU cache whose size `CACHE_MAX_SIZE_MB` sets ([configuration](/self-hosting/configuration#cache_max_size_mb)). Master playlists for `/v1/stream` sit in a separate cache of up to 1000 entries and 32 MB, so object reads cannot evict them.
- When a video finishes processing, the backend loads its master playlist, rendition playlists and thumbnails into these caches, so the first play comes from memory.
- When an asset is deleted, the backend evicts its objects.
- The backend answers range requests for an object already in memory from memory.
- The backend keeps which asset owns an object for five minutes, and an asset's tier and signing state for at most one minute. It drops the tier and signing state at once on a tier change, a revoke or a delete made through the same process.

[`GET /v1/cache/stats`](/developers/reference/api/ops/get-cache-stats) reports the in-memory cache's size, item counts, hits and misses. Object and master playlist responses carry an `X-Cache-Status` header; through nginx it is nginx's own cache status.

## Play counting [#play-counting]

A play is one player load of a video. The backend counts:

- a `200` for the master playlist at `/v1/stream/{id}/master.m3u8`, or for the master object at `/v1/objects/{objectId}` (where signed URLs point);
- a share map from `/v1/share/{id}`, since direct-from-Sia players never fetch the master from the gateway.

It does not count `HEAD`, `304` or range requests, refused or failed requests, share map refreshes marked `renew=1`, share maps from the authenticated `/api/v1/playback/{id}/share` route, or requests whose `Referer` is a `/studio` page of the same server (Studio previews). The same viewer loading the same video again within 30 minutes counts once. A viewer is a hash of the client address and user agent, so the backend never stores raw addresses. It buffers counts in memory and writes them to the database every 10 seconds.

## Related pages [#related-pages]

<Cards>
  <Card title="Serve private videos" href="/developers/guides/private-videos" />
  <Card title="Play videos in React" href="/developers/guides/play-react" />
  <Card title="Stream from Sia in the browser" href="/self-hosting/direct-playback" />
  <Card title="Storage on Sia" href="/developers/concepts/storage-on-sia" />
</Cards>


# Security model (/developers/concepts/security)

This page explains how a Sluby server decides who can do what: which routes are public, how API keys and Studio sessions are checked and stored, what `SESSION_SECRET` protects, what the server refuses to run with in production, and the guarantees behind signed URLs, CORS, webhook signing and logging.

## What is public without authentication [#public-routes]

These routes answer without an API key or a session:

| Route                                          | What it gives out                                                                                                                                                             |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /health`                                  | Liveness of the backend                                                                                                                                                       |
| `GET /v1/objects/{objectId}`                   | Objects of public assets; objects of private assets only with a valid signed URL                                                                                              |
| `GET /v1/stream/{id}/master.m3u8`              | The master playlist of a public video; a private video or a playback id with the `signed` policy needs a signed URL                                                           |
| `GET /v1/share/{id}`                           | The `sia://` share map of a video, gated like `/v1/stream`                                                                                                                    |
| `GET /watch/{id}`                              | The watch page, gated like `/v1/stream`                                                                                                                                       |
| `GET /v1/cache/stats`                          | The delivery cache's size and hit counts                                                                                                                                      |
| `/api/v1/auth/...`                             | The sign-in, setup and invite routes, so a browser can get a session. The routes that list or end your sessions and change your password check the session cookie themselves. |
| `GET /api/v1/openapi.json`, `GET /api/v1/docs` | The API description and its reference page                                                                                                                                    |

Everything else under `/api/v1` needs a Studio session or an API key, and tus uploads authenticate the same way. How each gated delivery route decides is on [Playback and delivery](/developers/concepts/playback).

The backend also serves Prometheus metrics at `GET /metrics`. When `METRICS_TOKEN` is set ([configuration](/self-hosting/configuration#metrics_token)), the route needs `Authorization: Bearer <token>` and answers `401` with `Metrics token required` otherwise; the server compares the token in constant time. The shipped nginx does not proxy `/metrics`, and the Compose files publish no backend port, so only containers on the Compose network reach it. The JSON metrics at `GET /api/v1/metrics` are for admins only.

## How a request is authenticated [#authentication]

Every other request under `/api/v1`, and every tus upload request, must carry a Studio session cookie or an API key in `Authorization: Bearer <key>`. A session cookie wins when a request carries both. Admin-only routes then check the caller's role, and each route checks for the scope it needs. The order of these checks, the roles and how a key takes its creator's role are on [Accounts, roles and sessions](/developers/concepts/accounts-and-roles#callers). The scopes and what each allows are on [API conventions](/developers/reference/api-conventions#scopes).

## API keys [#api-keys]

- The server keeps only a SHA-256 hash of each key and its first 12 characters, so you can tell keys apart in a list. The raw key appears once, in the response that creates or rotates it, and nobody can read it back, including from a copy of the database. The key format is on [API conventions](/developers/reference/api-conventions#api-keys).
- A key never acts beyond its creator's current role, so removing a member stops their keys on the next request ([details](/developers/concepts/accounts-and-roles#callers)).
- [Rotating a key](/developers/reference/api/keys/post-keys-id-rotate) issues a new secret with the same name, scopes and rate limit. The old key stops at once, or after a grace period of up to one week.
- The server remembers the hash of every `BOOTSTRAP_API_KEY` it has seeded and never seeds the same key again. A bootstrap key you deleted or rotated away stays gone across restarts, even while the variable is still set ([configuration](/self-hosting/configuration#bootstrap_api_key)).

## SESSION_SECRET [#session-secret]

`SESSION_SECRET` is the root of three things:

- The server signs Studio session cookies with HMAC-SHA256 under it.
- Signed playback URLs use an HMAC key derived from it for that purpose alone, so a URL signature can never pass as a cookie signature, or the other way round.
- The server derives the setup code that claims a fresh install from it.

Its default, how the server generates one outside production, and what changing it does are on [Configuration reference](/self-hosting/configuration#session_secret).

## What production refuses [#production-refusals]

With `NODE_ENV=production`, the backend runs startup checks and refuses to start with an unsafe configuration, such as a weak `SESSION_SECRET` or sign-in turned off. [`NODE_ENV`](/self-hosting/configuration#node_env) lists the checks, and [Troubleshooting](/self-hosting/troubleshooting#the-backend-refuses-to-start) quotes each message with its fix.

The production Compose file sets `NODE_ENV=production` and `AUTH_DISABLED=false`, and requires `SESSION_SECRET`. See [Run in production](/self-hosting/production). [`AUTH_DISABLED`](/self-hosting/configuration#auth_disabled) is for local development only: with it on, every request acts as one local admin account.

## Sessions and cookies [#cookies]

The Studio session cookie is `HttpOnly`, so page scripts cannot read it, and `SameSite=Lax` so that it rides along on the redirect back from GitHub sign-in. Its value is signed, but a valid signature alone is not enough: on every request the server also checks that the session row is still live and that the account has not been removed, which is what makes signing out and removing a member take effect at once. The cookie's attributes are on [API conventions](/developers/reference/api-conventions#session-cookie), and how sessions start and end is on [Accounts, roles and sessions](/developers/concepts/accounts-and-roles#sessions).

The shipped nginx sends the Studio page with `Cache-Control: no-store`, so Back after signing out does not show the signed-in Studio from the browser's cache.

## Passwords, setup code and links [#sign-in-secrets]

- **Passwords**: the server stores only scrypt hashes. A sign-in with an unknown email still runs a full hash, so response time does not reveal which emails exist.
- **The setup code**: the server derives it from `SESSION_SECRET` and, while sign-in is on and the install has no admin, writes it to its log at startup. Only someone who can read the server's logs or its secret can claim a fresh install.
- **Invite and reset links**: each carries a random token, and the server stores only the token's SHA-256 hash, so the database alone cannot be used to join or take over an account. A reset link works once. An invite link lets in as many people as the admin chose. Both expire.

The parameters behind each of these are on [Accounts, roles and sessions](/developers/concepts/accounts-and-roles#sign-in-methods). Sign-in, setup and link attempts have their own per-address and per-email limits, listed on [API conventions](/developers/reference/api-conventions#rate-limits).

## CORS and cross-origin writes [#cors]

The API trusts the session cookie only from the origins you list in `CORS_ORIGIN` ([configuration](/self-hosting/configuration#cors_origin)). A page on any other origin can call the API with a bearer key, but its requests never carry the session cookie. While `AUTH_DISABLED` is on, unlisted origins get no CORS headers at all, so other pages cannot read responses made as the local admin account.

CORS only decides who can read a response, so the API also refuses writes that a page on another origin could send without a preflight and that rely on the cookie alone. The exact rules for both are on [API conventions](/developers/reference/api-conventions#cors) and [Cross-origin writes](/developers/reference/api-conventions#cross-origin-writes).

The production Compose file sets `CORS_ORIGIN` to `https://` plus your domain, so only the Studio's own origin rides the cookie.

The delivery routes (`/v1/objects`, `/v1/stream`, `/v1/share`) answer any origin without credentials, because players on other sites fetch them.

## Signed URLs [#signed-urls]

A signed URL grants access to one object until one time, and nothing else:

- The signature covers the object id, the expiry and the asset's signing generation, so nobody can move it to another object or extend it.
- The gateway refuses any URL whose expiry lies further ahead than the maximum lifetime, whatever minted it ([Lifetime](/developers/concepts/playback#signed-url-lifetime)).
- Revoking, or changing the asset's tier, raises the signing generation and stops every URL signed before.
- nginx never stores a request that carries a signature, and responses for private assets carry `Cache-Control: no-store`.

The lifetimes, the revocation steps and what a revoke does not reach are on [Playback and delivery](/developers/concepts/playback#signed-urls).

## Webhook signing and egress [#webhooks]

Each webhook endpoint has its own signing secret, and every delivery carries a timestamped HMAC-SHA256 signature of its body, so a receiver can check that a request came from your server and refuse replayed requests. The headers, the scheme and secret rotation are on [Webhook events](/developers/reference/webhook-events#signature-scheme).

API callers choose the receiver URLs, so the server checks every address a receiver's host resolves to, refuses private and other non-public addresses, and connects only to the addresses it checked. It never follows redirects and never reads the response body. The refused ranges are on [Webhook events](/developers/reference/webhook-events#receiver-addresses); to allow receivers on your own network, set [`WEBHOOK_ALLOWED_NETWORKS`](/self-hosting/configuration#webhook_allowed_networks).

## Rate limits [#rate-limits]

Requests are limited at two layers:

- **nginx** limits each client address on the delivery routes (`/v1/`) and the sign-in routes (`/api/v1/auth/`), and answers `429` over the limit.
- **The backend** limits unauthenticated `/api/v1` requests per client address, and authenticated requests per API key or Studio session.

The numbers, headers and `429` body are on [API conventions](/developers/reference/api-conventions#rate-limits).

## Logs and error responses [#logs-and-errors]

- The backend logs request URLs with every query value replaced by `[redacted]`, except a fixed list of keys that carry no secret, such as `limit`, `cursor` and `expires`. URL signatures (`sig`) and the OAuth `code` and `state` never reach the backend's logs, and it redacts invite and reset tokens in paths too. The access log of the shipped nginx records each full request line, query string included.
- Play counts store a hash of the viewer's address and user agent, not the address.
- An unexpected server error answers `500` with `Internal Server Error` and no internal detail. Only with [`EXPOSE_ERROR_STACKS`](/self-hosting/configuration#expose_error_stacks) on do error responses carry messages and stack traces. The error format is on [API conventions](/developers/reference/api-conventions#errors).

## Response headers [#headers]

The shipped nginx sends `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin` on the Studio and API, and hides its version. The Studio page carries a Content Security Policy with `frame-ancestors 'none'`. The delivery routes and the watch page set their own headers instead, because other sites load and frame them: the watch page's policy sets `frame-ancestors *` and loads scripts, styles and media only from its own origin.

## Sia credentials [#sia-credentials]

The backend uploads to Sia with the app key in `SIA_APP_KEY` ([configuration](/self-hosting/configuration#sia_app_key)), which stays on the server. Direct playback in the browser uses a separate viewer identity, made with the `provision-viewer` script and built into the Studio as `VITE_SLUBY_SIA_*` values. See [Stream from Sia in the browser](/self-hosting/direct-playback).


# Storage on Sia (/developers/concepts/storage-on-sia)

A ready Sluby video lives on the Sia network: its renditions, playlists and thumbnails are Sia objects, and the backend removes its local copies once the video is ready. This page explains the Sia terms Sluby uses, which objects make up one video, how redundant they are, how Sluby makes sure every pinned object is on record, and what each field of the per-video storage breakdown means. For the steps that produce these objects, see [Upload pipeline](/developers/concepts/upload-pipeline).

## Sia terms [#sia-terms]

| Term                     | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host                     | A storage provider on the Sia network. Hosts store encrypted shards and serve them back.                                                                                                                                                                                                                                                                                                                                        |
| Indexer                  | The service between an app and the hosts. It keeps the record of each object (which slabs and shards make it up and which hosts hold them), watches slab health and coordinates repairs. Sluby connects to an indexer with its app key through the official `@siafoundation/sia-storage` SDK, for example the hosted indexer at `https://sia.storage` or a self-hosted `indexd`. The SDK uploads each shard straight to a host. |
| Object                   | One stored file, such as a rendition's data file or a playlist.                                                                                                                                                                                                                                                                                                                                                                 |
| Object id                | The id of an object, which the SDK returns when an upload finishes. Sluby stores object ids in its database, and playlists name objects by id.                                                                                                                                                                                                                                                                                  |
| Slab                     | A contiguous erasure-coded segment of data. An object's data lives in one or more slabs, and several small objects can share one slab.                                                                                                                                                                                                                                                                                          |
| Data shard, parity shard | Erasure coding splits a slab into data shards and adds parity shards. Any set of shards as large as the number of data shards rebuilds the slab, so the slab survives the loss of as many shards as it has parity shards.                                                                                                                                                                                                       |
| Sector                   | What one host stores for one shard of a slab. Sluby counts every sector as 4 MiB.                                                                                                                                                                                                                                                                                                                                               |
| Pin                      | Telling the indexer to keep an object record, so the object becomes listable and eligible for repair. Unpinning (deleting) an object removes the record; its slabs stay pinned until a prune.                                                                                                                                                                                                                                   |
| Prune                    | Asking the indexer to unpin every slab of the account that no object uses.                                                                                                                                                                                                                                                                                                                                                      |

The app key and the indexer URL come from the indexer connection. [Connect Sia storage](/self-hosting/sia-storage) shows how to set it up.

## What one video stores [#what-one-video-stores]

Each ready video is a small set of Sia objects. For a video with N renditions and T thumbnails (T is 3 unless a thumbnail shot failed), Sluby stores 2N + 1 + T objects:

| Role               | Count             | Content                                                                                  |
| ------------------ | ----------------- | ---------------------------------------------------------------------------------------- |
| `rendition_data`   | one per rendition | the rendition's `data.m4s`: the fMP4 init section and every segment                      |
| `variant_playlist` | one per rendition | the rendition's HLS playlist, with byte ranges into the data object                      |
| `master_manifest`  | one               | the HLS master playlist, one entry per rendition                                         |
| `thumbnail`        | up to three       | JPEG frames of the video ([Thumbnails](/developers/concepts/upload-pipeline#thumbnails)) |

The playlists refer to other objects by path: a variant playlist names its data object as `/v1/objects/<object id>`, and the master playlist names each variant playlist the same way. A player that has the master playlist's object id can therefore find every other object of the video. [Playback and delivery](/developers/concepts/playback) explains how those paths are served.

In the database, the `artifacts` table ties every object id to its video, its role and, for rendition files, its rendition. The `renditions` table holds one row per rendition with its data and playlist object ids. [Data model](/developers/concepts/data-model) describes both tables.

## Packed uploads and shared slabs [#packed-uploads-and-shared-slabs]

On Sia, even a 1-byte upload occupies a full slab, with all of its data and parity shards. Uploading each small file on its own would cost one full slab per file. Sluby uses packed uploads instead: one upload that places several objects into shared slabs. Each object references its own byte range inside the slabs it shares.

A video takes three packed uploads, because each playlist must name the ids of the objects it points at. [Upload to Sia](/developers/concepts/upload-pipeline#upload-to-sia) lists what each one carries. The two playlist uploads each fill one slab even though the playlists are a few kilobytes. Rendition data larger than the room left in a slab spans several slabs.

## Redundancy [#redundancy]

Erasure coding turns every slab into data shards plus parity shards, and each shard goes to a different host as one sector. For a slab with `d` data shards and `p` parity shards:

| Quantity                          | Value                  |
| --------------------------------- | ---------------------- |
| Sectors per slab                  | `d + p`, one per shard |
| Data per slab                     | `d` x 4 MiB            |
| Stored per slab                   | `(d + p)` x 4 MiB      |
| Redundancy ratio                  | `(d + p) / d`          |
| Shards needed to rebuild the slab | any `d` of the `d + p` |

For example, a slab with 10 data shards and 20 parity shards holds 40 MiB of data, stores 120 MiB on 30 hosts, has a redundancy ratio of 3, and survives the loss of any 20 of its shards.

Sluby passes a split to the SDK only when both [`SIA_DATA_SHARDS`](/self-hosting/configuration#sia_data_shards) and [`SIA_PARITY_SHARDS`](/self-hosting/configuration#sia_parity_shards) are set. With either one unset, it passes none and the SDK uses its own default. The split a stored video actually uses is in the `data_shards`, `parity_shards` and `redundancy_ratio` fields of its [storage breakdown](#totals).

## Records before pins [#records-before-pins]

A pinned object that Sluby has no record of would stay on Sia with nothing to find and unpin it. Sluby prevents this by writing every object id to its database before it pins the object, in the `pending_objects` table.

```mermaid
sequenceDiagram
  participant U as Upload stage
  participant SDK as sia-storage SDK
  participant H as Hosts
  participant DB as Postgres
  participant I as Indexer
  participant F as Finalize stage
  U->>SDK: packed upload (files)
  SDK->>H: shards of each slab
  SDK-->>U: objects with their ids
  U->>DB: insert ids into pending_objects (state uploading)
  U->>I: pin each object
  alt a pin fails
    U->>I: unpin the objects of this batch that were pinned
  end
  opt the upload stage fails or stops after recording ids
    U->>DB: mark the recorded ids release
    U->>I: unpin the ids marked release
    U->>DB: delete their pending_objects rows
  end
  Note over F,DB: one transaction
  F->>DB: write renditions and artifacts, delete the run's pending_objects rows
  F->>DB: mark replaced and leftover objects of the asset release
  F->>I: unpin objects marked release
  F->>DB: delete their pending_objects rows
```

A row in `pending_objects` is in one of two states:

| State       | Meaning                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `uploading` | A processing run recorded the object right before pinning it. Finalize can still promote it to an `artifacts` row. |
| `release`   | Nothing uses the object. Sluby unpins it and deletes the row once the unpin succeeds.                              |

What moves a row to `release`:

- A failed or stopped upload marks the objects it pinned.
- Finalize marks objects the video referenced before and no longer does, and any other `uploading` object of the same video (left by an earlier attempt or a duplicate execution).
- The deletion GC sweep marks `uploading` objects whose video is gone, being deleted, or no longer `processing`.

An object that an `artifacts` row still names is never unpinned from `pending_objects`, so a live video cannot lose an object this way. The `pending_objects` table has no foreign key to the video on purpose: its rows outlive a deleted video, because an upload can still pin after the video row is gone. The deletion sweep unpins what is left. [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation) covers that sweep.

## Slab pruning [#slab-pruning]

The indexer pins slabs separately from the objects that use them. Unpinning an object leaves its slabs pinned until a prune: a request that makes the indexer unpin every slab of the account that no pinned object uses. Sluby requests a prune after a failed upload, after a stopped upload releases the objects it pinned, and after it deletes a video's objects.

Sluby pins the objects of a packed upload only after the whole upload has finished, so while an upload runs, its stored slabs have no pinned object. A prune at that moment would unpin them. Sluby keeps prunes and uploads apart across every backend process that shares the Sia account:

- Each upload holds a lease in Redis and renews it every 15 seconds.
- A prune runs only when no upload lease is live anywhere. Otherwise it is marked as wanted and runs when the last upload ends.
- Uploads wait while a prune runs.
- Right before it pins, an upload checks its lease. A lease lapses only when the process stalls longer than the lease lifetime. If it lapsed and no prune ran in the meantime, the upload takes the lease back and continues. If a prune ran or is running, the upload pins nothing and fails, and the pipeline retries it.

Leases expire after four renewal intervals, so a process that dies while holding one blocks the others for at most that long.

## Storage breakdown [#storage-breakdown]

[`GET /api/v1/assets/{id}/sia`](/developers/reference/api/storage/get-assets-id-sia) returns what the indexer reports about every object of one video, with totals. It needs the `read` [scope](/developers/reference/api-conventions#scopes). The Studio shows the same data on a video's page ([See how a video is stored on Sia](/studio/storage)).

The backend lists the video's objects from the `artifacts` table. For a video stored before that table existed, it falls back to the object ids on the video row, where a playlist and a data file cannot be told apart, so their `role` is `null`.

### Objects [#objects]

Each entry of `objects`:

| Field               | Meaning                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `object_id`         | the Sia object id                                                                                                               |
| `role`              | `master_manifest`, `variant_playlist`, `rendition_data`, `thumbnail`, or `null` for an object stored before roles were recorded |
| `rendition`         | the rendition name, such as `720p`, for playlists and data files; `null` otherwise                                              |
| `size`              | the object's size in bytes, before erasure coding                                                                               |
| `encoded_size`      | the encoded size the indexer reports for the object, after erasure coding                                                       |
| `slab_count`        | slabs that hold part of the object                                                                                              |
| `sector_count`      | sectors of those slabs                                                                                                          |
| `shared_slab_count` | slabs the object shares with another object of the same video                                                                   |
| `host_count`        | distinct hosts that store a sector of the object                                                                                |
| `created_at`        | when the indexer created the object                                                                                             |

`unavailable_object_ids` lists objects the indexer could not describe at that moment. They are listed instead of dropped.

### Totals [#totals]

Totals count each slab once, even when several objects of the video share it. The slab's identity is its list of sector roots.

| Field                          | Meaning                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `object_count`                 | objects of the video                                                         |
| `raw_bytes`                    | sum of the object sizes, before erasure coding                               |
| `encoded_bytes`                | bytes the video occupies on hosts: every unique sector, 4 MiB each           |
| `sector_bytes`                 | the same number as `encoded_bytes`, kept for older clients                   |
| `unique_slab_count`            | distinct slabs                                                               |
| `unique_sector_count`          | distinct sectors                                                             |
| `data_shards`, `parity_shards` | the shard split of the video's slabs; `null` when slabs use different splits |
| `redundancy_ratio`             | total shards divided by data shards; `null` when slabs use different splits  |
| `host_count`                   | distinct hosts storing a sector of the video                                 |
| `country_count`                | distinct countries of those hosts                                            |

`encoded_bytes` comes from the unique sectors of the video, not from adding up the per-object `encoded_size` values, so the two do not have to match.

### Hosts, countries and the indexer [#hosts-countries-and-the-indexer]

| Field                | Meaning                                                                                                                                                                                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hosts[]`            | one entry per host: `public_key`, `sectors` (sectors of this video it stores), `country_code`, `latitude`, `longitude`, `good_for_upload`, sorted by sector count. `country_code`, `latitude`, `longitude` and `good_for_upload` are `null` for a host missing from the indexer's host list. |
| `countries[]`        | one entry per country: `country_code`, `hosts`, `sectors`                                                                                                                                                                                                                                    |
| `contracts`          | ids of active file contracts with the hosts that store the video, from a self-hosted `indexd` admin API; `null` when no admin API is configured                                                                                                                                              |
| `indexer`            | the indexer `url`, the `network`, and the `wallet_address` behind a self-hosted `indexd` (`null` when no admin API is configured or the lookup fails)                                                                                                                                        |
| `manifest_object_id` | the master playlist's object id                                                                                                                                                                                                                                                              |

The admin API counts as configured when [`SIA_ADMIN_PASSWORD`](/self-hosting/configuration#sia_admin_password) is set, and the backend calls it at [`SIA_ADMIN_URL`](/self-hosting/configuration#sia_admin_url).

### Caching [#caching]

A breakdown asks the indexer about every object of the video, so the backend caches a complete answer per video for 30 seconds and the host list for 5 minutes. An answer with unavailable objects is not cached, so the next request asks again.

## Related pages [#related-pages]

- [Upload pipeline](/developers/concepts/upload-pipeline): how the objects are produced and uploaded.
- [Playback and delivery](/developers/concepts/playback): how the objects reach a player.
- [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation): how objects are unpinned and how Sluby checks its records against the indexer.


# Upload pipeline (/developers/concepts/upload-pipeline)

This page explains what the Sluby backend does with a video from the first uploaded byte until the video is ready to play: the tus upload, the three queued stages (transcode, Sia upload, finalize), the rendition ladder and segment format FFmpeg produces, how the output goes to Sia in packed uploads, and how failures retry. For the client side of an upload, see [Upload videos from your app](/developers/guides/upload).

## Stages at a glance [#stages-at-a-glance]

Every video passes through one upload and three queued stages. The queues are BullMQ queues in Redis, and the workers that run them live in the backend process. Each backend process runs up to 2 transcode jobs, 4 Sia upload jobs and 4 finalize jobs at the same time.

```mermaid
flowchart LR
  A["tus upload<br/>POST, PATCH /api/v1/uploads"] -->|"upload finished,<br/>SHA-256 computed"| B["transcode queue<br/>FFmpeg + thumbnails"]
  B -->|"upload-segments job"| C["upload-segments queue<br/>packed uploads to Sia"]
  C -->|"finalize job"| D["finalize queue<br/>records + ready"]
  D --> E["asset ready"]
  B -. "final failure" .-> F["asset failed"]
  C -. "final failure" .-> F
  D -. "final failure" .-> F
  F -->|"POST /api/v1/assets/{id}/retry"| B
  F -->|"POST /api/v1/assets/{id}/retry<br/>(transcode already finished)"| C
```

| Stage         | What it does                                                                                 | Progress written to the processing job                           |
| ------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Upload        | tus receives the file into `UPLOAD_DIR`, then the backend hashes it and queues the transcode | not part of the processing job (the upload session tracks bytes) |
| Transcode     | probes the source, runs FFmpeg into the rendition ladder, extracts thumbnails                | 0 to 60 while FFmpeg runs, then 65                               |
| Upload to Sia | uploads the data files, thumbnails and playlists in three packed uploads, pins every object  | 65 to 90                                                         |
| Finalize      | writes the storage records, marks the asset `ready`, warms the cache, removes local files    | 90, then 100                                                     |

You read the processing job (stage log, progress, retry count) with [`GET /api/v1/assets/{id}/processing`](/developers/reference/api/assets/get-assets-id-processing).

## Upload with tus [#upload-with-tus]

Uploads use the [tus resumable upload protocol](https://tus.io/protocols/resumable-upload) at `/api/v1/uploads`. A request with a `Tus-Resumable` header, or a `PATCH`, `HEAD` or `OPTIONS` request, goes to the tus server. Other requests on that path go to the REST routes for upload status ([`GET /api/v1/uploads/{id}`](/developers/reference/api/uploads/get-uploads-id)) and cancel ([`DELETE /api/v1/uploads/{id}`](/developers/reference/api/uploads/delete-uploads-id)). There is no JSON route that creates an upload: the tus creation request creates it.

When a tus creation request (`POST`) arrives, the backend:

1. Authenticates the caller with an API key or a Studio session, and refuses a caller without the `upload` [scope](/developers/reference/api-conventions#scopes) with `403`.
2. Refuses a declared file type that does not start with `video/` with `415` and an empty file with `400`.
3. Validates the title, description and access tier from the upload metadata. A missing or blank title becomes `Untitled`.
4. Creates the video asset with status `created`, and an upload session that takes the tus upload id as its own id. The id in the tus `Location` header is therefore also the id the REST status and cancel routes take.
5. Sends the `upload.started` webhook once the file store has created the upload.

The maximum upload size is [`MAX_UPLOAD_SIZE`](/self-hosting/configuration#max_upload_size). The metadata keys a client sends are described in [Upload videos from your app](/developers/guides/upload).

While bytes arrive, the first write moves the asset from `created` to `uploading`, and the session records the received byte count. When the last byte arrives, the backend:

1. Computes the SHA-256 of the file by streaming it from disk, and stores the hash on the upload session, whose status becomes `completed`.
2. Creates a processing job row with status `queued`.
3. Adds a job to the `transcode` queue under the job id `transcode-<asset id>`, so a repeated finish hook does not queue a second transcode.
4. Sends the `upload.completed` webhook.

If any of these steps fails, the asset becomes `failed`, the backend sends `upload.failed`, and tus answers the request with the error.

### Unfinished and cancelled uploads [#unfinished-and-cancelled-uploads]

An unfinished upload expires 24 hours after its creation. Once an hour, the backend removes expired incomplete uploads from disk, marks their sessions `failed`, and discards an asset that never got past `created` or `uploading`. A finished upload never expires this way, because it is the source a failed asset needs for a retry.

A tus `DELETE` on an unfinished upload, or `DELETE /api/v1/uploads/{id}`, cancels it: the session becomes `cancelled`, and the backend removes the partial file and discards the asset. A finished upload cannot be cancelled. `DELETE /api/v1/uploads/{id}` answers `409` for it, and you delete its asset instead.

## Transcode [#transcode]

The transcode worker runs two jobs at a time per backend process, and sets each FFmpeg run to half of the CPU cores (rounded down, at least one) so two transcodes share the machine. Before it starts, it checks that the asset still exists and is not `ready` or `failed`. It then sets the asset to `processing` and sends `processing.started` once per run (BullMQ retries of the same job do not send it again).

### Probe [#probe]

`ffprobe` reads the source first. The worker picks the first video stream that is not cover art, and the default audio stream (or the first one). It applies rotation and sample aspect ratio, so a portrait phone clip counts as portrait.

Both `ffprobe` and `ffmpeg` read uploads with `-protocol_whitelist file` and a fixed list of container formats (`mov`, `matroska`, `webm`, `avi`, `mpegts`, `mpeg`, `asf`, `flv`, `ogg`, `mxf`, `dv`, `rm`, `nut`, `ivf`, `h264`, `hevc`, `m4v`, `mpegvideo`). The list leaves out playlist formats such as HLS and concat, so an upload cannot make FFmpeg open other files.

A file `ffprobe` reports as `Invalid data found when processing input`, or one without a video stream (`No video stream found`), fails the video at once without retries, and the backend marks its processing job not retryable.

### Rendition ladder [#rendition-ladder]

Sluby encodes every source into a ladder of H.264 renditions. Each rung has a fixed video bitrate, a peak rate 7% above it and a buffer 1.5 times the bitrate:

| Rendition | Size (16:9 landscape) | Video bitrate | Max rate | Buffer | Audio bitrate |
| --------- | --------------------- | ------------- | -------- | ------ | ------------- |
| `2160p`   | 3840x2160             | 15000k        | 16050k   | 22500k | 192k          |
| `1440p`   | 2560x1440             | 9000k         | 9630k    | 13500k | 192k          |
| `1080p`   | 1920x1080             | 6000k         | 6420k    | 9000k  | 192k          |
| `720p`    | 1280x720              | 3500k         | 3745k    | 5250k  | 128k          |
| `540p`    | 960x540               | 1800k         | 1926k    | 2700k  | 128k          |
| `360p`    | 640x360               | 800k          | 856k     | 1200k  | 96k           |

Which rungs a video gets:

- The tallest rung is [`TRANSCODE_MAX_RENDITION`](/self-hosting/configuration#transcode_max_rendition), `1080p` when it is not set. Sluby makes `1440p` and `2160p` only when you raise it.
- Sluby makes a rung only when its height fits in the source's short side, so it does not invent taller renditions than the source has. The one exception: a source shorter than 360 pixels on its short side gets the `360p` rung alone, scaled up to it.
- Each rung keeps the source's aspect ratio, with the rung height as the short side. A portrait 1080p source becomes 1080x1920, not a pillarboxed 1920x1080. Sluby rounds sizes to even numbers.

### Encoding settings [#encoding-settings]

| Setting           | Value                                                                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Video codec       | `libx264`, profile `high`, preset `veryfast`, 8-bit 4:2:0 (`yuv420p`), square pixels                                                      |
| Keyframes         | forced every 2 seconds, scene-cut keyframes off (`-sc_threshold 0`)                                                                       |
| Audio codec       | AAC, 2 channels, 48 kHz; every rendition carries the one selected source audio stream (renditions have no audio when the source has none) |
| Interlaced frames | deinterlaced with `bwdif` (progressive frames pass through)                                                                               |
| HDR (PQ or HLG)   | tone-mapped to SDR BT.709                                                                                                                 |

When a source with audio has a container that runs on more than half a second past the end of its video stream, FFmpeg cuts the output at the end of the video, so the extra audio does not pile up in the last segment.

### Segment format [#segment-format]

FFmpeg writes HLS with fragmented MP4 (fMP4) segments, as a VOD playlist, with a target segment length of 6 seconds (`-hls_time 6`). It uses the `single_file` flag: each rendition is one data file, `data.m4s`, that holds the init section and every segment, and the rendition's playlist addresses each segment by byte range with `EXT-X-BYTERANGE`. The `independent_segments` flag adds `#EXT-X-INDEPENDENT-SEGMENTS` to each playlist.

The output of one run is:

```text
<run directory>/
  master.m3u8            master playlist, one entry per rendition
  1080p/playlist.m3u8    variant playlist, byte ranges into data.m4s
  1080p/data.m4s         init section and every segment of 1080p
  720p/...
  thumb_25.jpg           thumbnails
  thumb_50.jpg
  thumb_75.jpg
  transcode-complete.json
```

### Thumbnails [#thumbnails]

After FFmpeg, the worker grabs three JPEG frames at 25%, 50% and 75% of the video's length, each 640x360 and letterboxed to keep the aspect ratio. The worker tone-maps HDR sources for thumbnails too. The worker skips a shot that fails, so a video without thumbnails still finishes.

### Time limits [#time-limits]

| Limit                         | Value                                                                             |
| ----------------------------- | --------------------------------------------------------------------------------- |
| `ffprobe`                     | 60 seconds                                                                        |
| FFmpeg transcode, total       | 30 minutes plus 60 times the video's length (12 hours when the length is unknown) |
| FFmpeg transcode, no progress | 10 minutes                                                                        |
| Each thumbnail                | 60 seconds                                                                        |

The backend kills a run that passes a limit with `SIGKILL`, so FFmpeg cannot finish the playlists of a truncated video.

### Run directories and the completion marker [#run-directories-and-the-completion-marker]

Each execution of the transcode stage writes into its own directory, `<TRANSCODE_OUTPUT_DIR>/<asset id>/<timestamp>-<random>`. A run counts as finished only when it holds `transcode-complete.json`, which the worker writes (atomically, by rename) after FFmpeg exits with code 0 and the thumbnails are taken. When a transcode job runs again and finds a finished run, it reuses that output instead of transcoding again.

## Upload to Sia [#upload-to-sia]

The upload stage turns the finished run into Sia objects. A Sia object is one stored file, addressed by an object id; [Storage on Sia](/developers/concepts/storage-on-sia) explains objects, slabs, shards and pins.

On Sia, even a 1-byte upload occupies a full slab, so Sluby packs the files of a run into as few uploads as it can. Each playlist has to name the object ids of what it points at, which gives three dependent uploads:

1. **Media**: every rendition's `data.m4s` and every thumbnail, in one packed upload.
2. **Variant playlists**: each `playlist.m3u8` rewritten so its `EXT-X-MAP` URI and segment lines point at `/v1/objects/<data object id>`, with the byte ranges unchanged. All playlists go in one packed upload.
3. **Master playlist**: `master.m3u8` rewritten so each rendition line points at `/v1/objects/<playlist object id>`, in its own upload.

The stored playlists hold root-relative paths, so they resolve against whichever origin serves them, and the direct-from-Sia player reads the object id out of the path. [Playback and delivery](/developers/concepts/playback) explains how those paths are served.

A packed upload puts several files into shared slabs. A file larger than the room left in the current slab starts a new slab, and a large file spans several slabs. After the data is stored, the backend records every object id in the database and then pins each object. [Storage on Sia](/developers/concepts/storage-on-sia#records-before-pins) explains why the record comes first.

Before reading the run, the stage checks it: a master playlist without renditions, a variant playlist without segments or without `#EXT-X-ENDLIST`, or an empty data file stops the stage, so leftovers of a failed FFmpeg run never become a video.

Before each upload, the stage checks that the asset is still `processing`. When the asset was deleted or left processing, the stage stops and releases the objects it already pinned.

### Upload retries and stalls [#upload-retries-and-stalls]

- The media upload gets up to 5 attempts inside the stage, waiting 2, 4, 8 and 16 seconds between them.
- The stage cancels a packed upload that stores nothing for 10 minutes and fails the attempt.
- When an attempt fails, the stage releases (unpins) the objects it pinned, so a retry uploads everything again from the start.

## Finalize [#finalize]

The finalize stage writes everything in one database transaction, after locking the asset row:

- one `renditions` row per rendition (name, width, height, bitrate, segment count, data size, data and playlist object ids). Width, height and bitrate come from the `RESOLUTION` and `BANDWIDTH` that FFmpeg writes for the rendition in the master playlist, the bitrate in kbps.
- one `artifacts` row per stored object with its role: `master_manifest`, `variant_playlist`, `rendition_data` or `thumbnail`
- the asset's master manifest id, thumbnail ids, duration, resolution, segment count, stored bytes, and status `ready`
- the processing job as `completed` at 100%

In the same transaction, finalize marks for release the objects the asset referenced before and no longer does (from an earlier run), and every other object an earlier attempt or a duplicate execution recorded for the asset. When the asset was deleted, or is no longer `processing`, finalize writes nothing and unpins the run's objects instead.

After the transaction, finalize sends `asset.ready`, unpins replaced objects, loads the master playlist, the variant playlists and the thumbnails into the backend's cache so the first play comes from memory, removes the run directories, and removes the source upload from disk. These steps are best effort: the asset is `ready` either way. A repeated finalize job sends `asset.ready` again, so the event arrives at least once.

The segment count stored on the asset is the per-rendition count, not the sum over renditions, because every rendition is segmented the same way.

## Statuses [#statuses]

### Asset status [#asset-status]

| Status       | Set when                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| `created`    | the tus creation request creates the asset                                                                         |
| `uploading`  | the first bytes of the upload arrive                                                                               |
| `processing` | the transcode worker starts (the asset stays `uploading` while the job waits in the queue), or a retry is accepted |
| `ready`      | finalize commits                                                                                                   |
| `failed`     | a stage fails for good, or the upload finish step fails                                                            |

### Processing job status [#processing-job-status]

| Status       | Set when                                                                  |
| ------------ | ------------------------------------------------------------------------- |
| `queued`     | the upload finishes, or a retry restarts the job                          |
| `processing` | the transcode or upload stage starts                                      |
| `retrying`   | a stage attempt fails and BullMQ will try again (the retry count goes up) |
| `completed`  | finalize commits                                                          |
| `failed`     | a stage fails for good; `retryable` is `false` for an unreadable source   |

### Webhook events [#webhook-events]

The pipeline sends `upload.started`, `upload.completed`, `upload.failed`, `processing.started`, `asset.ready` and `asset.errored` at the points this page describes. [Webhook events](/developers/reference/webhook-events#event-types) lists when each one fires and its payload. A webhook that cannot be queued never fails the upload or a stage.

## Retries [#retries]

### Automatic retries [#automatic-retries]

Each queue retries a failed job with exponential backoff:

| Queue             | Attempts | First backoff |
| ----------------- | -------- | ------------- |
| `transcode`       | 3        | 30 seconds    |
| `upload-segments` | 3        | 30 seconds    |
| `finalize`        | 3        | 10 seconds    |

While attempts remain, the processing job shows `retrying` with the error. After the last attempt, or at once for an unreadable source, the asset becomes `failed` and the backend sends `asset.errored`.

### Manual retry [#manual-retry]

[`POST /api/v1/assets/{id}/retry`](/developers/reference/api/assets/post-assets-id-retry) restarts a `failed` asset:

- When a finished transcode run is still on disk, the retry starts at the Sia upload and does not transcode again.
- Otherwise it transcodes the source upload again, which needs the uploaded file on disk. When neither exists, the API answers `410` with `Could not retry because the original file is gone. Upload the video again.`
- An asset that is not `failed` gets `400` with `Only a failed video can be retried. It may have restarted already.` Two retries at the same time move the asset once; the second one gets this `400`.

A retry gets its own run id, so its upload and finalize jobs have job ids the failed attempt never used.

A failed asset keeps its source upload and its finished transcode output for a retry. A ready asset no longer has either.

## Duplicate executions [#duplicate-executions]

BullMQ can hand a job to a second worker when the first one stalls, for example when the host freezes for longer than the job lock (5 minutes). The pipeline makes a second execution harmless:

- Each stage queues the next one under a fixed job id (`upload-<asset id>` and `finalize-<asset id>`, with the run id appended for a retry), so a stage that runs twice starts its successor once.
- Each transcode execution writes to its own run directory. When two finish, the upload reads only the directory queued first, and the backend removes the other.
- The Sia upload of a job holds a lease in Redis, renewed every 10 seconds. A second execution waits until the lease is free, and an execution that loses its lease stops at its next checkpoint.
- Finalize checks the asset's state inside its transaction, so a stale run never replaces the objects of a ready asset.

## Related pages [#related-pages]

- [Storage on Sia](/developers/concepts/storage-on-sia): objects, slabs, shards, redundancy and the storage breakdown.
- [Playback and delivery](/developers/concepts/playback): how the stored playlists and data files reach a player.
- [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation): how deleting a video unpins its objects.


# Manage your library from a server (/developers/guides/manage-library)

`client.assets` manages the videos in your Sluby library from your server. Reading needs a key with the `read` scope; editing, retrying and deleting need the `manage` scope ([API conventions](/developers/reference/api-conventions#scopes) lists what each scope allows).

Every sample on this page runs on your server with this client:

```js title="sluby.mjs (server)"
import { SlubyClient } from '@sluby/sdk';

const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');
export const client = new SlubyClient({ baseUrl: SLUBY_URL, apiKey: SLUBY_API_KEY });
```

## List videos [#list-videos]

`client.assets.list()` returns one page of videos, newest first by default. Walk the whole library with the cursor: pass each page's `nextCursor` back as `cursor` until it is `null`.

```js title="list.mjs (server)"
import { client } from './sluby.mjs';

// every ready video, newest first, 100 at a time
/** @type {string | undefined} */
let cursor;
do {
  const page = await client.assets.list({ status: 'ready', limit: 100, cursor });
  for (const asset of page.data) console.log(asset.id, asset.title);
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

The cursor works only with the default order (`created_at`, newest first), and a request takes either `cursor` or `page`, not both. [Pagination](/developers/reference/api-conventions#pagination) lists the range and default of `limit` and the other paging rules.

## Search, filter and sort [#search-filter-and-sort]

For any other order, page by number with `page`. The response's `total` counts every match.

```js title="search.mjs (server)"
import { client } from './sluby.mjs';

const page = await client.assets.list({
  search: 'interview',
  accessTier: 'private',
  sort: 'title',
  order: 'asc',
  page: 2,
  limit: 20,
});
console.log(`${page.total} matches, showing ${page.data.length}`);
```

- `search` matches the title or description, ignoring case, or a video's exact id.
- `status` is one of `created`, `uploading`, `processing`, `ready` and `failed`. `accessTier` is `public` or `private`.
- `sort` is `created_at` (the default), `title`, `duration` or `size`, and `order` is `desc` (the default) or `asc`.

The REST reference lists every query parameter and its limits: [`GET /api/v1/assets`](/developers/reference/api/assets/get-assets).

## Wait for processing [#wait-for-processing]

After an upload, `client.assets.waitForReady()` polls the video until its status is `ready` and returns it. `pollInterval` and `timeout`, in milliseconds, set how often it checks and when it gives up; their defaults are in the [SDK reference](/developers/reference/sdk#waitforready).

```js title="wait.mjs (server)"
import { ProcessingFailedError, TimeoutError } from '@sluby/sdk';
import { client } from './sluby.mjs';

const assetId = process.argv[2];

try {
  const asset = await client.assets.waitForReady(assetId, {
    pollInterval: 5000,
    timeout: 30 * 60_000,
  });
  console.log(`ready, ${asset.durationMs} ms`);
} catch (err) {
  if (err instanceof ProcessingFailedError) {
    const job = await client.assets.processing(assetId);
    console.log(`failed at ${job.stage}: ${job.errorMessage}`);
  } else if (err instanceof TimeoutError) {
    console.log('still processing, check again later');
  } else {
    throw err;
  }
}
```

`waitForReady` rejects with a `ProcessingFailedError` as soon as the video's status is `failed` (its `asset` property holds the video), and with a `TimeoutError` when the timeout passes first. Processing goes on after a timeout; only the waiting stops. Pass `signal` to stop waiting early: it then rejects with an `AbortError`.

To show progress while you wait, read the processing job:

```js title="progress.mjs (server)"
import { client } from './sluby.mjs';

const assetId = process.argv[2];

const job = await client.assets.processing(assetId);
console.log(`${job.status}, ${job.stage}, ${job.progressPercent}%`);
for (const line of job.logs) console.log(line.timestamp, line.stage, line.message);
```

`stage` is `queued`, `transcode`, `upload`, `finalize`, `completed` or `failed`, and `progressPercent` runs from 0 to 100 over the whole pipeline. [Upload pipeline](/developers/concepts/upload-pipeline) explains each stage. To get notified instead of polling, [receive webhooks](/developers/guides/webhooks).

## Read and edit a video [#read-and-edit-a-video]

`client.assets.get()` returns one video. `client.assets.update()` changes its `title`, `description` or `accessTier`. Pass the video as you read it in `ifMatch`, and the edit applies only if nobody changed the video since:

```js title="edit.mjs (server)"
import { ConflictError } from '@sluby/sdk';
import { client } from './sluby.mjs';

const assetId = process.argv[2];

const asset = await client.assets.get(assetId);
try {
  const updated = await client.assets.update(
    asset.id,
    { title: 'Launch keynote', description: 'Recorded on stage' },
    { ifMatch: asset },
  );
  console.log(`saved at ${updated.updatedAt}`);
} catch (err) {
  if (!(err instanceof ConflictError) || !err.current) throw err;
  // someone changed the video after you read it; err.current is the video as it is now
  console.log(`changed elsewhere, title is now "${err.current.title}"`);
}
```

The SDK sends `ifMatch` as an `If-Match` header holding the video's ETag: its `updatedAt` in milliseconds since the epoch, in quotes. When the video changed in the meantime, the API answers `412` and the SDK throws a `ConflictError` whose `current` is the video as it is now. Without `ifMatch`, the edit always applies. `assetEtag(asset)` returns the same ETag if you call the REST API yourself.

Changing `accessTier` decides who can watch; see [Serve private videos](/developers/guides/private-videos).

## Retry a failed video [#retry-a-failed-video]

When processing fails, `client.assets.processing()` tells you whether a retry can work: `retryable` is `true` for a failed video whose failure was not final and whose transcode output or original file is still on the server.

```js title="retry.mjs (server)"
import { client } from './sluby.mjs';

const assetId = process.argv[2];

const job = await client.assets.processing(assetId);
if (job.retryable) {
  const { stage } = await client.assets.retry(assetId);
  console.log(`restarted from ${stage}`); // 'transcode' or 'upload-segments'
}
```

A retry skips the transcode when its output survived and restarts at the upload to Sia (`upload-segments`); otherwise it transcodes the original file again (`transcode`). The API refuses a retry with `400` for a video that is not `failed`, and with `410` when neither the transcode output nor the original file is left on the server. Upload the video again in that case.

## Delete a video [#delete-a-video]

```js title="delete.mjs (server)"
import { NotFoundError } from '@sluby/sdk';
import { client } from './sluby.mjs';

const assetId = process.argv[2];

try {
  await client.assets.delete(assetId);
} catch (err) {
  if (!(err instanceof NotFoundError)) throw err;
  // already deleted, or no such video
}
```

The video leaves your library at once, and a background worker unpins its objects on Sia. Deletion cannot be undone. [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation) explains each step.

The [SDK reference](/developers/reference/sdk) lists the other `client.assets` methods, such as `renditions`, `stats` and `usage`.


# Play videos without React (/developers/guides/play-hls)

A Sluby video is an HLS stream, so any HLS player can play it from its playback URL. This guide uses [hls.js](https://github.com/video-dev/hls.js) in plain browser JavaScript. For direct-from-Sia playback, `@sluby/player/hls` gives you the hls.js loaders the React player uses, without React. All code on this page runs in the browser and uses no API key.

## Install [#install]

```bash
npm install hls.js @sluby/sdk
```

Add `@sluby/player` too if you want to stream from Sia. Its `@sluby/player/hls` entry imports only hls.js, so React is not needed:

```bash
npm install @sluby/player
```

## Play through the gateway [#play-through-the-gateway]

`client.playback.streamUrl()` builds the master playlist URL of a public video without a request. Hand it to hls.js, or to the `<video>` element where the browser plays HLS natively:

```ts title="play.ts (browser)"
import Hls from 'hls.js';
import { SlubyClient } from '@sluby/sdk';

const client = new SlubyClient({ baseUrl: 'https://sluby.example.com' });

export function play(video: HTMLVideoElement, assetId: string): Hls | null {
  const url = client.playback.streamUrl(assetId);

  if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(url);
    hls.attachMedia(video);
    return hls;
  }
  // iPhones without Managed Media Source cannot run hls.js, but play HLS natively
  if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = url;
    return null;
  }
  throw new Error('This browser cannot play HLS.');
}
```

The gateway answers playback requests from any origin, so the page can live on another domain than your Sluby server.

For a private video, use a signed URL from your server instead of `streamUrl()`; see [Serve private videos](/developers/guides/private-videos). The gateway signs every playlist and segment URL inside a private video's playlists with the same expiry, and refuses them after it. `<SlubyPlayer>` renews a signed URL during playback through its [`refreshSrc`](/developers/guides/private-videos#play-the-signed-url) prop; with hls.js alone, request an `expiresIn` that covers the viewing.

## Stream from Sia [#stream-from-sia]

`createSiaLoader` returns an hls.js loader class that downloads every playlist and segment from Sia through the client's viewer session. The client needs the `sia` option with your viewer identity ([Stream from Sia in the browser](/self-hosting/direct-playback) shows how the operator creates one).

```ts title="client.ts (browser)"
import { SlubyClient } from '@sluby/sdk';

// reuse one client: its viewer session stays connected between videos
export const client = new SlubyClient({
  baseUrl: 'https://sluby.example.com',
  sia: {
    indexerUrl: import.meta.env.VITE_SLUBY_SIA_INDEXER_URL,
    appId: import.meta.env.VITE_SLUBY_SIA_APP_ID,
    appKey: import.meta.env.VITE_SLUBY_SIA_APP_KEY,
  },
});
```

This sample reads the viewer identity from Vite environment variables.

```ts title="play-from-sia.ts (browser)"
import Hls, { type HlsConfig } from 'hls.js';
import { createSiaLoader } from '@sluby/player/hls';
import { client } from './client';

export async function playFromSia(video: HTMLVideoElement, assetId: string, url: string) {
  const config: Partial<HlsConfig> = {};
  if (client.sia) {
    // connect and fetch the share map first, so a bad viewer key fails here
    await client.sia.prepare(assetId, { src: url });
    config.loader = createSiaLoader(client.sia, assetId, { src: url });
  }
  const hls = new Hls(config);
  hls.loadSource(url);
  hls.attachMedia(video);
  return hls;
}

// a public video: playFromSia(video, id, client.playback.streamUrl(id))
```

Pass the gateway URL you would otherwise play as `url`: the stream URL of a public video, or a signed URL for a private one. With `{ src: url }`, the session fetches the video's share map from the public share endpoint next to that URL, carrying the URL's signature when it has one, so no API key is involved. Where hls.js cannot run (native HLS on an iPhone), no loader applies: set the gateway URL on the `<video>` element as in [Play through the gateway](#play-through-the-gateway).

## Mix the gateway and Sia [#mix-the-gateway-and-sia]

`createHybridLoader` loads playlists, the start of a video and any segment needed urgently through the gateway, and takes segments from Sia once enough video is buffered. The loader cuts off a Sia read that fails or runs long, and the gateway fetches that segment instead.

```ts title="play-hybrid.ts (browser)"
import Hls from 'hls.js';
import { createHybridLoader } from '@sluby/player/hls';
import { client } from './client';

export function playHybrid(video: HTMLVideoElement, assetId: string, url: string) {
  if (!client.sia) throw new Error('hybrid delivery needs a viewer identity');
  const hls = new Hls({
    // a new loader class for every Hls instance: the class holds the load's state
    loader: createHybridLoader({
      session: client.sia,
      assetId,
      source: { src: url },
      media: () => video,
      onStats: (s) =>
        console.log(`${s.siaSegments} segments from Sia, ${s.gatewaySegments} from the gateway`),
    }),
  });
  hls.loadSource(url);
  hls.attachMedia(video);
  return hls;
}
```

`media` returns the element hls.js plays into; the loader reads from it how much video is buffered. The `policy` option tunes the thresholds; the [player reference](/developers/reference/player#hybrid-types) lists its fields and defaults (`DEFAULT_HYBRID_POLICY`), and [createHybridLoader](/developers/reference/player#createhybridloader) describes every rule the loader follows.

## Recover from errors [#recover-from-errors]

hls.js retries errors that are not fatal on its own. For fatal errors, this handler retries a network error up to 3 times and a media error up to 2 times, and resets both counters whenever hls.js buffers a segment. `<SlubyPlayer>` uses the same limits by default ([recovery props](/developers/reference/player#recovery-props)).

```ts title="recovery.ts (browser)"
import Hls from 'hls.js';

export function withRecovery(hls: Hls, onGiveUp: (message: string) => void) {
  let network = 0;
  let media = 0;
  let manifestParsed = false;
  hls.on(Hls.Events.MANIFEST_PARSED, () => {
    manifestParsed = true;
  });
  hls.on(Hls.Events.FRAG_BUFFERED, () => {
    network = 0;
    media = 0;
  });
  hls.on(Hls.Events.ERROR, (_event, data) => {
    if (!data.fatal) return; // hls.js retries these itself
    if (data.type === Hls.ErrorTypes.NETWORK_ERROR && network < 3) {
      network += 1;
      // startLoad resumes only after a manifest was parsed; a failed manifest loads again
      if (manifestParsed) hls.startLoad();
      else if (hls.url) hls.loadSource(hls.url);
    } else if (data.type === Hls.ErrorTypes.MEDIA_ERROR && media < 2) {
      media += 1;
      hls.recoverMediaError();
    } else {
      hls.destroy();
      onGiveUp(`${data.type}: ${data.details}`);
    }
  });
}
```

The `examples/vanilla` app in the Sluby repository puts these pieces together with uploads, a quality menu and a signing server.


# Play videos in React (/developers/guides/play-react)

`<SlubyPlayer>` from `@sluby/player` plays a Sluby video in a React app. It runs hls.js with adaptive quality, uses the browser's native HLS where hls.js is not supported, shows a loading spinner and an error overlay with a **Retry** button, and streams the video bytes straight from Sia when you give it a viewer identity. Everything on this page runs in the browser and uses no API key.

## Install [#install]

```bash
npm install @sluby/player @sluby/sdk
```

The React versions the player supports are in the [player reference](/developers/reference/player#package).

## Play a public video [#play-a-public-video]

Create one `SlubyClient` for your app and pass the video's stream URL as `src`:

```tsx title="Video.tsx (browser)"
import { SlubyClient } from '@sluby/sdk';
import { SlubyPlayer } from '@sluby/player';

// no API key: a public video plays from its stream URL
const client = new SlubyClient({ baseUrl: 'https://sluby.example.com' });

export function Video({ assetId }: { assetId: string }) {
  return (
    <SlubyPlayer src={client.playback.streamUrl(assetId)} controls style={{ width: '100%' }} />
  );
}
```

`client.playback.streamUrl()` builds the URL without a request and accepts an asset id or a `pb_...` playback id.

The player can also resolve the URL itself when you pass `client` and `assetId` without `src`. It then asks the API for the playback URL, which takes credentials with the `read` scope (an API key or a Sluby session). On a page that anyone can open, pass `src` instead, as above.

A private video does not play from its stream URL. [Serve private videos](/developers/guides/private-videos) shows how your server hands the player a signed URL.

## Stream the bytes from Sia [#stream-the-bytes-from-sia]

With a viewer identity in the client's `sia` option, the player downloads the video straight from Sia hosts instead of through your Sluby server's gateway. The viewer identity is publishable, not a secret: the operator of your Sluby server creates it with the `provision-viewer` script, which prints the three `VITE_SLUBY_SIA_*` values ([Stream from Sia in the browser](/self-hosting/direct-playback)).

Create the client once, outside your components:

```ts title="sluby.ts (browser)"
import { SlubyClient } from '@sluby/sdk';

// created once for the whole app: a new client makes the player load again
export const client = new SlubyClient({
  baseUrl: 'https://sluby.example.com',
  // the viewer identity your Sluby operator gives you; omit it to play through the gateway
  sia: {
    indexerUrl: import.meta.env.VITE_SLUBY_SIA_INDEXER_URL,
    appId: import.meta.env.VITE_SLUBY_SIA_APP_ID,
    appKey: import.meta.env.VITE_SLUBY_SIA_APP_KEY,
  },
});
```

This sample reads the values from Vite environment variables. Then pass `client` and `assetId` along with `src`:

```tsx title="Video.tsx (browser)"
import { SlubyPlayer } from '@sluby/player';
import { client } from './sluby';

export function Video({ assetId }: { assetId: string }) {
  return (
    <SlubyPlayer
      src={client.playback.streamUrl(assetId)}
      client={client}
      assetId={assetId}
      controls
      style={{ width: '100%' }}
      onError={(err) => console.error('playback failed', err.message, err.cause)}
    />
  );
}
```

With `src`, the player only uses the client's `sia` session, so this still needs no API key. The player plays through the gateway instead when the client has no `sia` option, when `assetId` is missing, or when the browser plays HLS natively. Under the default `"direct"` mode, when the Sia session cannot connect, the player logs a console warning and plays that video through the gateway. [Playback and delivery](/developers/concepts/playback#delivery-modes) explains the mechanism.

## Choose a delivery mode [#choose-a-delivery-mode]

`siaDelivery` decides how the bytes travel when the client has a viewer session:

- `"direct"` (the default) streams every playlist and segment from Sia.
- `"hybrid"` loads the playlists, the start of the video and any segment needed urgently through the gateway, and takes the other segments from Sia once enough video is buffered. Starting playback never waits for the Sia session, and a Sia read that fails or runs long falls back to the gateway.

`onDeliveryChange` reports the mode of each load as `'sia'`, `'hybrid'` or `'gateway'`. Under hybrid delivery, `onDeliveryStats` reports after every segment how many bytes and segments came from each side:

```tsx title="HybridVideo.tsx (browser)"
import { useState } from 'react';
import { SlubyPlayer, type HybridDeliveryStats } from '@sluby/player';
import { client } from './sluby';

export function HybridVideo({ assetId }: { assetId: string }) {
  const [mode, setMode] = useState<'sia' | 'hybrid' | 'gateway' | null>(null);
  const [stats, setStats] = useState<HybridDeliveryStats | null>(null);
  const total = stats ? stats.siaBytes + stats.gatewayBytes : 0;

  return (
    <>
      <SlubyPlayer
        src={client.playback.streamUrl(assetId)}
        client={client}
        assetId={assetId}
        siaDelivery="hybrid"
        onDeliveryChange={setMode}
        onDeliveryStats={setStats}
        controls
      />
      <p>
        {mode}
        {stats && total > 0 && `, ${Math.round((stats.siaBytes / total) * 100)}% of bytes from Sia`}
      </p>
    </>
  );
}
```

`hybridPolicy` tunes when a segment can come from Sia; the [player reference](/developers/reference/player#hybrid-types) lists its fields and defaults.

## Show a quality menu [#show-a-quality-menu]

`onQualitiesChange` lists the renditions once the manifest is parsed, `onQualityChange` reports the one playing, and the player handle's `setQuality()` pins one. `-1` goes back to adaptive quality.

```tsx title="VideoWithQuality.tsx (browser)"
import { useRef, useState } from 'react';
import { SlubyPlayer, type QualityLevel, type SlubyPlayerHandle } from '@sluby/player';
import { client } from './sluby';

export function VideoWithQuality({ assetId }: { assetId: string }) {
  const player = useRef<SlubyPlayerHandle>(null);
  const [levels, setLevels] = useState<QualityLevel[]>([]);
  const [current, setCurrent] = useState<QualityLevel | null>(null);
  const [pinned, setPinned] = useState(-1);

  return (
    <>
      <SlubyPlayer
        ref={player}
        src={client.playback.streamUrl(assetId)}
        controls
        onQualitiesChange={setLevels}
        onQualityChange={setCurrent}
      />
      <select
        value={pinned}
        onChange={(e) => {
          const index = Number(e.target.value);
          player.current?.setQuality(index); // -1 goes back to adaptive
          setPinned(index);
        }}
      >
        <option value={-1}>Auto{current ? ` (${current.name})` : ''}</option>
        {levels.map((level) => (
          <option key={level.index} value={level.index}>
            {level.name}, {Math.round(level.bitrate / 1000)} kbps
          </option>
        ))}
      </select>
    </>
  );
}
```

`onQualitiesChange` fires only when hls.js plays the video, so on native HLS playback the menu in this sample offers only `Auto`.

## React to playback events [#react-to-playback-events]

```tsx title="TrackedVideo.tsx (browser)"
import { SlubyPlayer } from '@sluby/player';
import { client } from './sluby';

export function TrackedVideo({ assetId }: { assetId: string }) {
  return (
    <SlubyPlayer
      src={client.playback.streamUrl(assetId)}
      controls
      onStateChange={(state) => console.log('state', state)}
      onReady={() => console.log('ready')}
      onPlay={() => console.log('play')}
      onPause={() => console.log('pause')}
      onEnd={() => console.log('ended')}
      onError={(err) => console.error(err)}
    />
  );
}
```

`onStateChange` receives `'idle'`, `'loading'`, `'ready'`, `'buffering'` or `'error'`, first with the state at mount and then on every change. `onError` fires once the player gives up; the error's `cause` holds the underlying SDK or hls.js error when there is one. Changing a callback prop does not reload the video.

## Build your own controls [#build-your-own-controls]

`useVideo` follows the player and gives you its state and controls. Pass it the player's ref:

```tsx title="CustomControls.tsx (browser)"
import { useRef } from 'react';
import { SlubyPlayer, useVideo, type SlubyPlayerHandle } from '@sluby/player';
import { client } from './sluby';

export function CustomControls({ assetId }: { assetId: string }) {
  const player = useRef<SlubyPlayerHandle>(null);
  const video = useVideo(player);

  return (
    <>
      <SlubyPlayer ref={player} src={client.playback.streamUrl(assetId)} controls={false} />
      <button onClick={video.isPlaying ? video.pause : video.play}>
        {video.isPlaying ? 'Pause' : 'Play'}
      </button>
      <button onClick={() => video.seek(video.currentTime + 10)}>+10 s</button>
      <span>
        {Math.floor(video.currentTime)} / {Math.floor(video.duration)} s
        {video.isBuffering && ', buffering'}
      </span>
    </>
  );
}
```

`useVideo` also returns `setVolume`, `volume`, `qualities`, `currentQuality` and `setQuality`. The [player reference](/developers/reference/player) lists every prop, the handle's methods and the full return value of `useVideo`.


# Serve private videos (/developers/guides/private-videos)

A private video plays only through a signed URL: a playback URL with an expiry and a signature that your server mints with its API key. Your server decides who can watch, the browser receives only the signed URL, and the key never leaves the server. [Playback and delivery](/developers/concepts/playback#signed-urls) explains how signing works, including the default and maximum lifetime of a signed URL.

## Make a video private [#make-a-video-private]

On your server, set the access tier at upload, or change it later with a key that has the `manage` scope:

```js
// at upload
await client.uploads.upload(file, { title: 'Members only', accessTier: 'private' });

// later, with a key that has the manage scope
await client.assets.update(assetId, { accessTier: 'private' });
```

Making a video private also stops every signed URL minted for it before the change.

## Mint signed URLs on your server [#mint-signed-urls-on-your-server]

Add a route to your server that checks your own access rule and then asks Sluby for a signed URL. A key with the `read` scope is enough.

```js title="server.mjs (server)"
import { createServer } from 'node:http';
import { SlubyClient, NotFoundError } from '@sluby/sdk';

const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');
// a key with the read scope is enough to mint signed URLs
const client = new SlubyClient({ baseUrl: SLUBY_URL, apiKey: SLUBY_API_KEY });

/**
 * Your own access rule: is this visitor signed in, did they buy this video.
 * @param {import('node:http').IncomingMessage} req
 * @param {string} assetId
 */
async function canWatch(req, assetId) {
  // look up your own session and the videos this visitor can watch
  return false;
}

createServer(async (req, res) => {
  const url = new URL(req.url ?? '/', 'http://localhost');
  const match = /^\/playback\/([^/]+)$/.exec(url.pathname);
  if (req.method !== 'GET' || !match) {
    res.writeHead(404).end();
    return;
  }
  const assetId = decodeURIComponent(match[1]);
  if (!(await canWatch(req, assetId))) {
    res.writeHead(403).end();
    return;
  }
  try {
    const signed = await client.playback.getSignedUrl(assetId, { expiresIn: 3600 });
    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
    res.end(
      JSON.stringify({
        url: signed.signedUrl,
        poster: signed.posterUrl,
        expiresAt: signed.expiresAt,
      }),
    );
  } catch (err) {
    res.writeHead(err instanceof NotFoundError ? 404 : 502).end();
  }
}).listen(3000);
```

`getSignedUrl` returns:

- `signedUrl`: the signed master playlist URL. When the gateway serves a private video's playlists, it signs every URL inside them with the same expiry.
- `posterUrl`: the video's poster image, signed the same way, or `null` when the video has none.
- `expiresAt`: when the URL stops working, as an ISO 8601 timestamp.

`expiresIn` is the lifetime in seconds and must be a positive whole number. Without it the server applies its default. A video that is not ready yet has no playback URL: the API answers `409` ([`GET /api/v1/playback/{id}/signed`](/developers/reference/api/playback/get-playback-id-signed)).

## Play the signed URL [#play-the-signed-url]

Fetch the signed URL from your route and pass it to the player as `src`. `refreshSrc` keeps a long viewing going: the player calls it shortly before the URL expires, and keeps playing from the same position on the URL it returns.

```tsx title="PrivateVideo.tsx (browser)"
import { useEffect, useState } from 'react';
import { SlubyPlayer } from '@sluby/player';
import { client } from './sluby';

interface SignedPlayback {
  url: string;
  poster: string | null;
  expiresAt: string;
}

async function fetchPlayback(assetId: string): Promise<SignedPlayback> {
  const res = await fetch(`/playback/${encodeURIComponent(assetId)}`);
  if (!res.ok) throw new Error(`Could not get a playback URL (${res.status})`);
  return (await res.json()) as SignedPlayback;
}

export function PrivateVideo({ assetId }: { assetId: string }) {
  const [playback, setPlayback] = useState<SignedPlayback | null>(null);

  useEffect(() => {
    fetchPlayback(assetId).then(setPlayback, (err) => console.error(err));
  }, [assetId]);

  if (!playback) return null;
  return (
    <SlubyPlayer
      src={playback.url}
      poster={playback.poster ?? undefined}
      // called shortly before the URL expires; playback continues on the new one
      refreshSrc={async () => (await fetchPlayback(assetId)).url}
      // optional: with a viewer identity the bytes come straight from Sia
      client={client}
      assetId={assetId}
      controls
    />
  );
}
```

`client` is the browser `SlubyClient` without an API key from [Play videos in React](/developers/guides/play-react#stream-the-bytes-from-sia). With `client` and `assetId` next to a signed `src`, the player streams from Sia using the share map that belongs to that signed URL, so the browser still holds no key. Leave both out to play through the gateway.

Without `refreshSrc`, playback of a signed `src` fails when the URL expires. To play a signed URL with hls.js and no React, see [Play videos without React](/developers/guides/play-hls#play-through-the-gateway).

## Revoke signed URLs [#revoke-signed-urls]

To stop every signed URL of a video at once, for example after a link leaked, call the revoke endpoint with a key that has the `manage` scope. Your server can mint new signed URLs right after.

```js title="revoke.mjs (server)"
const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');
const assetId = process.argv[2];
if (!assetId) throw new Error('usage: node revoke.mjs <asset id>');

// needs a key with the manage scope
const res = await fetch(
  `${SLUBY_URL}/api/v1/playback/${encodeURIComponent(assetId)}/signed/revoke`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${SLUBY_API_KEY}` },
  },
);
if (!res.ok) throw new Error(`revoke failed: ${res.status}`);
```

With the SDK, the same call is `await client.playback.revokeSignedUrls(assetId)`, which resolves `{ signingGeneration }`. In the Studio, it is **Revoke signed URLs** on the video's page ([Revoke signed URLs](/studio/privacy#revoke-signed-urls)).

The REST reference documents the endpoint: [`POST /api/v1/playback/{id}/signed/revoke`](/developers/reference/api/playback/post-playback-id-signed-revoke).


# Upload videos from your app (/developers/guides/upload)

Uploading a file creates a video asset in your Sluby library. After the last byte arrives, Sluby transcodes the video and stores it on Sia; [Upload pipeline](/developers/concepts/upload-pipeline) explains those steps. This guide shows how to send the file.

Uploads use the [tus](https://tus.io) resumable upload protocol at `POST /api/v1/uploads`. `@sluby/sdk` speaks tus for you. Any other tus client works too, as shown [at the end](#upload-with-any-tus-client).

Every upload needs credentials with the `upload` scope. An API key in browser code is readable by anyone who loads the page, so the samples here upload from your server.

## Upload a file from your server [#upload-a-file-from-your-server]

`client.uploads.upload()` takes a `Blob` or `File`, or the raw bytes as a `Uint8Array` (a Node.js `Buffer` is one). It does not take a Node.js stream. In Node.js, `openAsBlob` gives you a `Blob` backed by the file on disk, and the SDK reads it one chunk at a time, so a large file never sits in memory whole.

```js title="upload.mjs (server)"
import { openAsBlob } from 'node:fs';
import { basename } from 'node:path';
import { SlubyClient } from '@sluby/sdk';

const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');
const client = new SlubyClient({ baseUrl: SLUBY_URL, apiKey: SLUBY_API_KEY });

const path = process.argv[2];
if (!path) throw new Error('usage: node upload.mjs <file>');

// Ctrl+C cancels the upload and discards the asset it created
const controller = new AbortController();
process.once('SIGINT', () => controller.abort());

const upload = client.uploads.upload(await openAsBlob(path), {
  title: basename(path),
  description: 'Uploaded from my server',
  accessTier: 'private',
  signal: controller.signal,
  onProgress: (percent, sent, total) => console.log(`${percent}% (${sent} of ${total} bytes)`),
});

console.log(`asset ${await upload.assetId}, upload ${await upload.uploadId}`);
await upload;
console.log('all bytes received, processing starts');
```

The options in this sample:

- `title` is required. `description` is optional.
- `accessTier` is `'public'` (the default) or `'private'`. A private video plays only through a signed URL; see [Serve private videos](/developers/guides/private-videos).
- `onProgress` receives the percentage (0 to 100, rounded), the bytes sent and the total bytes.
- `signal` cancels the upload when it fires, the same as `upload.abort()`.

The [SDK reference](/developers/reference/sdk#uploads) lists the remaining options: `chunkSize`, `retryDelays`, `onSuccess`, `onError` and `resume`.

## Get the asset id before the upload finishes [#get-the-asset-id-before-the-upload-finishes]

`upload()` returns a handle that is a promise: `await upload` resolves when the server has every byte. The handle also carries two promises that resolve as soon as the server has created the upload, before the bytes finish:

- `upload.assetId`: the id of the video asset this upload creates. Use it to store the video in your own database, or to start waiting for processing.
- `upload.uploadId`: the id of the upload itself, for `client.uploads.getStatus(uploadId)` and `client.uploads.cancel(uploadId)`.

When the bytes are in, wait for processing with `client.assets.waitForReady(assetId)`, described in [Wait for processing](/developers/guides/manage-library#wait-for-processing), or let a [webhook](/developers/guides/webhooks) tell you.

## Pause, resume and cancel [#pause-resume-and-cancel]

```ts
const upload = client.uploads.upload(file, { title: 'Long recording' });

await upload.pause(); // stops sending; the bytes received so far stay on the server
console.log(upload.isPaused); // true
upload.resume(); // continues from the last byte the server has

await upload.abort(); // ends the upload and deletes the asset it created
await upload.catch((err) => console.log(err.name)); // AbortError
```

After `abort()`, the handle rejects with an `AbortError`, so attach a handler to it as the last line does. After the upload has finished, `abort()` does nothing, so cleanup code that always calls it never deletes a finished video. To remove a finished video, delete the asset ([Manage your library](/developers/guides/manage-library#delete-a-video)).

An upload that never finishes expires ([Unfinished and cancelled uploads](/developers/concepts/upload-pipeline#unfinished-and-cancelled-uploads)).

## Handle upload errors [#handle-upload-errors]

The handle, `upload.assetId` and `upload.uploadId` reject with a `SlubyError`. An HTTP error from the server becomes the subclass for its status, for example `PermissionError` for a key without the `upload` scope. After `abort()`, they reject with an `AbortError`:

```js
import { AbortError, PermissionError, SlubyError } from '@sluby/sdk';

const upload = client.uploads.upload(file, { title: 'Demo' });
try {
  await upload;
} catch (err) {
  if (err instanceof AbortError) console.log('cancelled');
  else if (err instanceof PermissionError) console.log('the key has no upload scope');
  else if (err instanceof SlubyError)
    console.log(`upload failed (${err.statusCode}): ${err.message}`);
  else throw err;
}
```

Before the handle rejects, the SDK retries a request that fails on the network or with a 5xx status, waiting the delays in [`retryDelays`](/developers/reference/sdk#uploadfileoptions) between attempts. The count starts over whenever the server has received more bytes. A 4xx status other than 409 or 423 fails the upload at once.

## Files that start in a browser [#files-that-start-in-a-browser]

When your users pick the file in your web app, send it to your own server and upload it from there with your key. The browser code:

```ts title="sendVideo.ts (browser)"
export async function sendVideo(file: File): Promise<string> {
  const res = await fetch(`/videos?title=${encodeURIComponent(file.name)}`, {
    method: 'POST',
    body: file,
  });
  if (!res.ok) throw new Error(`Upload failed with status ${res.status}`);
  const { assetId } = (await res.json()) as { assetId: string };
  return assetId;
}
```

The server writes the request body to a temporary file and uploads that file to Sluby:

```js title="server.mjs (server)"
import { createServer } from 'node:http';
import { createWriteStream, openAsBlob } from 'node:fs';
import { rm } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { pipeline } from 'node:stream/promises';
import { SlubyClient } from '@sluby/sdk';

const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');
const client = new SlubyClient({ baseUrl: SLUBY_URL, apiKey: SLUBY_API_KEY });

createServer(async (req, res) => {
  const url = new URL(req.url ?? '/', 'http://localhost');
  if (req.method !== 'POST' || url.pathname !== '/videos') {
    res.writeHead(404).end();
    return;
  }
  // check your own user's session here before you accept the file

  const path = join(tmpdir(), randomUUID());
  try {
    await pipeline(req, createWriteStream(path));
    const upload = client.uploads.upload(await openAsBlob(path), {
      title: url.searchParams.get('title') || 'Untitled',
    });
    const assetId = await upload.assetId;
    await upload;
    res.writeHead(201, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ assetId }));
  } catch (err) {
    console.error(err);
    res.writeHead(502, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ error: 'Upload failed' }));
  } finally {
    await rm(path, { force: true });
  }
}).listen(3000);
```

The SDK also uploads from a browser with the Sluby session cookie instead of a key, when the Sluby server itself serves the page. The Studio uploads this way.

In a browser, the SDK resumes an upload that a closed tab or a reload interrupted. Upload the same file again with the same title, description and access tier, and the same API key (or, without a key, the session cookie): the SDK continues the unfinished upload instead of creating a new asset. Pass `resume: false` to always start a new one.

## Upload with any tus client [#upload-with-any-tus-client]

Any tus 1.0.0 client can upload to Sluby. Send it to:

| Item           | Value                                                                 |
| -------------- | --------------------------------------------------------------------- |
| Endpoint       | `POST https://sluby.example.com/api/v1/uploads`                       |
| Authentication | `Authorization: Bearer <your API key>`, a key with the `upload` scope |

Sluby reads these keys from the tus `Upload-Metadata`:

| Key           | Value                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `title`       | Up to 200 characters, no control characters. Missing or blank becomes `Untitled`.                                              |
| `description` | Up to 5000 characters. Tabs and line breaks are allowed, other control characters are not.                                     |
| `accessTier`  | `public` or `private`. Default `public`. Sluby also accepts the key `access_tier`.                                             |
| `filetype`    | The file's MIME type. When set, it must start with `video/`, or the server answers `415` with `Only video files are accepted`. |
| `filename`    | The original file name.                                                                                                        |

The server refuses an empty file with `400` and `The file is empty`. The operator of the Sluby server sets the largest accepted file with `MAX_UPLOAD_SIZE` ([Configuration reference](/self-hosting/configuration#max_upload_size)).

The upload id is the last path segment of the upload URL that tus returns. Pass it to `GET /api/v1/uploads/{id}` (a key with the `read` scope) to read the upload's status and the id of the asset it created, in `video_asset_id`. This sample uses [tus-js-client](https://github.com/tus/tus-js-client) in Node.js:

```js title="tus-upload.mjs (server)"
import { readFile } from 'node:fs/promises';
import * as tus from 'tus-js-client';

const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');

const file = await readFile('./video.mp4');

const upload = new tus.Upload(file, {
  endpoint: `${SLUBY_URL}/api/v1/uploads`,
  headers: { Authorization: `Bearer ${SLUBY_API_KEY}` },
  chunkSize: 10 * 1024 * 1024,
  metadata: {
    filename: 'video.mp4',
    filetype: 'video/mp4',
    title: 'Uploaded with tus-js-client',
    description: '',
    accessTier: 'public',
  },
  onError: (err) => console.error('upload failed', err),
  onSuccess: async () => {
    // the upload id is the last path segment of the upload URL
    const uploadId = String(upload.url).split('/').pop();
    const res = await fetch(`${SLUBY_URL}/api/v1/uploads/${uploadId}`, {
      headers: { Authorization: `Bearer ${SLUBY_API_KEY}` },
    });
    const session = await res.json();
    console.log(`asset ${session.video_asset_id}`);
  },
});
upload.start();
```

A tus `DELETE` on the upload URL, or `DELETE /api/v1/uploads/{id}`, cancels an unfinished upload and discards its asset. The REST API reference documents [the upload status](/developers/reference/api/uploads/get-uploads-id) and [cancel](/developers/reference/api/uploads/delete-uploads-id) endpoints.


# Receive webhooks (/developers/guides/webhooks)

A webhook sends a signed `POST` request to your server when something happens to a video, for example when it is ready to play or when processing fails. This guide registers an endpoint, verifies its requests, sends a test event, and resends a failed delivery. [Webhook events](/developers/reference/webhook-events) lists every event, its payload and the headers, and describes how delivery, retries and the delivery log behave.

## Register an endpoint [#register-an-endpoint]

### In the Studio [#in-the-studio]

Open **Webhooks** under **Developers** and click **Add webhook**. Enter the **Endpoint URL**, choose the **Events** to receive, and click **Add webhook**. The Studio then shows the signing secret once: copy it before you close the dialog.

### With the SDK [#with-the-sdk]

Registering, listing and changing endpoints needs a key with the `manage` scope. This runs on your server:

```js title="create-webhook.mjs (server)"
import { SlubyClient } from '@sluby/sdk';

const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');
// managing webhooks needs a key with the manage scope
const client = new SlubyClient({ baseUrl: SLUBY_URL, apiKey: SLUBY_API_KEY });

const endpoint = await client.webhookEndpoints.create({
  url: 'https://app.example.com/sluby-webhook',
  events: ['asset.ready', 'asset.errored'],
});
// shown only now: store it where your receiver reads it, for example SLUBY_WEBHOOK_SECRET
console.log(endpoint.id, endpoint.secret);
```

By default Sluby delivers only to public addresses. [Receiver addresses](/developers/reference/webhook-events#receiver-addresses) lists the URL rules and how the operator of your Sluby server allows a private network.

## Verify every request [#verify-every-request]

Each request carries an `X-Sluby-Timestamp` header and an `X-Sluby-Signature-V1` header ([signature scheme](/developers/reference/webhook-events#signature-scheme)). `webhooks.verifyRequest()` checks both: the signature must match your endpoint's secret, and the timestamp must fall inside the replay window ([Timestamps and replay window](/developers/reference/webhook-events#timestamps-and-replay-window)), so a captured request stops verifying after that. Pass the raw body exactly as it arrived, before any JSON parsing.

This receiver uses only Node.js built-ins and `@sluby/sdk`:

```js title="receiver.mjs (server)"
import { createServer } from 'node:http';
import { WebhookManager } from '@sluby/sdk';

const secret = process.env.SLUBY_WEBHOOK_SECRET;
if (!secret) throw new Error('Set SLUBY_WEBHOOK_SECRET.');
const webhooks = new WebhookManager();
const handled = new Set(); // use your database in production

createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/sluby-webhook') {
    res.writeHead(404).end();
    return;
  }
  // the signature covers the exact bytes, so read the raw body before parsing it
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const body = Buffer.concat(chunks).toString('utf8');

  if (!webhooks.verifyRequest(body, req.headers, secret)) {
    res.writeHead(401).end();
    return;
  }
  const event = webhooks.parseEvent(body);

  // a retry or a resend carries the same id: handle each event once
  if (event.id && handled.has(event.id)) {
    res.writeHead(200).end();
    return;
  }
  if (event.id) handled.add(event.id);

  if (event.event === 'asset.ready') {
    console.log(`video ${event.data.video_asset_id} is ready`);
  } else if (event.event === 'asset.errored') {
    console.log(`video ${event.data.video_asset_id} failed: ${event.data.error}`);
  }
  res.writeHead(200).end();
}).listen(3000);
```

`WebhookManager` needs no API key, so a receiver does not need a `SlubyClient`; `client.webhooks` is an instance of the same class. `parseEvent()` returns the event as `{ id, event, timestamp, data }`. The keys inside `data` stay as Sluby sends them, in snake case, such as `video_asset_id`.

`verifyRequest()` needs Node.js ([supported versions](/developers/reference/sdk#package)). In browsers, edge runtimes and Deno, use `verifyRequestAsync()`, which runs on Web Crypto:

```ts title="webhook.ts (server)"
import { WebhookManager } from '@sluby/sdk';

const webhooks = new WebhookManager();

// for runtimes with Web Crypto and the Fetch API, such as edge runtimes and Deno
export async function handleWebhook(request: Request, secret: string): Promise<Response> {
  const body = await request.text();
  if (!(await webhooks.verifyRequestAsync(body, request.headers, secret))) {
    return new Response(null, { status: 401 });
  }
  const event = webhooks.parseEvent(body);
  console.log(event.event, event.data);
  return new Response(null, { status: 200 });
}
```

## Answer quickly, and expect retries [#answer-quickly-and-expect-retries]

Answer with a `2xx` status before the delivery timeout, and do slow work after you answer. [Response and timeout](/developers/reference/webhook-events#response-and-timeout) lists which answers count as delivered.

Sluby retries a failed delivery on a fixed schedule ([Retries](/developers/reference/webhook-events#retries)). Every attempt carries the same event `id`, so drop an id you have already handled, as the receiver above does ([Duplicates and ordering](/developers/reference/webhook-events#duplicates-and-ordering)).

## Send a test event [#send-a-test-event]

To check your receiver, send a signed `webhook.test` event:

- In the Studio, click **Send test** on the webhook's page, or in its row on the **Webhooks** page.
- With the SDK:

```js title="test-webhook.mjs (server)"
const result = await client.webhookEndpoints.test(endpointId);
console.log(result.delivered ? `answered ${result.statusCode}` : `not delivered: ${result.error}`);
```

[Test events](/developers/reference/webhook-events#test-events) describes how Sluby sends and logs a test.

## Read the delivery log and resend [#read-the-delivery-log-and-resend]

Sluby logs every delivery attempt. [Delivery log](/developers/reference/webhook-events#delivery-log) lists what each entry holds, the failure reasons and how long Sluby keeps entries.

In the Studio, the **Deliveries** table on the webhook's page shows the log. **Show payload** opens the body that was sent, and **Send again** resends it. With the SDK:

```js title="deliveries.mjs (server)"
const deliveries = await client.webhookEndpoints.deliveries(endpointId, { limit: 100 });
for (const d of deliveries) {
  console.log(
    d.createdAt,
    d.event,
    `attempt ${d.attempt}`,
    d.delivered ? 'ok' : (d.error ?? d.statusCode),
  );
}

// send a failed one again, with the same event id
const failed = deliveries.find((d) => !d.delivered);
if (failed) {
  const { deliveryId } = await client.webhookEndpoints.redeliver(endpointId, failed.id);
  console.log(`queued as ${deliveryId}`);
}
```

`deliveries()` returns the newest attempts first. [Redelivery](/developers/reference/webhook-events#redelivery) describes what a resend carries and when Sluby refuses one; the SDK rejects a refused resend with a `ConflictError`.

## Pause, change or remove an endpoint [#pause-change-or-remove-an-endpoint]

```js title="manage-webhook.mjs (server)"
await client.webhookEndpoints.update(endpointId, { isActive: false }); // pause
await client.webhookEndpoints.update(endpointId, { isActive: true }); // resume
await client.webhookEndpoints.update(endpointId, { events: ['asset.ready'] });

const { secret } = await client.webhookEndpoints.rotateSecret(endpointId);
console.log(secret);

await client.webhookEndpoints.delete(endpointId);
```

- `isActive: false` pauses the endpoint ([Paused and deleted endpoints](/developers/reference/webhook-events#paused-and-deleted-endpoints)). In the Studio, use **Pause** and **Resume**.
- `rotateSecret()` replaces the signing secret, for example after it leaked, and only this answer contains the new one. [Signature scheme](/developers/reference/webhook-events#signature-scheme) describes when the old secret stops verifying. In the Studio, use **Rotate secret** on the webhook's page.
- `delete()` removes the endpoint and its delivery log. In the Studio, use **Delete webhook** under **More** on the webhook's page.

The REST reference documents each webhook endpoint, starting with [`POST /api/v1/webhooks`](/developers/reference/api/webhooks/post-webhooks).


# Build with Sluby (/developers)

In this walkthrough you upload a video from a Node.js script with `@sluby/sdk`, wait until Sluby has transcoded it and stored it on Sia, and play it in the browser with `@sluby/player`. The API key stays on your server; the browser plays the public video without one.

You need the address of a Sluby server, for example `https://sluby.example.com`, and a Studio account on it.

<Steps>
<Step>

### Create an API key [#create-an-api-key]

In the Studio, open **API keys** under **Developers** and click **Create key**. Give the key a name and keep the scopes `upload` and `read` selected: `upload` sends the file and `read` checks when it is ready. Click **Create key** and copy the key. The Studio shows it only once.

Keep the key on your server, for example in an environment variable:

```bash title=".env"
SLUBY_URL=https://sluby.example.com
SLUBY_API_KEY=sluby_...
```

[Create and manage API keys](/studio/api-keys) covers the page in detail, and [API conventions](/developers/reference/api-conventions#scopes) lists what each scope allows.

</Step>
<Step>

### Install the packages [#install-the-packages]

On the server, install the SDK. Check that your Node.js version is one the SDK supports ([package facts](/developers/reference/sdk#package)).

```bash
npm install @sluby/sdk
```

In your React app, install the SDK and the player ([supported React versions](/developers/reference/player#package)):

```bash
npm install @sluby/sdk @sluby/player
```

</Step>
<Step>

### Upload the video and wait until it is ready [#upload-the-video-and-wait-until-it-is-ready]

This script runs on your server. It uploads `video.mp4`, prints the id of the new video asset, and waits until processing has finished.

```js title="upload.mjs (server)"
import { openAsBlob } from 'node:fs';
import { SlubyClient } from '@sluby/sdk';

const { SLUBY_URL, SLUBY_API_KEY } = process.env;
if (!SLUBY_URL || !SLUBY_API_KEY) throw new Error('Set SLUBY_URL and SLUBY_API_KEY.');

const client = new SlubyClient({ baseUrl: SLUBY_URL, apiKey: SLUBY_API_KEY });

// a Blob backed by the file: the SDK reads it one chunk at a time
const file = await openAsBlob('./video.mp4');

const upload = client.uploads.upload(file, {
  title: 'My first video',
  onProgress: (percent) => console.log(`uploaded ${percent}%`),
});

const assetId = await upload.assetId;
console.log(`asset ${assetId} created`);
await upload;

const asset = await client.assets.waitForReady(assetId, { timeout: 30 * 60_000 });
console.log(`ready: ${asset.id}, ${asset.resolution}`);
```

Run it with your environment loaded:

```bash
node --env-file=.env upload.mjs
```

`upload.assetId` resolves as soon as the server has created the upload, before the bytes finish. `waitForReady` polls the asset until its status is `ready`, and the 30 minute `timeout` gives a long video time to process. [Wait for processing](/developers/guides/manage-library#wait-for-processing) covers its defaults and errors.

</Step>
<Step>

### Play the video [#play-the-video]

A public video plays from its stream URL, which the SDK builds without a request and without a key. This component runs in the browser:

```tsx title="Video.tsx (browser)"
import { SlubyClient } from '@sluby/sdk';
import { SlubyPlayer } from '@sluby/player';

// no API key: a public video plays from its stream URL
const client = new SlubyClient({ baseUrl: 'https://sluby.example.com' });

export function Video({ assetId }: { assetId: string }) {
  return (
    <SlubyPlayer src={client.playback.streamUrl(assetId)} controls style={{ width: '100%' }} />
  );
}
```

Render `<Video assetId="..." />` with the id the script printed.

</Step>
</Steps>

## Next steps [#next-steps]

<Cards>
  <Card title="Upload videos from your app" href="/developers/guides/upload">
    Progress, pause, resume and cancel, files that start in a browser, and uploads with any tus
    client.
  </Card>
  <Card title="Play videos in React" href="/developers/guides/play-react">
    Stream from Sia, pick a delivery mode, show a quality menu and build your own controls.
  </Card>
  <Card title="Play videos without React" href="/developers/guides/play-hls">
    Drive hls.js yourself, with or without the Sia loaders.
  </Card>
  <Card title="Serve private videos" href="/developers/guides/private-videos">
    Mint signed URLs on your server, renew them during playback and revoke them.
  </Card>
  <Card title="Manage your library from a server" href="/developers/guides/manage-library">
    List, search, edit, retry and delete videos.
  </Card>
  <Card title="Receive webhooks" href="/developers/guides/webhooks">
    Get a signed request when a video is ready or fails.
  </Card>
</Cards>

## Reference [#reference]

<Cards>
  <Card title="API conventions" href="/developers/reference/api-conventions">
    Authentication, scopes, errors, pagination and rate limits.
  </Card>
  <Card title="@sluby/sdk reference" href="/developers/reference/sdk">
    Every SDK namespace, method and error class.
  </Card>
  <Card title="@sluby/player reference" href="/developers/reference/player">
    Every player prop, the handle, `useVideo` and the loaders.
  </Card>
  <Card title="Webhook events" href="/developers/reference/webhook-events">
    Event types, payloads, headers and the signature scheme.
  </Card>
</Cards>

To learn how Sluby works inside, start with [Architecture](/developers/concepts/architecture).


# API conventions (/developers/reference/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](/developers/reference/api/assets/get-assets).

## Base URL [#base-url]

The REST API lives under `/api/v1` on your server's public URL. With the Docker Compose stack from [Install Sluby](/self-hosting), 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](/self-hosting/operations).

| Path prefix | What it serves                                                                                                                                                                                                                                                                                                                                              | Authentication                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `/api/v1/`  | The REST API, including tus uploads at `/api/v1/uploads`                                                                                                                                                                                                                                                                                                    | API key or Studio session, see [Authentication](#authentication)                           |
| `/v1/`      | The delivery gateway: [`/v1/stream/{id}/master.m3u8`](/developers/reference/api/delivery/get-stream-videoassetid-master-m3u8), [`/v1/objects/{objectId}`](/developers/reference/api/delivery/get-objects-objectid), [`/v1/share/{id}`](/developers/reference/api/delivery/get-share-id), [`/v1/cache/stats`](/developers/reference/api/ops/get-cache-stats) | None. Private videos use signed URLs ([how playback works](/developers/concepts/playback)) |
| `/watch/`   | The public watch page, [`/watch/{id}`](/developers/reference/api/delivery/get-watch-id)                                                                                                                                                                                                                                                                     | None                                                                                       |

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.

## Authentication [#authentication]

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`](/developers/reference/api/ops/get-openapi-json), [`GET /api/v1/docs`](/developers/reference/api/ops/get-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 keys [#api-keys]

Send the key as a bearer token:

```http
Authorization: Bearer sluby_...
```

| Property   | Value                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Format     | A key the server generates is `sluby_` followed by 43 base64url characters (32 random bytes)                                                                                                                                                                                                                                                    |
| Storage    | The server stores only the SHA-256 hash of the key, plus its first 12 characters (`prefix`) so you can tell keys apart                                                                                                                                                                                                                          |
| Shown      | Once, in the response that creates or rotates the key                                                                                                                                                                                                                                                                                           |
| Scopes     | One or more of `upload`, `read`, `manage`. A new key gets `upload` and `read` when you do not list any                                                                                                                                                                                                                                          |
| Rate limit | Per key, requests per minute. Default `100`, see [Rate limits](#rate-limits)                                                                                                                                                                                                                                                                    |
| Role       | A key acts with the current role of the member who created it, and stops working while that member is removed. A key created on the server ([`BOOTSTRAP_API_KEY`](/self-hosting/configuration#bootstrap_api_key) or the [seed script](/self-hosting/sign-in#create-an-admin-api-key-from-the-command-line)) has no creator and acts as an admin |

The header must start with `Bearer ` exactly. Create, rotate and revoke keys with the [keys endpoints](/developers/reference/api/keys/post-keys) or in the Studio ([Create and manage API keys](/studio/api-keys)). For what roles allow, see [Accounts, roles and sessions](/developers/concepts/accounts-and-roles).

### Scopes [#scopes]

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`.

| Scope    | Endpoints it allows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `upload` | tus uploads: [`POST /api/v1/uploads`](/developers/reference/api/uploads/post-uploads), [`HEAD`](/developers/reference/api/uploads/head-uploads-id) and [`PATCH /api/v1/uploads/{id}`](/developers/reference/api/uploads/patch-uploads-id). Cancelling an upload: [`DELETE /api/v1/uploads/{id}`](/developers/reference/api/uploads/delete-uploads-id)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `read`   | [`GET /api/v1/uploads/{id}`](/developers/reference/api/uploads/get-uploads-id), [`GET /api/v1/assets`](/developers/reference/api/assets/get-assets), [`GET /api/v1/assets/{id}`](/developers/reference/api/assets/get-assets-id), [`GET /api/v1/assets/{id}/processing`](/developers/reference/api/assets/get-assets-id-processing), [`GET /api/v1/assets/{id}/renditions`](/developers/reference/api/assets/get-assets-id-renditions), [`GET /api/v1/assets/{id}/sia`](/developers/reference/api/storage/get-assets-id-sia), [`GET /api/v1/assets/{id}/playback-ids`](/developers/reference/api/playback/get-assets-id-playback-ids), [`GET /api/v1/playback/{id}`](/developers/reference/api/playback/get-playback-id), [`GET /api/v1/playback/{id}/signed`](/developers/reference/api/playback/get-playback-id-signed), [`GET /api/v1/playback/{id}/share`](/developers/reference/api/playback/get-playback-id-share), [`GET /api/v1/stats`](/developers/reference/api/ops/get-stats), [`GET /api/v1/stats/usage`](/developers/reference/api/ops/get-stats-usage), [`GET /api/v1/system/status`](/developers/reference/api/ops/get-system-status), `GET /api/v1/metrics` (admins only) |
| `manage` | [`PATCH`](/developers/reference/api/assets/patch-assets-id) and [`DELETE /api/v1/assets/{id}`](/developers/reference/api/assets/delete-assets-id), [`POST /api/v1/assets/{id}/retry`](/developers/reference/api/assets/post-assets-id-retry), [`POST /api/v1/assets/{id}/playback-ids`](/developers/reference/api/playback/post-assets-id-playback-ids), [`DELETE /api/v1/playback-ids/{playbackId}`](/developers/reference/api/playback/delete-playback-ids-playbackid), [`POST /api/v1/playback/{id}/signed/revoke`](/developers/reference/api/playback/post-playback-id-signed-revoke), every [`/api/v1/keys`](/developers/reference/api/keys/get-keys) endpoint, every [`/api/v1/webhooks`](/developers/reference/api/webhooks/get-webhooks) endpoint, [`GET /api/v1/reconciliation`](/developers/reference/api/reconciliation/get-reconciliation), [`POST /api/v1/reconciliation/run`](/developers/reference/api/reconciliation/post-reconciliation-run) (admins only), every [`/api/v1/members`](/developers/reference/api/members/get-members) and [`/api/v1/invites`](/developers/reference/api/members/get-invites) endpoint (admins only)                                       |

A Studio session holds all three scopes.

#### Admin-only endpoints [#admin-only-endpoints]

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`](/developers/reference/api/reconciliation/post-reconciliation-run) (needs `manage`)
- the [members](/developers/reference/api/members/get-members) and [invites](/developers/reference/api/members/get-invites) endpoints (need `manage`)

Two endpoints answer everyone with the scope but return less to a member: [`GET /api/v1/system/status`](/developers/reference/api/ops/get-system-status) returns the health summary only, and [`GET /api/v1/reconciliation`](/developers/reference/api/reconciliation/get-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 cookie [#session-cookie]

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.

| Property   | Value                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------- |
| Name       | `sluby_session`                                                                                                       |
| Attributes | `Path=/`, `HttpOnly`, `SameSite=Lax`, and `Secure` when `PUBLIC_URL` starts with `https://`                           |
| Lifetime   | `Max-Age` set to the session's lifetime, see [Sessions and cookies](/developers/concepts/accounts-and-roles#sessions) |
| Scopes     | `upload`, `read`, `manage`                                                                                            |
| Role       | The account's current role, checked on every request                                                                  |
| Rate limit | 1000 requests per minute per account, see [Rate limits](#rate-limits)                                                 |

The server checks on every request that the session is still live and the account is not removed. [`GET /api/v1/auth/sessions`](/developers/reference/api/auth/get-auth-sessions), [`DELETE /api/v1/auth/sessions/{id}`](/developers/reference/api/auth/delete-auth-sessions-id), [`DELETE /api/v1/auth/sessions`](/developers/reference/api/auth/delete-auth-sessions), [`GET /api/v1/auth/me`](/developers/reference/api/auth/get-auth-me) and [`POST /api/v1/auth/password/change`](/developers/reference/api/auth/post-auth-password-change) work with the session cookie only. For how sessions start and end, see [Accounts, roles and sessions](/developers/concepts/accounts-and-roles).

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`](/self-hosting/configuration#auth_disabled)).

### Cross-origin writes [#cross-origin-writes]

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.

## Errors [#errors]

### Error body [#error-body]

Every REST error is JSON with an `error` string:

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

| Field              | When it is present                                                                                                                                                                                                           |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error`            | Always. A message meant for people. For a validation error it is the first problem, prefixed with the field name when the message does not already name it. For an unexpected server failure it is `"Internal Server Error"` |
| `details`          | A `400` from validation: one entry per problem, with `field` (dotted path, empty for the whole input) and `message`. Some sign-in errors also use it to point at a form field                                                |
| `reason`           | A machine-readable code on some `401`, `403`, `409` and `410` answers, see [Authentication failures](#authentication-failures)                                                                                               |
| `retry_after`      | A `429`: seconds to wait, the same value as the `Retry-After` header                                                                                                                                                         |
| `current`          | A `412` from [`PATCH /api/v1/assets/{id}`](/developers/reference/api/assets/patch-assets-id): the asset as it is now, see [ETags](#etags)                                                                                    |
| `message`, `stack` | Only when the server runs with `EXPOSE_ERROR_STACKS=true` ([`EXPOSE_ERROR_STACKS`](/self-hosting/configuration#expose_error_stacks))                                                                                         |

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 codes [#status-codes]

| Status | Meaning in Sluby                                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The body, query or a header is invalid. Also a malformed id, and malformed JSON                                                                                     |
| `401`  | No valid API key or session                                                                                                                                         |
| `403`  | The caller lacks a scope or the admin role, a cross-origin write was refused, or a sign-in check failed (wrong setup code, removed account, wrong current password) |
| `404`  | No such resource in the workspace, or no such route                                                                                                                 |
| `409`  | The request conflicts with the current state, for example the key limit is reached, a key was already rotated, or the action would leave no admin                   |
| `410`  | An invite or reset link was used, expired or revoked                                                                                                                |
| `412`  | `If-Match` does not match the asset's current version                                                                                                               |
| `413`  | The JSON body is larger than 1 MiB, or a tus upload is larger than the server allows                                                                                |
| `429`  | Over a rate limit or attempt limit                                                                                                                                  |
| `500`  | An unexpected server failure                                                                                                                                        |
| `502`  | An upstream did not answer, for example the Sia indexer while minting share URLs                                                                                    |
| `503`  | A dependency did not answer, for example the database while minting share URLs                                                                                      |

Each endpoint page in the [REST API reference](/developers/reference/api/assets/get-assets) lists the codes that endpoint returns. [`@sluby/sdk`](/developers/reference/sdk#errors) turns these into error classes.

### Authentication failures [#authentication-failures]

| Status | `error`                                                  | `reason`      | Cause                                                                      |
| ------ | -------------------------------------------------------- | ------------- | -------------------------------------------------------------------------- |
| `401`  | `Missing or invalid Authorization header`                | `missing`     | No `Authorization: Bearer` header and no session cookie this server signed |
| `401`  | `This session has expired`                               | `expired`     | The session cookie is past its expiry                                      |
| `401`  | `This session was signed out`                            | `revoked`     | The session was signed out, here or from another browser                   |
| `401`  | `This account was removed from this workspace`           | `not_allowed` | An admin removed the account behind the session                            |
| `401`  | `Invalid API key`                                        | none          | No key with this value exists (also a revoked key)                         |
| `401`  | `API key is deactivated`                                 | none          | The key is marked inactive                                                 |
| `401`  | `API key has expired`                                    | none          | The key was rotated and its grace period is over                           |
| `401`  | `This API key's creator was removed from this workspace` | `not_allowed` | The member who created the key was removed                                 |
| `403`  | `Requires '<scope>' scope`                               | none          | The key lacks the scope                                                    |
| `403`  | `Only an admin may use this endpoint`                    | none          | The caller is not an admin                                                 |

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.

## Pagination [#pagination]

Two list endpoints page with a cursor:

| Endpoint                                                            | Parameters                                                                    | Response fields                                             |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`GET /api/v1/assets`](/developers/reference/api/assets/get-assets) | `limit` (1 to 100, default 20), `cursor`, or `page` (1 to 1000000, default 1) | `data`, `next_cursor`, `has_more`, `total`, `page`, `limit` |
| [`GET /api/v1/keys`](/developers/reference/api/keys/get-keys)       | `limit` (1 to 1000, default 1000), `cursor`                                   | `data`, `next_cursor`, `has_more`, `limits`                 |

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`](/developers/reference/api/webhooks/get-webhooks-id-deliveries) takes only a `limit` (1 to 100, default 50) and returns the newest deliveries.

## Rate limits [#rate-limits]

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

| Limiter          | Applies to                                                                                                                                                                                                  | Limit                                                                                                                                                          | Counted per       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| Per key          | Authenticated REST requests with an API key                                                                                                                                                                 | The key's `rate_limit` per minute (default `100`), capped at 10000 per minute ([`API_KEY_RATE_LIMIT_MAX`](/self-hosting/configuration#api_key_rate_limit_max)) | API key           |
| Per session      | Authenticated REST requests with a Studio session                                                                                                                                                           | 1000 per minute, or the key cap when that is lower                                                                                                             | Account           |
| Per IP           | `/api/v1` requests that do not authenticate: the `/api/v1/auth` routes, the OpenAPI document and docs page, unknown routes, and requests with missing or invalid credentials                                | 600 per minute ([`API_IP_RATE_LIMIT`](/self-hosting/configuration#api_ip_rate_limit))                                                                          | Client IP address |
| Sign-in attempts | [`POST /api/v1/auth/password`](/developers/reference/api/auth/post-auth-password) and [`POST /api/v1/auth/password/change`](/developers/reference/api/auth/post-auth-password-change)                       | 10 attempts per 10 minutes                                                                                                                                     | Client IP address |
| Wrong passwords  | The same two routes                                                                                                                                                                                         | 5 wrong passwords per 15 minutes. A correct password clears the count                                                                                          | Email address     |
| Setup attempts   | [`POST /api/v1/auth/setup`](/developers/reference/api/auth/post-auth-setup)                                                                                                                                 | 10 attempts per 10 minutes                                                                                                                                     | Client IP address |
| Link attempts    | [`GET /api/v1/auth/invites/{token}`](/developers/reference/api/auth/get-auth-invites-token) and [`POST /api/v1/auth/invites/{token}/accept`](/developers/reference/api/auth/post-auth-invites-token-accept) | 30 per 10 minutes                                                                                                                                              | Client IP address |

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

| Header                  | Value                                             |
| ----------------------- | ------------------------------------------------- |
| `X-RateLimit-Limit`     | The limit of the current window                   |
| `X-RateLimit-Remaining` | Requests left in the window                       |
| `X-RateLimit-Reset`     | Seconds until the window resets (not a timestamp) |

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

```json
{
  "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`](/self-hosting/configuration#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 limits [#proxy-limits]

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

| Paths                          | Request rate (burst)                                                                                                                                                  | Concurrent connections                                                    |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `/v1/` (delivery)              | `100r/s` (burst 400), [`WEB_DELIVERY_RATE`](/self-hosting/configuration#web_delivery_rate) and [`WEB_DELIVERY_BURST`](/self-hosting/configuration#web_delivery_burst) | 200, [`WEB_DELIVERY_CONN`](/self-hosting/configuration#web_delivery_conn) |
| `/api/v1/auth/` and `/metrics` | `10r/s` (burst 50), [`WEB_AUTH_RATE`](/self-hosting/configuration#web_auth_rate) and [`WEB_AUTH_BURST`](/self-hosting/configuration#web_auth_burst)                   | 20, [`WEB_AUTH_CONN`](/self-hosting/configuration#web_auth_conn)          |

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](/self-hosting/configuration#web-proxy)).

## ETags and If-Match [#etags]

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

| Request                                                                         | ETag behavior                                                                                                        |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [`GET /api/v1/assets/{id}`](/developers/reference/api/assets/get-assets-id)     | Returns `ETag` with the asset's version and `Cache-Control: no-store`. Ignores `If-None-Match` (never answers `304`) |
| [`PATCH /api/v1/assets/{id}`](/developers/reference/api/assets/patch-assets-id) | Accepts `If-Match`. Returns the new `ETag`                                                                           |

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:

```json
{
  "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.

## CORS [#cors]

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

| Request origin                               | Answer                                                                                                                                     |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Listed in `CORS_ORIGIN`                      | `Access-Control-Allow-Origin` set to that origin, with `Access-Control-Allow-Credentials: true`. The session cookie works from that origin |
| Any other origin                             | `Access-Control-Allow-Origin: *` without credentials. Requests with an API key work; requests that rely on the session cookie do not       |
| Any other origin while `AUTH_DISABLED` is on | No CORS headers                                                                                                                            |

| Setting                  | Value                                                                                                                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Allowed methods          | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD`                                                                                                                                                                 |
| Allowed request headers  | `Content-Type`, `Authorization`, `Tus-Resumable`, `Upload-Length`, `Upload-Offset`, `Upload-Metadata`, `Upload-Concat`, `Upload-Defer-Length`, `X-Requested-With`, `If-Match`                                              |
| Exposed response headers | `Upload-Offset`, `Upload-Length`, `Upload-Metadata`, `Tus-Version`, `Tus-Resumable`, `Tus-Max-Size`, `Tus-Extension`, `Location`, `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `ETag` |
| Preflight cache          | `Access-Control-Max-Age: 600`                                                                                                                                                                                              |

When `CORS_ORIGIN` lists any origin, or `AUTH_DISABLED` is on, responses carry `Vary: Origin`. See [`CORS_ORIGIN`](/self-hosting/configuration#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 limits [#request-size-limits]

| Body                                                                   | Limit                                                                                               | Over the limit                                         |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| JSON request body (`Content-Type: application/json`) on any REST route | 1 MiB (1048576 bytes)                                                                               | `413` with `{"error": "request entity too large"}`     |
| Upload through tus                                                     | 10 GiB (10737418240 bytes), set by [`MAX_UPLOAD_SIZE`](/self-hosting/configuration#max_upload_size) | `413` with the plain-text body `Maximum size exceeded` |

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 reference [#openapi]

The server describes its API in an OpenAPI 3.1 document:

| URL                                                                          | What it returns                                                                                                                               | Authentication |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| [`GET /api/v1/openapi.json`](/developers/reference/api/ops/get-openapi-json) | The OpenAPI document as JSON                                                                                                                  | None           |
| [`GET /api/v1/docs`](/developers/reference/api/ops/get-docs)                 | An interactive reference page (Scalar) that reads `/api/v1/openapi.json`. The backend serves its script, so the page loads nothing from a CDN | None           |

Both count against the [per-IP limit](#rate-limits). The interactive page uses `bearerAuth` by default, so you can paste a key and send requests from it.

The [REST API reference](/developers/reference/api/assets/get-assets) on this site is generated from the same document, published here as [`/openapi.json`](/openapi.json).


# @sluby/player reference (/developers/reference/player)

`@sluby/player` plays Sluby videos in React: an hls.js player with adaptive quality, bounded error recovery, renewal of signed URLs, Safari's native HLS and direct-from-Sia delivery. Its `@sluby/player/hls` entry gives the same Sia loaders to apps that run hls.js without React. For a walkthrough, see [Play videos in React](/developers/guides/play-react) and [Play videos without React](/developers/guides/play-hls).

## Install [#install]

```bash
npm install @sluby/player react react-dom
```

For the `@sluby/player/hls` entry alone, React is not needed:

```bash
npm install @sluby/player hls.js
```

To resolve playback URLs from an asset id or to stream from Sia, also install [`@sluby/sdk`](/developers/reference/sdk) and pass a `SlubyClient` as `client`.

## Package [#package]

| Fact              | Value                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| Version           | This page describes `@sluby/player` 0.3.0                                                           |
| Entry points      | `@sluby/player` (React) and `@sluby/player/hls` (no React)                                          |
| Module formats    | ESM (`import`) and CommonJS (`require`) for both entries, each with type declarations               |
| Dependencies      | `hls.js`                                                                                            |
| Peer dependencies | `react` and `react-dom`, `^18 \|\| ^19`, both optional so `@sluby/player/hls` installs without them |
| Node.js           | `^20.16.0 \|\| >=22.3.0` (the `engines` field)                                                      |
| Side effects      | None (`"sideEffects": false`)                                                                       |

## Exports [#exports]

| Entry               | Export                                                                                                                                                                                                                                                                                          | Kind            |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `@sluby/player`     | [`SlubyPlayer`](#slubyplayer)                                                                                                                                                                                                                                                                   | React component |
| `@sluby/player`     | [`useVideo`](#usevideo)                                                                                                                                                                                                                                                                         | React hook      |
| `@sluby/player`     | [`SlubyPlayerHandle`](#handle), `SlubyPlayerProps`, `UseVideoReturn`, [`QualityLevel`, `TextTrackSource`, `PlayerState`, `PlaybackResolver`, `SiaPlaybackClient`](#types), [`SiaPlaybackSession`, `SiaShareSource`](#sia-session-types), [`HybridPolicy`, `HybridDeliveryStats`](#hybrid-types) | Types           |
| `@sluby/player/hls` | [`createSiaLoader`](#createsialoader)                                                                                                                                                                                                                                                           | Function        |
| `@sluby/player/hls` | [`createHybridLoader`](#createhybridloader)                                                                                                                                                                                                                                                     | Function        |
| `@sluby/player/hls` | [`DEFAULT_HYBRID_POLICY`](#hybrid-types)                                                                                                                                                                                                                                                        | Constant        |
| `@sluby/player/hls` | `HybridLoaderOptions`, `HybridPolicy`, `HybridDeliveryStats`, `SiaPlaybackSession`, `SiaShareSource`                                                                                                                                                                                            | Types           |

## SlubyPlayer [#slubyplayer]

```tsx
import { SlubyPlayer } from '@sluby/player';

<SlubyPlayer client={client} assetId={assetId} title="Launch video" />;
```

`SlubyPlayer` renders a `<div>` around a `<video>` and forwards a ref of type [`SlubyPlayerHandle`](#handle). The `<video>` always has `playsInline`.

### Choose the source [#source]

| Props                                             | What the player plays                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src`                                             | The URL as given, through the gateway                                                                                                                                                                                                                                                                                                         |
| `src` + `assetId` + `client` with a `sia` session | The same video straight from Sia, with the share map from the public share endpoint for `src`. No API key needed.                                                                                                                                                                                                                             |
| `client` + `assetId`, no `src`                    | The player calls `client.playback.getUrl(assetId)`. When that reports a private asset, it then calls `client.playback.getSignedUrl(assetId, { expiresIn })` and plays the signed URL. With `signed`, it calls only `getSignedUrl`. With a `sia` session on `client` it streams from Sia, with the share map from the authenticated API route. |

`assetId` takes an asset id or a `pb_...` playback id.

Without `src`, `client` needs a `playback` member (a `SlubyClient` has one). Otherwise the player fails with `SlubyPlayer needs a client with playback (a SlubyClient) to play an assetId without src.`

### Source props [#source-props]

| Prop         | Type                                         | Default        | Behavior                                                                                                                                                                                                                                |
| ------------ | -------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src`        | `string`                                     | none           | Absolute HLS master manifest URL on the gateway, such as `client.playback.streamUrl(id)` or a URL your server signed. A new `src` for the same video (same URL without its query) keeps playing without a reload while hls.js plays it. |
| `refreshSrc` | `(src: string) => string \| Promise<string>` | none           | For a signed `src`: called with the current `src` before it expires, and when a load fails after that. The player continues on the returned URL. Without it, playback of a signed `src` fails at its expiry.                            |
| `client`     | `PlaybackResolver \| SiaPlaybackClient`      | none           | A `SlubyClient`, or any object of either [type](#types). With `src`, the player uses only `client.sia`, so `{ sia }` is enough. Create it once: a different object resolves and loads the video again.                                  |
| `assetId`    | `string`                                     | none           | Asset id or `pb_...` playback id                                                                                                                                                                                                        |
| `signed`     | `boolean`                                    | `false`        | Play a signed URL from `client.playback.getSignedUrl`. Ignored with `src`.                                                                                                                                                              |
| `expiresIn`  | `number`                                     | server default | Lifetime in seconds of each signed URL the player fetches. Ignored with `src`.                                                                                                                                                          |

Passing `signed` or `expiresIn` together with `src` logs a console warning: `Sluby: signed and expiresIn are ignored when src is given; sign src on your server and pass refreshSrc to renew it before it expires.`

### Display props [#display-props]

| Prop              | Type                                     | Default             | Behavior                                                                                                                      |
| ----------------- | ---------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `poster`          | `string`                                 | the resolved poster | `<video poster>`. Without it, the player uses the poster that `getUrl` or `getSignedUrl` returned.                            |
| `title`           | `string`                                 | none                | Set as the `<video>`'s `aria-label`, the name screen readers announce                                                         |
| `tracks`          | `TextTrackSource[]`                      | none                | WebVTT caption and subtitle files, rendered as `<track>` elements                                                             |
| `crossOrigin`     | `'' \| 'anonymous' \| 'use-credentials'` | not set             | The `<video>`'s `crossorigin` attribute. Tracks on another origin need it, and that origin must send CORS headers.            |
| `controls`        | `boolean`                                | `true`              | The browser's native controls                                                                                                 |
| `muted`           | `boolean`                                | `false`             | Start muted                                                                                                                   |
| `autoPlay`        | `boolean`                                | `false`             | Start playing once the manifest is parsed and the element is ready to play. The browser's autoplay policy can still block it. |
| `width`, `height` | `number \| string`                       | none                | Applied to the wrapper's style and to the `<video>`                                                                           |
| `className`       | `string`                                 | none                | On the wrapper `<div>`                                                                                                        |
| `style`           | `CSSProperties`                          | none                | Merged over the wrapper's base style, `position: relative; display: inline-block`                                             |
| `overlay`         | `boolean`                                | `true`              | The built-in loading spinner and error overlay with a **Retry** button                                                        |

### Recovery props [#recovery-props]

| Prop                | Type     | Default | Behavior                                                        |
| ------------------- | -------- | ------- | --------------------------------------------------------------- |
| `maxNetworkRetries` | `number` | `3`     | Recoveries from fatal network errors before the player gives up |
| `maxMediaRetries`   | `number` | `2`     | Recoveries from fatal media errors before the player gives up   |

### Delivery props [#delivery-props]

| Prop           | Type                    | Default                                  | Behavior                                                                                              |
| -------------- | ----------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `siaDelivery`  | `'direct' \| 'hybrid'`  | `'direct'`                               | How a video with a viewer session is delivered. Ignored without a session. See [Delivery](#delivery). |
| `hybridPolicy` | `Partial<HybridPolicy>` | [`DEFAULT_HYBRID_POLICY`](#hybrid-types) | Tuning for `siaDelivery="hybrid"`. Read when a load starts.                                           |

### Callbacks [#callbacks]

| Prop                | Type                                             | Called                                                                                                                                |
| ------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady`           | `() => void`                                     | When the manifest is parsed (hls.js) or on `loadedmetadata` (native HLS)                                                              |
| `onPlay`            | `() => void`                                     | On the `<video>`'s `play` event                                                                                                       |
| `onPause`           | `() => void`                                     | On the `<video>`'s `pause` event                                                                                                      |
| `onEnd`             | `() => void`                                     | On the `<video>`'s `ended` event                                                                                                      |
| `onError`           | `(error: Error) => void`                         | When the player gives up. `error.cause` holds the underlying error when there is one, such as an SDK `SlubyError` or an hls.js error. |
| `onStateChange`     | `(state: PlayerState) => void`                   | Once with the starting state on mount, then on every [state](#states) change, in order                                                |
| `onQualityChange`   | `(level: QualityLevel) => void`                  | On every rendition switch, and once the manifest is parsed when hls.js has already picked a rendition                                 |
| `onQualitiesChange` | `(levels: QualityLevel[]) => void`               | With every rendition once the manifest is parsed. hls.js path only.                                                                   |
| `onDeliveryChange`  | `(mode: 'sia' \| 'hybrid' \| 'gateway') => void` | When each load starts, with how its bytes travel. See [Delivery](#delivery).                                                          |
| `onDeliveryStats`   | `(stats: HybridDeliveryStats) => void`           | Under hybrid delivery, after every media segment, with the totals of the load so far                                                  |

Changing a callback, `autoPlay`, `refreshSrc`, the retry limits or `hybridPolicy` does not reload the video.

### States [#states]

| `PlayerState` | Meaning                                                                      |
| ------------- | ---------------------------------------------------------------------------- |
| `idle`        | Nothing to play yet                                                          |
| `loading`     | Resolving the URL or loading the manifest                                    |
| `ready`       | The manifest is loaded, or the video is playing                              |
| `buffering`   | The `<video>` is waiting for data, or the player is recovering from an error |
| `error`       | The player gave up. The overlay shows the message and **Retry**.             |

**Retry** resolves the source again and continues from the same position.

### Error recovery [#error-recovery]

| hls.js fatal error | Recovery                                                           | Message when the player gives up                        |
| ------------------ | ------------------------------------------------------------------ | ------------------------------------------------------- |
| Network error      | Reloads after `1000 ms × attempt`, up to `maxNetworkRetries` times | `Network error, gave up after <n> retries (<details>).` |
| Media error        | `hls.recoverMediaError()`, up to `maxMediaRetries` times           | `Media error, gave up after <n> retries (<details>).`   |
| Any other type     | None                                                               | `Fatal HLS error: <type> / <details>`                   |

The retry counters reset each time a segment is buffered. A new load of the same video (after **Retry** or a renewal that reloads) resumes at the same position and play state.

When hls.js is unsupported and the browser has no native HLS, the player fails with `HLS is not supported in this browser and native HLS is unavailable.` When hls.js is unsupported but the browser plays HLS natively (such as Safari on an iPhone without Managed Media Source), the player sets the URL on the `<video>` and plays through the gateway. Quality callbacks and `getQualities()` have nothing to report there.

### Signed URL renewal [#renewal]

The player renews a signed URL when it knows the expiry and either it signed the URL itself (`client` + `assetId`) or you passed `refreshSrc`. The expiry comes from `expiresAt` of `getSignedUrl`, or from the `expires` query parameter (Unix seconds) of the URL.

| Step                                                         | Behavior                                                                                                                                   |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| When                                                         | 60 seconds before the expiry, or halfway through the URL's remaining life when that is under 2 minutes                                     |
| How                                                          | `refreshSrc(currentSrc)` for a `src`; a new `getUrl` / `getSignedUrl` call with the same `signed` and `expiresIn` for `client` + `assetId` |
| Same video, same delivery path, hls.js playing               | The player switches to the new URLs in place and keeps the buffer                                                                          |
| Native HLS, or the delivery path changed                     | The player reloads and resumes at the same position                                                                                        |
| Renewal fails                                                | Logs `Sluby: could not renew the signed playback URL.` and keeps playing until the expiry                                                  |
| Network error at most 60 seconds before the expiry, or later | The player renews instead of retrying. If that fails: `The playback URL expired and could not be renewed (<details>).`                     |

Direct-from-Sia playback from `client` + `assetId` does not depend on the signed URL's expiry: the session renews its share map on its own.

## Delivery [#delivery]

A load uses Sia only when there is a viewer session (`client.sia`) and hls.js runs in the browser. [Playback and delivery](/developers/concepts/playback) explains the three modes.

| Condition                                                      | `onDeliveryChange` | Loader                                                                                                    |
| -------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------- |
| Session, `siaDelivery="direct"`, `session.prepare()` succeeded | `'sia'`            | [`createSiaLoader`](#createsialoader): every playlist and segment from Sia                                |
| Session, `siaDelivery="direct"`, `session.prepare()` failed    | `'gateway'`        | hls.js's HTTP loader. The console shows `Sluby: direct-from-Sia delivery unavailable, using the gateway.` |
| Session, `siaDelivery="hybrid"`                                | `'hybrid'`         | [`createHybridLoader`](#createhybridloader): starts on the gateway without waiting for the session        |
| No session, or `src` without `assetId`                         | `'gateway'`        | hls.js's HTTP loader                                                                                      |
| Native HLS                                                     | `'gateway'`        | The browser                                                                                               |

## Handle [#handle]

```ts
interface SlubyPlayerHandle {
  getVideoElement: () => HTMLVideoElement | null;
  getHlsInstance: () => Hls | null;
  getQualities: () => QualityLevel[];
  setQuality: (levelIndex: number) => void;
  isAutoQuality: () => boolean;
}
```

| Method                   | Returns                                                                                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `getVideoElement()`      | The `<video>`, or `null` before mount                                                                                                                                                                  |
| `getHlsInstance()`       | The current hls.js instance, or `null` on native HLS. The player creates a new instance for every load (another video, a retry), so read it when you need it. A renewed signed URL keeps the instance. |
| `getQualities()`         | The renditions of the loaded manifest. Empty on native HLS.                                                                                                                                            |
| `setQuality(levelIndex)` | Pins the rendition with that `index`. `-1`, or any index out of range, goes back to adaptive.                                                                                                          |
| `isAutoQuality()`        | Whether hls.js picks the rendition. `true` when there is no hls.js instance.                                                                                                                           |

## useVideo [#usevideo]

```ts
function useVideo(player: RefObject<SlubyPlayerHandle | null>): UseVideoReturn;
function useVideo(
  videoRef: RefObject<HTMLVideoElement | null>,
  hlsRef: RefObject<Hls | null>,
): UseVideoReturn;
```

A headless hook for custom controls. Pass the ref of a `SlubyPlayer`, or a `<video>` ref and an hls.js instance ref for a player of your own. The hook follows the element once it mounts and every hls.js instance attached to it.

```tsx
import { useRef } from 'react';
import { SlubyPlayer, useVideo, type SlubyPlayerHandle } from '@sluby/player';

function Player({ src }: { src: string }) {
  const player = useRef<SlubyPlayerHandle>(null);
  const video = useVideo(player);
  return (
    <>
      <SlubyPlayer ref={player} src={src} controls={false} />
      <button onClick={video.isPlaying ? video.pause : video.play}>
        {video.isPlaying ? 'Pause' : 'Play'}
      </button>
    </>
  );
}
```

| Member           | Type                           | Behavior                                                                                                |
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `play`           | `() => void`                   | Calls `video.play()`. A rejection, such as an autoplay block, is ignored and `isPlaying` stays `false`. |
| `pause`          | `() => void`                   | Pauses                                                                                                  |
| `seek`           | `(time: number) => void`       | Seeks to `time` seconds, clamped to 0 and, once known, the duration                                     |
| `setQuality`     | `(levelIndex: number) => void` | Same as the handle's `setQuality`                                                                       |
| `setVolume`      | `(vol: number) => void`        | Sets the volume, clamped to 0 to 1. `0` also mutes, and any other value unmutes.                        |
| `qualities`      | `QualityLevel[]`               | The renditions, empty until the manifest is parsed                                                      |
| `currentQuality` | `QualityLevel \| null`         | The playing rendition                                                                                   |
| `duration`       | `number`                       | Seconds, `0` while unknown                                                                              |
| `currentTime`    | `number`                       | Seconds                                                                                                 |
| `isPlaying`      | `boolean`                      |                                                                                                         |
| `isBuffering`    | `boolean`                      | `true` after `waiting`, `false` after `playing`, `canplay` or `seeked`                                  |
| `volume`         | `number`                       | `0` when muted. Starts at `1`.                                                                          |

The hook updates from `<video>` events and hls.js events; it runs no timer.

## @sluby/player/hls [#hls-entry]

The loaders that `SlubyPlayer` uses, for apps that create hls.js themselves. Each returns a loader class for hls.js's `loader` config option.

### createSiaLoader [#createsialoader]

```ts
function createSiaLoader(
  session: SiaPlaybackSession,
  assetId: string,
  source?: SiaShareSource,
): { new (config: HlsConfig): Loader<LoaderContext> };
```

```ts
import Hls from 'hls.js';
import { createSiaLoader } from '@sluby/player/hls';

const src = client.playback.streamUrl(assetId);
await client.sia!.prepare(assetId, { src });
const hls = new Hls({ loader: createSiaLoader(client.sia!, assetId, { src }) });
hls.attachMedia(video);
hls.loadSource(src);
```

| Behavior      | Detail                                                                                                                                                                                                                                              |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URLs it loads | `.../v1/objects/{id}` (the loader reads the object id from the path) and `.../v1/stream/{id}/master.m3u8` (the master object id comes from `session.masterObjectId`). Any other URL fails with status 400 and `SiaLoader: no object id in "<url>"`. |
| `source`      | `{ src }` with the playback URL hls.js loads: the share map comes from the public share endpoint for it, with no API key. Leave it out to use the authenticated API route.                                                                          |
| Byte ranges   | Honored. The loader reads a segment without a range whole.                                                                                                                                                                                          |
| Timeouts      | hls.js's `loadPolicy.maxLoadTimeMs`                                                                                                                                                                                                                 |
| Failures      | A session error with a `statusCode` from 400 to 499 goes to hls.js with that status, which hls.js's default retry policy does not retry. Any other failure goes to hls.js with status 502, which that policy retries.                               |

A `/v1/stream/...` URL with a session that has no `masterObjectId` fails with status 502 and `SiaLoader: this session cannot resolve a /v1/stream master url; use a SlubyClient session or play the /v1/objects/{id} master url`.

### createHybridLoader [#createhybridloader]

```ts
function createHybridLoader(options: HybridLoaderOptions): {
  new (config: HlsConfig): Loader<LoaderContext>;
};

interface HybridLoaderOptions {
  session: SiaPlaybackSession;
  assetId: string;
  source?: SiaShareSource;
  media: () => HTMLMediaElement | null;
  urls?: { readonly current: Map<string, string> };
  policy?: Partial<HybridPolicy>;
  onStats?: (stats: HybridDeliveryStats) => void;
}
```

| Option                         | Behavior                                                                                                                                                 |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session`, `assetId`, `source` | As for `createSiaLoader`                                                                                                                                 |
| `media`                        | Returns the element hls.js feeds. The loader reads how much is buffered ahead of the playhead.                                                           |
| `urls`                         | Current gateway URL per object, keyed by URL without its query. Requests go to these URLs when set. `SlubyPlayer` uses it to renew signed URLs in place. |
| `policy`                       | Merged over [`DEFAULT_HYBRID_POLICY`](#hybrid-types)                                                                                                     |
| `onStats`                      | Called after every media segment with a copy of the totals                                                                                               |

The loader extends hls.js's default loader:

- Playlists, keys and anything that is not a media segment with a `/v1/objects/` id go through the gateway.
- A media segment comes from Sia only when no other Sia read is running, Sia is not paused, a 1-byte warm-up read of that object succeeded, and at least `minBufferSec` seconds are buffered ahead. Otherwise it comes from the gateway.
- A Sia read gets `min(maxSiaWaitMs, (bufferAhead - safetyMarginSec) × 1000)` milliseconds. When it fails or runs out of time, the gateway fetches the segment and the segment counts as a fallback.
- `maxFailures` failed reads in a row, warm-up reads included, pause Sia for `pauseMs`. A successful segment read resets the count.
- When `session.prepare()` fails, the console shows `Sluby: Sia is unavailable for now, playing through the gateway.` and Sia is paused for `pauseMs`, then tried again.

Every loader of one class shares the same state (warm objects, failures, totals). Create a new class for every hls.js instance.

### HybridPolicy and HybridDeliveryStats [#hybrid-types]

| `HybridPolicy` field | `DEFAULT_HYBRID_POLICY` | Meaning                                                                                    |
| -------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
| `minBufferSec`       | `10`                    | Seconds buffered ahead before a segment can come from Sia                                  |
| `safetyMarginSec`    | `4`                     | Seconds of buffer kept in hand: a Sia read is cut off while this much is left              |
| `maxSiaWaitMs`       | `20000`                 | Longest single Sia read, in milliseconds                                                   |
| `maxFailures`        | `3`                     | Failed or cut-off Sia reads in a row, warm-up reads included, before the loader pauses Sia |
| `pauseMs`            | `60000`                 | How long Sia stays paused, in milliseconds                                                 |

| `HybridDeliveryStats` field | Meaning                                                     |
| --------------------------- | ----------------------------------------------------------- |
| `siaBytes`                  | Media bytes read from Sia hosts                             |
| `gatewayBytes`              | Media bytes fetched through the gateway, fallbacks included |
| `siaSegments`               | Segments read from Sia                                      |
| `gatewaySegments`           | Segments fetched through the gateway                        |
| `fallbacks`                 | Segments Sia started but the gateway delivered              |

The totals count the media segments of one load and leave out playlists.

## Types [#types]

### QualityLevel [#qualitylevel]

| Field             | Type     | Value                                                                                                                                                                                                   |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `index`           | `number` | The hls.js level index, the value `setQuality` takes                                                                                                                                                    |
| `width`, `height` | `number` | Pixels                                                                                                                                                                                                  |
| `bitrate`         | `number` | The rendition's `BANDWIDTH` in the manifest, in bits per second                                                                                                                                         |
| `name`            | `string` | The shorter side plus `p`, so a 720 × 1280 portrait rendition is `720p`, the same as a 1280 × 720 landscape one. `SlubyPlayer` callbacks, `getQualities()` and `useVideo` name renditions the same way. |

### TextTrackSource [#texttracksource]

| Field     | Type                        | Value                                           |
| --------- | --------------------------- | ----------------------------------------------- |
| `src`     | `string`                    | URL of a WebVTT file                            |
| `kind`    | `'subtitles' \| 'captions'` |                                                 |
| `srclang` | `string`                    | BCP 47 language tag, such as `en`               |
| `label`   | `string`                    | The name shown in the track menu                |
| `default` | `boolean`                   | Show this track unless the viewer picks another |

### PlaybackResolver and SiaPlaybackClient [#playbackresolver]

Structural types, so the player has no hard dependency on `@sluby/sdk`. A `SlubyClient` fits both.

```ts
interface SiaPlaybackClient {
  sia?: SiaPlaybackSession;
}

interface PlaybackResolver extends SiaPlaybackClient {
  playback: {
    getUrl(assetId: string): Promise<{
      playbackUrl: string;
      posterUrl: string | null;
      accessTier?: 'public' | 'private';
    }>;
    getSignedUrl(
      assetId: string,
      options?: { expiresIn?: number },
    ): Promise<{ signedUrl: string; expiresAt?: string; posterUrl?: string | null }>;
  };
}
```

### SiaPlaybackSession and SiaShareSource [#sia-session-types]

```ts
interface SiaShareSource {
  src?: string;
}

interface SiaPlaybackSession {
  prepare(assetId: string, source?: SiaShareSource): Promise<void>;
  resolveObjectId(assetId: string, objectId: string, source?: SiaShareSource): Promise<unknown>;
  download(object: unknown, options?: { offset?: number; length?: number }): ReadableStream;
  masterObjectId?(assetId: string, source?: SiaShareSource): Promise<string>;
}
```

The SDK's [`SiaSession`](/developers/reference/sdk#sia) (`client.sia`) implements it. `masterObjectId` is needed only to play a `/v1/stream/{id}/master.m3u8` URL.

## Overlay markup [#overlay]

The built-in overlay renders no `<style>` element, so it needs no `style-src 'unsafe-inline'` in a Content Security Policy. The spinner turns through the Web Animations API, slower under `prefers-reduced-motion`. Style the overlay with these attributes:

| Selector                         | Element                                                          |
| -------------------------------- | ---------------------------------------------------------------- |
| `[data-sluby-overlay="loading"]` | The loading overlay, `role="status"`                             |
| `[data-sluby-overlay="error"]`   | The error overlay with the message and **Retry**, `role="alert"` |
| `[data-sluby-spinner]`           | The spinner                                                      |


# @sluby/sdk reference (/developers/reference/sdk)

`@sluby/sdk` is the TypeScript client for the Sluby REST API. It wraps every request in typed methods, uploads files over tus, verifies webhook signatures and opens the browser session that streams video straight from Sia. For a walkthrough, start with [Upload videos from your app](/developers/guides/upload).

## Install [#install]

```bash
npm install @sluby/sdk
```

## Package [#package]

| Fact           | Value                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| Version        | This page describes `@sluby/sdk` 0.2.1                                                                     |
| Module formats | ESM (`import`) and CommonJS (`require`), each with its own type declarations                               |
| Entry points   | One: `@sluby/sdk`. There are no subpath exports.                                                           |
| Node.js        | `^20.16.0 \|\| >=22.3.0` (the `engines` field)                                                             |
| Browsers       | Every REST method, uploads and `verifyRequestAsync` run in a browser. `client.sia` runs only in a browser. |
| HTTP           | The global `fetch`. There is no option to pass your own.                                                   |
| Dependencies   | `tus-js-client` for uploads, `@siafoundation/sia-storage` for direct-from-Sia playback                     |
| Side effects   | None (`"sideEffects": false`)                                                                              |

The Sia storage SDK is a WebAssembly module. The client imports it the first time `client.sia` connects (`connect()`, `prepare()` or `resolveObjectId()`), so code that never touches `client.sia` never loads it.

## SlubyConfig [#slubyconfig]

```ts
interface SlubyConfig {
  baseUrl: string;
  apiKey?: string;
  credentials?: RequestCredentials;
  deliveryBaseUrl?: string;
  sia?: SiaViewerConfig;
  timeoutMs?: number;
}
```

| Option            | Type                 | Default   | Behavior                                                                                                                                                                                                                                                           |
| ----------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `baseUrl`         | `string`             | required  | The origin of your Sluby server, such as `https://sluby.example.com`. The SDK appends the `/api/v1/...` paths and removes trailing slashes.                                                                                                                        |
| `apiKey`          | `string`             | none      | Sent as `Authorization: Bearer <apiKey>` on every API request and every upload request. The public share map request of `client.sia` never carries it. Leave it out in a browser app on the same origin as the API: requests then carry the Studio session cookie. |
| `credentials`     | `RequestCredentials` | not set   | Passed to `fetch` for API requests. With `'include'`, uploads also send cookies cross-origin. Set it only when a cookie session crosses origins.                                                                                                                   |
| `deliveryBaseUrl` | `string`             | `baseUrl` | The origin the SDK resolves playback URLs against: `playback.streamUrl`, `playback.getUrl`, `playback.getSignedUrl` and relative `src` values in `client.sia`. The SDK removes trailing slashes.                                                                   |
| `sia`             | `SiaViewerConfig`    | none      | The viewer identity for direct-from-Sia playback. When set, `client.sia` is a [`SiaSession`](#sia). When not set, `client.sia` is `undefined`.                                                                                                                     |
| `timeoutMs`       | `number`             | none      | Rejects any API request that has not finished, headers and body, within this many milliseconds, with a [`TimeoutError`](#errors). It does not apply to uploads.                                                                                                    |

The constructor throws an `Error` when:

| Condition                                  | Message                                                                                |
| ------------------------------------------ | -------------------------------------------------------------------------------------- |
| `apiKey` is set to an empty string         | `SlubyClient apiKey must be non-empty when provided; omit it to use a cookie session.` |
| `baseUrl` is empty                         | `SlubyClient requires a non-empty baseUrl.`                                            |
| `timeoutMs` is not a finite number above 0 | `SlubyClient timeoutMs must be a positive number of milliseconds.`                     |

### SiaViewerConfig [#siaviewerconfig]

The publishable, low-privilege Sia identity a browser uses to download shared objects. [Stream from Sia in the browser](/self-hosting/direct-playback) shows how to create one.

| Field         | Type     | Default                              | Behavior                                                          |
| ------------- | -------- | ------------------------------------ | ----------------------------------------------------------------- |
| `indexerUrl`  | `string` | required                             | The indexer the viewer connects to, such as `https://sia.storage` |
| `appId`       | `string` | required                             | 32 bytes as 64 hex characters, with or without `0x`               |
| `appKey`      | `string` | required                             | 32 bytes as 64 hex characters, with or without `0x`               |
| `name`        | `string` | `Sluby Player`                       | App name shown to the indexer                                     |
| `description` | `string` | `Sluby direct-from-Sia video player` | App description shown to the indexer                              |
| `serviceUrl`  | `string` | `indexerUrl`                         | App service URL shown to the indexer                              |

## SlubyClient [#slubyclient]

```ts
import { SlubyClient } from '@sluby/sdk';

const client = new SlubyClient({
  baseUrl: 'https://sluby.example.com',
  apiKey: process.env.SLUBY_API_KEY,
  timeoutMs: 30_000,
});
```

| Member                          | Type                            | Purpose                                                                                       |
| ------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
| `uploads`                       | `UploadManager`                 | [Upload files, read and cancel upload sessions](#uploads)                                     |
| `assets`                        | `AssetManager`                  | [List, read, edit, retry, delete and wait for videos](#assets)                                |
| `playback`                      | `PlaybackManager`               | [Public and signed playback URLs](#playback)                                                  |
| `playbackIds`                   | `PlaybackIdManager`             | [`pb_...` playback ids](#playback-ids)                                                        |
| `keys`                          | `KeyManager`                    | [API keys](#keys)                                                                             |
| `sessions`                      | `SessionManager`                | [Signed-in Studio browsers](#sessions)                                                        |
| `reconciliation`                | `ReconciliationManager`         | [The storage check](#reconciliation)                                                          |
| `webhookEndpoints`              | `WebhookEndpointManager`        | [Register and manage webhook endpoints](#webhook-endpoints)                                   |
| `webhooks`                      | `WebhookManager`                | [Verify and parse incoming webhooks](#webhooks)                                               |
| `sia`                           | `SiaSession \| undefined`       | [Direct-from-Sia viewer session](#sia), present only with `config.sia`                        |
| `resolveDeliveryUrl(pathOrUrl)` | `(pathOrUrl: string) => string` | Returns an absolute `http(s)` URL unchanged and prefixes anything else with `deliveryBaseUrl` |

### Request behavior [#request-behavior]

- Request bodies go out with the API's snake_case field names. Responses come back mapped to the camelCase types on this page.
- Every method that takes `options` accepts `signal?: AbortSignal`. When the signal fires, the call rejects with an [`AbortError`](#errors) whose `cause` is the signal's reason.
- The SDK reads the whole response body before it resolves, so `signal` and `timeoutMs` cover the body too.
- A response outside 200 to 299 rejects with the [error class for its status](#errors).
- A network failure rejects with the `TypeError` that `fetch` threw, not a `SlubyError`.
- The SDK does not retry REST requests. Uploads retry on their own (see `retryDelays` in [UploadFileOptions](#uploadfileoptions)).

The endpoint decides which [scope](/developers/reference/api-conventions#scopes) a request needs. Each method below links to its endpoint page.

## client.uploads [#uploads]

```ts
class UploadManager {
  upload(file: UploadInput, options: UploadOptions): AssetUploadHandle;
  getStatus(uploadId: string, options?: RequestOptions): Promise<UploadSession>;
  cancel(uploadId: string, options?: RequestOptions): Promise<void>;
}

type UploadInput = Blob | Uint8Array;
```

| Method      | Request                                                                                                                                                                            | Returns                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `upload`    | tus upload to [`POST /api/v1/uploads`](/developers/reference/api/uploads/post-uploads), then [`PATCH`](/developers/reference/api/uploads/patch-uploads-id) requests for the chunks | An [`AssetUploadHandle`](#assetuploadhandle) right away, without waiting |
| `getStatus` | [`GET /api/v1/uploads/{uploadId}`](/developers/reference/api/uploads/get-uploads-id)                                                                                               | `UploadSession`                                                          |
| `cancel`    | [`DELETE /api/v1/uploads/{uploadId}`](/developers/reference/api/uploads/delete-uploads-id)                                                                                         | Nothing                                                                  |

`upload()` takes a `File` or `Blob` in the browser, and a `Buffer`, `Uint8Array` or `Blob` (for example from `fs.openAsBlob`) in Node.js. It does not take Node.js streams. Each call creates one video asset, unless it resumes an unfinished upload (see `resume` below). The upload runs as a single tus stream.

### UploadOptions [#uploadoptions]

`UploadOptions` is [`UploadFileOptions`](#uploadfileoptions) plus the fields of the new video. The SDK sends them as tus metadata.

| Field         | Type                    | Default    | tus metadata key |
| ------------- | ----------------------- | ---------- | ---------------- |
| `title`       | `string`                | required   | `title`          |
| `description` | `string`                | `''`       | `description`    |
| `accessTier`  | `'public' \| 'private'` | `'public'` | `accessTier`     |

The SDK also sends `filename` (the `File`'s name, or `video`) and `filetype` (the `Blob`'s type, or an empty string).

### UploadFileOptions [#uploadfileoptions]

| Field         | Type                                                                   | Default                 | Behavior                                                                                                                                                                                                    |
| ------------- | ---------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chunkSize`   | `number`                                                               | `10485760` (10 MiB)     | Bytes per tus `PATCH` request                                                                                                                                                                               |
| `retryDelays` | `number[]`                                                             | `[0, 1000, 3000, 5000]` | Milliseconds to wait before each tus retry                                                                                                                                                                  |
| `onProgress`  | `(percent: number, bytesUploaded: number, bytesTotal: number) => void` | none                    | `percent` is `Math.round(bytesUploaded / bytesTotal * 100)`. Not called while `bytesTotal` is 0.                                                                                                            |
| `onSuccess`   | `() => void`                                                           | none                    | Called once when every byte is uploaded                                                                                                                                                                     |
| `onError`     | `(error: Error) => void`                                               | none                    | Called with the same `SlubyError` the handle rejects with                                                                                                                                                   |
| `resume`      | `boolean`                                                              | `true`                  | In a browser, resumes an unfinished upload of the same file, with the same metadata, by the same key, from an earlier page load. A finished upload is never resumed. A `Uint8Array` input is never resumed. |
| `signal`      | `AbortSignal`                                                          | none                    | Aborts the upload like `handle.abort()`                                                                                                                                                                     |

Before it resumes a stored upload, the SDK sends a `HEAD` to it and resumes only when the server reports `Upload-Offset` below `Upload-Length`.

### AssetUploadHandle [#assetuploadhandle]

```ts
type AssetUploadHandle = Promise<void> & {
  assetId: Promise<string>;
  uploadId: Promise<string>;
  pause: () => Promise<void>;
  resume: () => void;
  abort: () => Promise<void>;
  readonly isPaused: boolean;
};
```

| Member         | Behavior                                                                                                                                                                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `await handle` | Resolves when every byte is uploaded. Processing then continues on the server: use [`assets.waitForReady`](#assets) to wait for it.                                                                                                                |
| `assetId`      | The id of the asset the upload created, available as soon as the server creates the upload                                                                                                                                                         |
| `uploadId`     | The last path segment of the tus upload URL, the id `getStatus` and `cancel` take                                                                                                                                                                  |
| `pause()`      | Stops sending and keeps the partial upload                                                                                                                                                                                                         |
| `resume()`     | Continues a paused upload from where it stopped                                                                                                                                                                                                    |
| `abort()`      | Stops sending, terminates the upload on the server (which discards the asset it created) and rejects the handle, `assetId` and `uploadId` (those not yet settled) with `AbortError('Upload aborted.')`. Does nothing once the upload has finished. |
| `isPaused`     | Whether the upload is paused                                                                                                                                                                                                                       |

The handle, `assetId` and `uploadId` reject with the [error class](#errors) for the HTTP status of a failed tus request (the tus error is on `cause`), or with a `SlubyError` whose message starts with `Upload failed:` for any other failure.

## client.assets [#assets]

```ts
class AssetManager {
  list(options?: ListAssetsOptions): Promise<PaginatedResponse<VideoAsset>>;
  get(videoAssetId: string, options?: RequestOptions): Promise<VideoAsset>;
  update(
    videoAssetId: string,
    data: Partial<Pick<VideoAsset, 'title' | 'description' | 'accessTier'>>,
    options?: RequestOptions & { ifMatch?: VideoAsset | string },
  ): Promise<VideoAsset>;
  delete(videoAssetId: string, options?: RequestOptions): Promise<void>;
  processing(videoAssetId: string, options?: RequestOptions): Promise<ProcessingJob>;
  renditions(videoAssetId: string, options?: RequestOptions): Promise<Rendition[]>;
  retry(videoAssetId: string, options?: RequestOptions): Promise<{ stage: RetryStage }>;
  stats(options?: RequestOptions): Promise<AssetStats>;
  usage(options?: RequestOptions & { days?: number }): Promise<UsageReport>;
  waitForReady(
    videoAssetId: string,
    options?: { pollInterval?: number; timeout?: number; signal?: AbortSignal },
  ): Promise<VideoAsset>;
}

function assetEtag(asset: Pick<VideoAsset, 'updatedAt'>): string;
```

| Method         | Request                                                                                                      | Returns                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `list`         | [`GET /api/v1/assets`](/developers/reference/api/assets/get-assets)                                          | One page of assets with `total`, `page`, `limit`, `nextCursor` and `hasMore` |
| `get`          | [`GET /api/v1/assets/{id}`](/developers/reference/api/assets/get-assets-id)                                  | `VideoAsset`                                                                 |
| `update`       | [`PATCH /api/v1/assets/{id}`](/developers/reference/api/assets/patch-assets-id)                              | The updated `VideoAsset`                                                     |
| `delete`       | [`DELETE /api/v1/assets/{id}`](/developers/reference/api/assets/delete-assets-id)                            | Nothing                                                                      |
| `processing`   | [`GET /api/v1/assets/{id}/processing`](/developers/reference/api/assets/get-assets-id-processing)            | `ProcessingJob`: stage, percent, error and log lines                         |
| `renditions`   | [`GET /api/v1/assets/{id}/renditions`](/developers/reference/api/assets/get-assets-id-renditions)            | `Rendition[]`, tallest first, empty until the asset is ready                 |
| `retry`        | [`POST /api/v1/assets/{id}/retry`](/developers/reference/api/assets/post-assets-id-retry)                    | The stage processing restarted from: `'transcode'` or `'upload-segments'`    |
| `stats`        | [`GET /api/v1/stats`](/developers/reference/api/ops/get-stats)                                               | `AssetStats`. `byStatus` has every status, 0 when none.                      |
| `usage`        | [`GET /api/v1/stats/usage`](/developers/reference/api/ops/get-stats-usage), with `?days=` when `days` is set | `UsageReport`: plays per UTC day                                             |
| `waitForReady` | Repeated `get`                                                                                               | The asset once its status is `ready`                                         |

### update and If-Match [#update-if-match]

Pass `ifMatch` to apply the edit only if nobody changed the asset since you read it. Pass the asset as you read it, or an ETag string. `assetEtag(asset)` builds the ETag the server uses: `asset.updatedAt` in milliseconds since the epoch, in double quotes. It throws a `TypeError` when `updatedAt` is not a date.

When the asset changed, `update` rejects with a `ConflictError` whose `statusCode` is `412` and whose `current` is the asset as the server has it now.

```ts
import { ConflictError } from '@sluby/sdk';

try {
  await client.assets.update(asset.id, { title: 'New title' }, { ifMatch: asset });
} catch (err) {
  if (err instanceof ConflictError && err.current) {
    // the asset changed on the server; err.current is the version there now
  }
}
```

### waitForReady [#waitforready]

| Option         | Default               | Behavior                                                                                                                                           |
| -------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pollInterval` | `5000`                | Milliseconds between reads                                                                                                                         |
| `timeout`      | `600000` (10 minutes) | Longest wait in milliseconds. The asset is read at least once, even with `timeout: 0`.                                                             |
| `signal`       | none                  | Stops polling and rejects with an `AbortError`: `Stopped waiting: the signal was aborted.` between reads, `The request was aborted.` during a read |

| Outcome         | Result                                                                                             |
| --------------- | -------------------------------------------------------------------------------------------------- |
| Status `ready`  | Resolves with the asset                                                                            |
| Status `failed` | Rejects with `ProcessingFailedError`, whose `asset` is the asset as last read                      |
| Timeout         | Rejects with `TimeoutError('Timed out after <timeout>ms waiting for asset <id> to become ready.')` |

### ListAssetsOptions [#listassetsoptions]

| Field        | Type                                              | Query parameter | Behavior                                                                                         |
| ------------ | ------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `page`       | `number`                                          | `page`          | Page number                                                                                      |
| `limit`      | `number`                                          | `limit`         | Assets per page                                                                                  |
| `cursor`     | `string`                                          | `cursor`        | The `nextCursor` of the previous page. Works only with the default order (`created_at`, `desc`). |
| `status`     | `VideoAssetStatus`                                | `status`        | Only assets in this status                                                                       |
| `accessTier` | `'public' \| 'private'`                           | `access_tier`   | Only assets with this tier                                                                       |
| `search`     | `string`                                          | `search`        | Case-insensitive match on title or description, or an exact asset id                             |
| `sort`       | `'created_at' \| 'title' \| 'duration' \| 'size'` | `sort`          | Default `created_at`                                                                             |
| `order`      | `'asc' \| 'desc'`                                 | `order`         | Default `desc`                                                                                   |

Defaults and limits for `page` and `limit` are on the [endpoint page](/developers/reference/api/assets/get-assets).

## client.playback [#playback]

```ts
class PlaybackManager {
  streamUrl(idOrPlaybackId: string): string;
  getUrl(videoAssetId: string, options?: RequestOptions): Promise<PlaybackInfo>;
  getSignedUrl(
    videoAssetId: string,
    options?: { expiresIn?: number; signal?: AbortSignal },
  ): Promise<SignedPlaybackInfo>;
  revokeSignedUrls(videoAssetId: string, options?: RequestOptions): Promise<SignedUrlRevocation>;
}
```

| Method             | Request                                                                                                                                                   | Returns                                                                                  |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `streamUrl`        | None. It builds the URL of [`GET /v1/stream/{id}/master.m3u8`](/developers/reference/api/delivery/get-stream-videoassetid-master-m3u8) without a request. | `<deliveryBaseUrl>/v1/stream/<id>/master.m3u8` for an asset id or a `pb_...` playback id |
| `getUrl`           | [`GET /api/v1/playback/{id}`](/developers/reference/api/playback/get-playback-id)                                                                         | `PlaybackInfo`                                                                           |
| `getSignedUrl`     | [`GET /api/v1/playback/{id}/signed`](/developers/reference/api/playback/get-playback-id-signed), with `?expires_in=` when `expiresIn` is set              | `SignedPlaybackInfo`                                                                     |
| `revokeSignedUrls` | [`POST /api/v1/playback/{id}/signed/revoke`](/developers/reference/api/playback/post-playback-id-signed-revoke). Needs the `manage` scope.                | `SignedUrlRevocation`: `{ signingGeneration: number }`, the asset's new generation       |

`getSignedUrl` rejects with a `RangeError` before sending anything when `expiresIn` is not a whole number above 0. Without `expiresIn` the server's default lifetime applies; [Playback and delivery](/developers/concepts/playback) has the default and the maximum.

| `PlaybackInfo` field | Type                    | Value                                                            |
| -------------------- | ----------------------- | ---------------------------------------------------------------- |
| `playbackUrl`        | `string`                | Absolute master manifest URL, resolved against `deliveryBaseUrl` |
| `playbackPath`       | `string`                | The server-relative path the API returned                        |
| `posterUrl`          | `string \| null`        | Absolute poster URL, `null` when the asset has no thumbnail      |
| `durationMs`         | `number \| null`        | Duration                                                         |
| `resolution`         | `string \| null`        | Source resolution such as `1920x1080`                            |
| `accessTier`         | `'public' \| 'private'` | The asset's tier                                                 |

| `SignedPlaybackInfo` field | Type             | Value                                                                      |
| -------------------------- | ---------------- | -------------------------------------------------------------------------- |
| `signedUrl`                | `string`         | Absolute signed master manifest URL, resolved against `deliveryBaseUrl`    |
| `signedPath`               | `string`         | The server-relative signed path the API returned                           |
| `posterUrl`                | `string \| null` | The first thumbnail, signed until the same time, `null` when there is none |
| `expiresAt`                | `string`         | ISO 8601 time the signed URL stops working                                 |

## client.playbackIds [#playback-ids]

```ts
class PlaybackIdManager {
  list(videoAssetId: string, options?: RequestOptions): Promise<PlaybackId[]>;
  create(
    videoAssetId: string,
    input?: CreatePlaybackIdInput,
    options?: RequestOptions,
  ): Promise<PlaybackId>;
  delete(playbackId: string, options?: RequestOptions): Promise<void>;
}

interface CreatePlaybackIdInput {
  policy?: 'public' | 'signed'; // default 'public'
  name?: string;
}
```

| Method   | Request                                                                                                                                 | Returns              |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `list`   | [`GET /api/v1/assets/{id}/playback-ids`](/developers/reference/api/playback/get-assets-id-playback-ids)                                 | `PlaybackId[]`       |
| `create` | [`POST /api/v1/assets/{id}/playback-ids`](/developers/reference/api/playback/post-assets-id-playback-ids)                               | The new `PlaybackId` |
| `delete` | [`DELETE /api/v1/playback-ids/{playbackId}`](/developers/reference/api/playback/delete-playback-ids-playbackid), by the `pb_...` handle | Nothing              |

`PlaybackId` has `id` (the record id), `playbackId` (the `pb_...` handle to use in playback URLs), `policy`, `name` (empty string when none was given) and `createdAt`.

## client.keys [#keys]

```ts
class KeyManager {
  list(options?: ListApiKeysOptions): Promise<ApiKeyPage>;
  create(input: CreateApiKeyInput, options?: RequestOptions): Promise<CreatedApiKey>;
  update(keyId: string, input: { name: string }, options?: RequestOptions): Promise<ApiKey>;
  rotate(
    keyId: string,
    options?: { gracePeriodSeconds?: number; signal?: AbortSignal },
  ): Promise<RotatedApiKey>;
  revoke(keyId: string, options?: RequestOptions): Promise<void>;
}

interface ListApiKeysOptions extends RequestOptions {
  limit?: number;
  cursor?: string;
}

interface CreateApiKeyInput {
  name: string;
  scopes?: ApiKeyScope[];
  rateLimit?: number; // requests per minute
}
```

| Method   | Request                                                                                                                                             | Returns                                                                                            |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `list`   | [`GET /api/v1/keys`](/developers/reference/api/keys/get-keys)                                                                                       | `ApiKeyPage`: `data`, `hasMore`, `nextCursor` and `limits` (`maxKeys`, `maxRateLimit`)             |
| `create` | [`POST /api/v1/keys`](/developers/reference/api/keys/post-keys)                                                                                     | `CreatedApiKey`: the key plus its raw `key`, returned only here                                    |
| `update` | [`PATCH /api/v1/keys/{id}`](/developers/reference/api/keys/patch-keys-id)                                                                           | The renamed `ApiKey`. Secret, scopes and rate limit stay.                                          |
| `rotate` | [`POST /api/v1/keys/{id}/rotate`](/developers/reference/api/keys/post-keys-id-rotate), with `grace_period_seconds` when `gracePeriodSeconds` is set | `RotatedApiKey`: the replacement with its raw `key`, plus `rotatedFrom` and `previousKeyExpiresAt` |
| `revoke` | [`DELETE /api/v1/keys/{id}`](/developers/reference/api/keys/delete-keys-id)                                                                         | Nothing                                                                                            |

`rotate` rejects with a `ConflictError` (409) for a key that was already rotated. Rotate its replacement instead.

`ApiKey` fields: `id`, `name`, `scopes` (`'upload' | 'read' | 'manage'`, see [Scopes](/developers/reference/api-conventions#scopes)), `rateLimit` (requests per minute), `isActive`, `createdAt`, `expiresAt` (set while a rotated-out key is in its grace period, otherwise `null`), `prefix` (the first 12 characters of the key, or `null`), `lastUsedAt` and `createdBy` (`{ id, name }` of the member who made it, or `null`).

## client.sessions [#sessions]

```ts
class SessionManager {
  list(options?: RequestOptions): Promise<StudioSession[]>;
  revoke(sessionId: string, options?: RequestOptions): Promise<void>;
  revokeAll(options?: RequestOptions): Promise<{ revoked: number }>;
}
```

These methods work only with a Studio session cookie: create the client without `apiKey`. A client with an API key gets an `AuthenticationError` (401). On a server with sign-in turned off (`AUTH_DISABLED`), they reject with a `ConflictError` (409).

| Method      | Request                                                                                       | Returns                                                                             |
| ----------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `list`      | [`GET /api/v1/auth/sessions`](/developers/reference/api/auth/get-auth-sessions)               | The account's live sessions, newest first. `current` marks the one making the call. |
| `revoke`    | [`DELETE /api/v1/auth/sessions/{id}`](/developers/reference/api/auth/delete-auth-sessions-id) | Nothing. Revoking the current session also clears its cookie.                       |
| `revokeAll` | [`DELETE /api/v1/auth/sessions`](/developers/reference/api/auth/delete-auth-sessions)         | How many sessions were signed out, the current one included                         |

`StudioSession` fields: `id`, `userAgent`, `createdAt`, `expiresAt`, `lastSeenAt`, `current`.

## client.reconciliation [#reconciliation]

```ts
class ReconciliationManager {
  latest(options?: RequestOptions): Promise<ReconciliationReport>;
  run(options?: RequestOptions): Promise<ReconciliationTrigger>;
}
```

| Method   | Request                                                                                               | Returns                                                                                               |
| -------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `latest` | [`GET /api/v1/reconciliation`](/developers/reference/api/reconciliation/get-reconciliation)           | The latest finished storage check. Rejects with `NotFoundError` before the first check finishes.      |
| `run`    | [`POST /api/v1/reconciliation/run`](/developers/reference/api/reconciliation/post-reconciliation-run) | `{ enqueued, alreadyPending }`. Only an admin can run it; anyone else gets a `PermissionError` (403). |

`ReconciliationReport` is a union on `scope`:

- `scope: 'deployment'` (for an admin): the whole deployment, with `dbObjectCount`, `indexerObjectCount`, `inSyncCount`, `orphanCount`, `orphanedIds` and `errorMessage`.
- `scope: 'account'` (for a caller that is not an admin): the missing objects of the workspace's videos, without the deployment-wide counts.

Both carry `id`, `startedAt`, `finishedAt`, `createdAt`, `status` (`'ok' | 'drift' | 'failed'`), `missingCount`, `missingIds` and `missingObjects` (each `{ objectId, videoAssetId, title }`). [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation) explains the check.

## client.webhookEndpoints [#webhook-endpoints]

```ts
class WebhookEndpointManager {
  list(options?: RequestOptions): Promise<WebhookEndpoint[]>;
  get(endpointId: string, options?: RequestOptions): Promise<WebhookEndpoint>;
  create(
    input: CreateWebhookEndpointInput,
    options?: RequestOptions,
  ): Promise<CreatedWebhookEndpoint>;
  update(
    endpointId: string,
    input: UpdateWebhookEndpointInput,
    options?: RequestOptions,
  ): Promise<WebhookEndpoint>;
  delete(endpointId: string, options?: RequestOptions): Promise<void>;
  rotateSecret(
    endpointId: string,
    options?: RequestOptions,
  ): Promise<{ id: string; secret: string }>;
  test(endpointId: string, options?: RequestOptions): Promise<WebhookTestResult>;
  deliveries(
    endpointId: string,
    options?: { limit?: number; signal?: AbortSignal },
  ): Promise<WebhookDelivery[]>;
  redeliver(
    endpointId: string,
    deliveryId: string,
    options?: RequestOptions,
  ): Promise<{ deliveryId: string }>;
}

interface CreateWebhookEndpointInput {
  url: string;
  events: WebhookEventName[];
}

interface UpdateWebhookEndpointInput {
  url?: string;
  events?: WebhookEventName[]; // replaces the subscribed events
  isActive?: boolean; // false pauses the endpoint, true resumes it
}
```

| Method         | Request                                                                                                                                               | Returns                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `list`         | [`GET /api/v1/webhooks`](/developers/reference/api/webhooks/get-webhooks)                                                                             | Every endpoint, paused ones included, newest first                                           |
| `get`          | [`GET /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/get-webhooks-id)                                                                     | One endpoint, with `lastDeliveryAt` and `lastDeliveryOk`                                     |
| `create`       | [`POST /api/v1/webhooks`](/developers/reference/api/webhooks/post-webhooks)                                                                           | `CreatedWebhookEndpoint` with the signing `secret`, returned only here                       |
| `update`       | [`PATCH /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/patch-webhooks-id)                                                                 | The updated endpoint. The secret stays.                                                      |
| `delete`       | [`DELETE /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/delete-webhooks-id)                                                               | Nothing                                                                                      |
| `rotateSecret` | [`POST /api/v1/webhooks/{id}/rotate-secret`](/developers/reference/api/webhooks/post-webhooks-id-rotate-secret)                                       | The new `secret`, returned only here                                                         |
| `test`         | [`POST /api/v1/webhooks/{id}/test`](/developers/reference/api/webhooks/post-webhooks-id-test)                                                         | `WebhookTestResult`: `delivered`, `statusCode`, `error`                                      |
| `deliveries`   | [`GET /api/v1/webhooks/{id}/deliveries`](/developers/reference/api/webhooks/get-webhooks-id-deliveries), with `?limit=` when `limit` is set           | `WebhookDelivery[]`, newest first                                                            |
| `redeliver`    | [`POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver`](/developers/reference/api/webhooks/post-webhooks-id-deliveries-deliveryid-redeliver) | The id of the new delivery. Rejects with `ConflictError` (409) while the endpoint is paused. |

`WebhookDelivery` fields: `id`, `eventId`, `event`, `statusCode`, `delivered`, `error`, `attempt` (1 for the first try), `createdAt`, `payload` (the JSON body that was sent) and `manual` (`true` for a resend made with `redeliver`). [Webhook events](/developers/reference/webhook-events) describes the events, payloads and retries.

## client.webhooks [#webhooks]

```ts
class WebhookManager {
  verifyRequest(
    payload: string,
    headers: WebhookHeaders,
    secret: string,
    options?: VerifyRequestOptions,
  ): boolean;
  verifyRequestAsync(
    payload: string,
    headers: WebhookHeaders,
    secret: string,
    options?: VerifyRequestOptions,
  ): Promise<boolean>;
  verifySignature(payload: string, signature: string, secret: string): boolean;
  verifySignatureAsync(payload: string, signature: string, secret: string): Promise<boolean>;
  parseEvent(payload: string): WebhookEvent;
}

type WebhookHeaders =
  { get(name: string): string | null } | Record<string, string | string[] | undefined>;

interface VerifyRequestOptions {
  toleranceSeconds?: number; // default 300
  now?: number; // current time in Unix seconds, default the clock
}

const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
```

`WebhookManager` needs no credentials. Use it through any client, or construct it on its own with `new WebhookManager()`.

| Method                 | Runs on                                             | Behavior                                                                                                                                                          |
| ---------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verifyRequest`        | Node.js                                             | `true` when `X-Sluby-Signature-V1` is the hex HMAC-SHA256 of `<X-Sluby-Timestamp>.<payload>` under `secret` and the timestamp is within `toleranceSeconds` of now |
| `verifyRequestAsync`   | Web Crypto (browsers, edge runtimes, Deno, Node.js) | Same check as `verifyRequest`                                                                                                                                     |
| `verifySignature`      | Node.js                                             | `true` when `signature` (hex, either case) is the HMAC-SHA256 of `payload` under `secret`. Compares in constant time.                                             |
| `verifySignatureAsync` | Web Crypto                                          | Same check as `verifySignature`                                                                                                                                   |
| `parseEvent`           | Anywhere                                            | Parses the body into a `WebhookEvent`                                                                                                                             |

Details:

- Pass the raw request body as `payload`, exactly as received, before any JSON parsing.
- `headers` takes a Fetch `Headers` object or a Node.js `req.headers` record. Header names match case-insensitively, and for an array the SDK uses the first value.
- The timestamp must be 1 to 12 digits. A missing header, a malformed timestamp or one outside the tolerance returns `false`.
- `verifySignature` throws where `process.getBuiltinModule` is missing (outside Node.js): `Synchronous signature verification needs Node.js 20.16+ or 22.3+ (process.getBuiltinModule). Use verifySignatureAsync() in browser or edge environments.` `verifyRequest` throws the same error once the headers pass the timestamp checks.
- `parseEvent` throws `Invalid webhook payload: missing required "event" or "timestamp" field.` when either is not a string, and throws the `SyntaxError` of `JSON.parse` for a body that is not JSON. It keeps `id` only when it is a string and sets `data` to `{}` when it is missing.

```ts
import { WebhookManager } from '@sluby/sdk';

const webhooks = new WebhookManager();

// rawBody: the request body as a string; headers: req.headers
if (webhooks.verifyRequest(rawBody, headers, process.env.SLUBY_WEBHOOK_SECRET!)) {
  const event = webhooks.parseEvent(rawBody);
  console.log(event.id, event.event, event.data.video_asset_id);
}
```

`WebhookEvent` is `{ id?: string; event: WebhookEventName | (string & {}); timestamp: string; data: Record<string, unknown> }`. `data` keeps the snake_case keys of the payload. The headers, signature scheme and every payload are on [Webhook events](/developers/reference/webhook-events).

## client.sia [#sia]

`client.sia` is a `SiaSession` when the client was created with [`sia`](#siaviewerconfig), and `undefined` otherwise. It runs only in a browser. `@sluby/player` drives it; call it yourself only when you build your own player. [Playback and delivery](/developers/concepts/playback) explains direct-from-Sia playback.

```ts
class SiaSession {
  static readonly MAX_CACHED_OBJECTS = 64;
  constructor(fetchFn: FetchFn, config: SiaViewerConfig, transport?: SiaSessionTransport);
  connect(): Promise<void>;
  prepare(assetId: string, source?: SiaShareSource): Promise<void>;
  getShareMap(
    assetId: string,
    source?: SiaShareSource,
    options?: { renew?: boolean },
  ): Promise<SiaShareMap>;
  shareMapUrl(assetId: string, src: string): string;
  masterObjectId(assetId: string, source?: SiaShareSource): Promise<string>;
  resolveObjectId(assetId: string, objectId: string, source?: SiaShareSource): Promise<SiaObject>;
  download(object: SiaObject, options?: SiaDownloadOptions): ReadableStream;
  dispose(): void;
}

interface SiaShareSource {
  src?: string;
}

interface SiaDownloadOptions {
  offset?: number;
  length?: number;
}

function publicShareMapUrl(assetId: string, src: string): string;
```

`FetchFn` is not exported. Use the session `SlubyClient` creates rather than constructing one.

### Share map source [#share-map-source]

Every method that needs an asset's share map takes an optional `source`:

| `source`                                                                                                                                                                        | Share map request                                                                                                                   | Credentials                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `{ src }`, where `src` is the gateway playback URL being played (`/v1/stream/{id}/master.m3u8` or `/v1/objects/{id}`, signed or not, absolute or relative to `deliveryBaseUrl`) | [`GET /v1/share/{id}`](/developers/reference/api/delivery/get-share-id) on the delivery base, with the `expires` and `sig` of `src` | None, so a page without an API key can play direct from Sia |
| Not set                                                                                                                                                                         | [`GET /api/v1/playback/{id}/share`](/developers/reference/api/playback/get-playback-id-share)                                       | The client's API key or session                             |

### Methods [#sia-methods]

| Method                                        | Behavior                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connect()`                                   | Loads the WebAssembly SDK and connects to the indexer with the viewer app key. Resolves once connected; later calls reuse the connection. A failed attempt is not cached, so the next call tries again. Rejects when the app id or key is not 64 hex characters, or when the app key is not registered with the indexer.                                                               |
| `prepare(assetId, source?)`                   | `connect()`, then loads the asset's share map                                                                                                                                                                                                                                                                                                                                          |
| `getShareMap(assetId, source?, options?)`     | Fetches the share map without caching it. `renew: true` adds `renew=1` to a public request, so the server does not count another play. Rejects with a `SlubyError` when the answer has no valid `expires_at`.                                                                                                                                                                          |
| `shareMapUrl(assetId, src)`                   | The public share map URL for `src`, after resolving a relative `src` against `deliveryBaseUrl`                                                                                                                                                                                                                                                                                         |
| `masterObjectId(assetId, source?)`            | The object id of the asset's HLS master playlist, from the cached share map                                                                                                                                                                                                                                                                                                            |
| `resolveObjectId(assetId, objectId, source?)` | A downloadable handle for one object of the asset. Cached per asset and object, at most `MAX_CACHED_OBJECTS` (64), least recently used dropped first. Fetches a fresh share map once when the object is missing from it, or when its share URL fails less than 60 seconds before the map's expiry or later. Rejects with `NotFoundError` when the map has no share URL for the object. |
| `download(object, options?)`                  | A `ReadableStream` of the object's bytes from Sia, from `offset` for `length` bytes. Throws when called before the session is connected.                                                                                                                                                                                                                                               |
| `dispose()`                                   | Frees every resolved object and the WebAssembly SDK and forgets the share maps. The session stays usable: the next call connects again.                                                                                                                                                                                                                                                |

The session caches each share map per asset and source, and fetches a new one when the cached map is missing, expired, or within 60 seconds of its `expiresAt`. A map that arrived already inside those 60 seconds stays in use until it expires. A refetch of a map the session already held adds `renew=1` to a public request.

`publicShareMapUrl(assetId, src)` builds the public share map URL for an absolute `src`. The share id is the `{id}` in a `/v1/stream/{id}/master.m3u8` URL, or `assetId` for a `/v1/objects/{id}` URL. It throws when `src` is neither.

`SiaShareMap` is `{ masterObjectId: string; shares: Record<string, string>; expiresAt: string }`, where `shares` maps each object id (hex) to its `sia://` share URL.

## Errors [#errors]

Every error the SDK creates extends `SlubyError`, which extends `Error`. Check classes with `instanceof`.

| Class                   | `statusCode`        | Thrown when                                                                                                                                                                         | Extra fields                                                                           |
| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `SlubyError`            | HTTP status, or `0` | Base class. Thrown directly for a status without its own class (such as 500 or 502), for a 2xx response whose body is not JSON, and for an upload failure without an HTTP response. | `responseBody?: string`, `cause`                                                       |
| `ValidationError`       | `400` or `422`      | The request is malformed or a value is invalid                                                                                                                                      |                                                                                        |
| `AuthenticationError`   | `401`               | The key or session is missing, wrong, revoked or expired                                                                                                                            |                                                                                        |
| `PermissionError`       | `403`               | The caller is known but not allowed: a key without the needed scope, a member without the needed role, or a signed URL that is invalid or expired                                   |                                                                                        |
| `NotFoundError`         | `404` or `410`      | The resource does not exist, or no longer does (410)                                                                                                                                |                                                                                        |
| `ConflictError`         | `409` or `412`      | The resource is not in a state that allows the request (409), or an `update` with `ifMatch` found the asset changed (412)                                                           | `current?: VideoAsset` on a 412 from `assets.update`                                   |
| `RateLimitError`        | `429`               | The key or caller went over a [rate limit](/developers/reference/api-conventions#rate-limits)                                                                                       | `retryAfter?: number`, seconds from the `Retry-After` header (seconds or an HTTP date) |
| `TimeoutError`          | `0`                 | A request ran past `timeoutMs`, or `waitForReady` ran past its `timeout`                                                                                                            |                                                                                        |
| `AbortError`            | `0`                 | A `signal` fired, or `abort()` was called on an upload. `name` is `'AbortError'`, like the DOM's.                                                                                   | `cause`: the signal's reason                                                           |
| `ProcessingFailedError` | `0`                 | `waitForReady` read the asset as `failed`                                                                                                                                           | `asset: VideoAsset`                                                                    |

The `message` of an HTTP error is the `error` string of a JSON body, else its `message` string. For a body that is not JSON, it is the trimmed body text when that is one line under 200 characters and does not start with `<`. Otherwise it is the HTTP status text, else `Unknown API error`. The raw body is on `responseBody`. [Errors in API conventions](/developers/reference/api-conventions#errors) describes the error body the API sends.

A network failure is not a `SlubyError`: the SDK rethrows the `TypeError` from `fetch`. A `statusCode` of `0` marks an error raised in the client, not by the server.

```ts
import { SlubyError, RateLimitError } from '@sluby/sdk';

try {
  await client.assets.list();
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`retry in ${err.retryAfter ?? 60} s`);
  } else if (err instanceof SlubyError) {
    console.log(err.name, err.statusCode, err.message);
  } else {
    throw err; // a network failure from fetch
  }
}
```

## Types [#types]

Every type below is exported from `@sluby/sdk` as a type.

### VideoAsset [#videoasset]

| Field                | Type               | Notes                                                             |
| -------------------- | ------------------ | ----------------------------------------------------------------- |
| `id`                 | `string`           |                                                                   |
| `title`              | `string`           |                                                                   |
| `description`        | `string`           |                                                                   |
| `manifestObjectId`   | `string \| null`   | `null` until processing finishes                                  |
| `thumbnailObjectIds` | `string[]`         |                                                                   |
| `durationMs`         | `number \| null`   | `null` or `0` until processing has probed the source              |
| `resolution`         | `string \| null`   | Source resolution such as `1920x1080`                             |
| `status`             | `VideoAssetStatus` | `'created' \| 'uploading' \| 'processing' \| 'ready' \| 'failed'` |
| `accessTier`         | `AccessTier`       | `'public' \| 'private'`                                           |
| `creatorAddress`     | `string`           |                                                                   |
| `segmentCount`       | `number`           |                                                                   |
| `totalStorageBytes`  | `number`           |                                                                   |
| `playCount`          | `number`           | All-time plays                                                    |
| `lastPlayedAt`       | `string \| null`   | `null` before the first play                                      |
| `createdAt`          | `string`           |                                                                   |
| `updatedAt`          | `string`           | Also the asset's version for [`ifMatch`](#update-if-match)        |

### ProcessingJob [#processingjob]

| Field                      | Type                                                                | Notes                                                                          |
| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `id`                       | `string`                                                            |                                                                                |
| `status`                   | `'queued' \| 'processing' \| 'completed' \| 'failed' \| 'retrying'` | `retrying` means a failed attempt is queued again                              |
| `stage`                    | `ProcessingStage`                                                   | `'queued' \| 'transcode' \| 'upload' \| 'finalize' \| 'completed' \| 'failed'` |
| `progressPercent`          | `number`                                                            | Overall progress, 0 to 100                                                     |
| `retryCount`               | `number`                                                            |                                                                                |
| `errorMessage`             | `string \| null`                                                    |                                                                                |
| `startedAt`, `completedAt` | `string \| null`                                                    |                                                                                |
| `createdAt`                | `string`                                                            |                                                                                |
| `logs`                     | `Array<{ timestamp: string; stage: string; message: string }>`      | The worker's log lines                                                         |
| `retryable`                | `boolean`                                                           | Whether `assets.retry` can start a new run                                     |

### Other types [#other-types]

| Type                                                            | Shape                                                                                                                   |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `UploadSession`                                                 | `{ id; videoAssetId: string \| null; status: UploadSessionStatus; progressPercent; fileSize; uploadedBytes }`           |
| `UploadSessionStatus`                                           | `'uploading' \| 'completed' \| 'cancelled' \| 'failed'`                                                                 |
| `UploadHandle`                                                  | `AssetUploadHandle` without `assetId` and `uploadId`                                                                    |
| `RequestOptions`                                                | `{ signal?: AbortSignal }`                                                                                              |
| `PaginatedResponse<T>`                                          | `{ data: T[]; total; page: number \| null; limit; nextCursor: string \| null; hasMore: boolean }`                       |
| `CursorPage<T>`                                                 | `{ data: T[]; hasMore: boolean; nextCursor: string \| null }`                                                           |
| `AssetSortField`                                                | `'created_at' \| 'title' \| 'duration' \| 'size'`                                                                       |
| `RetryStage`                                                    | `'transcode' \| 'upload-segments'`                                                                                      |
| `Rendition`                                                     | `{ name; width; height; videoBitrateKbps; segmentCount; byteSize; dataObjectId; playlistObjectId }`                     |
| `AssetStats`                                                    | `{ total; byStatus: Record<VideoAssetStatus, number>; storedBytes; readyDurationMs; objectCount }`                      |
| `UsageReport`                                                   | `{ days: Array<{ date: string; plays: number }>; total: number }`, oldest day first                                     |
| `PlaybackPolicy`                                                | `'public' \| 'signed'`                                                                                                  |
| `ApiKeyScope`                                                   | `'upload' \| 'read' \| 'manage'`                                                                                        |
| `ApiKeyPage`                                                    | `CursorPage<ApiKey>` plus `limits: { maxKeys; maxRateLimit }`                                                           |
| `CreatedApiKey`                                                 | `ApiKey` plus `key: string`                                                                                             |
| `RotatedApiKey`                                                 | `CreatedApiKey` plus `rotatedFrom: string; previousKeyExpiresAt: string`                                                |
| `WebhookEventName`                                              | `'upload.started' \| 'upload.completed' \| 'upload.failed' \| 'processing.started' \| 'asset.ready' \| 'asset.errored'` |
| `WebhookEndpoint`                                               | `{ id; url; events: WebhookEventName[]; isActive; createdAt; lastDeliveryAt; lastDeliveryOk }`                          |
| `CreatedWebhookEndpoint`                                        | `{ id; url; events; secret }`                                                                                           |
| `WebhookTestResult`                                             | `{ delivered: boolean; statusCode: number \| null; error: string \| null }`                                             |
| `MissingObject`                                                 | `{ objectId: string; videoAssetId: string \| null; title: string \| null }`                                             |
| `ReconciliationReportDeployment`, `ReconciliationReportAccount` | The two members of `ReconciliationReport`                                                                               |
| `ReconciliationTrigger`                                         | `{ enqueued: boolean; alreadyPending: boolean }`                                                                        |
| `SiaObject`                                                     | An opaque handle from `resolveObjectId`. Pass it only to `download` of the same session.                                |
| `SiaSessionTransport`                                           | `{ fetchPublic?: (url: string) => Promise<Response>; resolveDeliveryUrl?: (pathOrUrl: string) => string }`              |

The manager classes (`UploadManager`, `AssetManager`, `PlaybackManager`, `PlaybackIdManager`, `KeyManager`, `SessionManager`, `ReconciliationManager`, `WebhookEndpointManager`, `WebhookManager`, `SiaSession`) are exported for typing. Except for `WebhookManager`, reach them through a `SlubyClient`.


# Webhook events (/developers/reference/webhook-events)

Sluby sends an HTTP `POST` with a JSON body to each of your webhook endpoints that is active and subscribed to the event. This page lists every event and describes exactly what each request contains and how delivery behaves. For a step-by-step setup, see [Receive webhooks](/developers/guides/webhooks).

You manage endpoints with the `manage` [scope](/developers/reference/api-conventions#scopes):

| Action                                               | Endpoint                                                                                                                                              |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create an endpoint (returns the signing secret once) | [`POST /api/v1/webhooks`](/developers/reference/api/webhooks/post-webhooks)                                                                           |
| List endpoints                                       | [`GET /api/v1/webhooks`](/developers/reference/api/webhooks/get-webhooks)                                                                             |
| Get one endpoint                                     | [`GET /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/get-webhooks-id)                                                                     |
| Change the URL or events, pause or resume            | [`PATCH /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/patch-webhooks-id)                                                                 |
| Replace the signing secret                           | [`POST /api/v1/webhooks/{id}/rotate-secret`](/developers/reference/api/webhooks/post-webhooks-id-rotate-secret)                                       |
| Send a test event                                    | [`POST /api/v1/webhooks/{id}/test`](/developers/reference/api/webhooks/post-webhooks-id-test)                                                         |
| Read the delivery log                                | [`GET /api/v1/webhooks/{id}/deliveries`](/developers/reference/api/webhooks/get-webhooks-id-deliveries)                                               |
| Resend a logged delivery                             | [`POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver`](/developers/reference/api/webhooks/post-webhooks-id-deliveries-deliveryid-redeliver) |
| Delete an endpoint and its delivery log              | [`DELETE /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/delete-webhooks-id)                                                               |

## Event types [#event-types]

You subscribe an endpoint to one or more of these six events. The API answers any other name in `events` with `400` and the message `Invalid events: <names>`.

| Event                                       | Sent when                                                              |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| [`upload.started`](#upload-started)         | A tus upload has been created and its asset exists.                    |
| [`upload.completed`](#upload-completed)     | All bytes of an upload arrived and the asset is queued for processing. |
| [`upload.failed`](#upload-failed)           | Sluby could not finish an upload whose bytes all arrived.              |
| [`processing.started`](#processing-started) | A processing run of an asset starts.                                   |
| [`asset.ready`](#asset-ready)               | An asset finished processing and is playable.                          |
| [`asset.errored`](#asset-errored)           | Processing of an asset failed for good.                                |

Sluby sends a seventh event, [`webhook.test`](#test-events), only through the test endpoint, to that one endpoint, whatever its subscriptions.

## Event envelope [#event-envelope]

Every request body is one JSON object with four fields:

| Field       | Type   | Description                                                                                                                                       |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string | Event id, `evt_` followed by a UUID. Every endpoint receives the same `id` for one event, and every retry and resend of it carries the same `id`. |
| `event`     | string | The event name, for example `asset.ready`.                                                                                                        |
| `timestamp` | string | ISO 8601 time at which Sluby created the event. Retries and resends keep it.                                                                      |
| `data`      | object | Event fields, listed per event below. Keys are snake_case.                                                                                        |

```json title="Example body"
{
  "id": "evt_6f1c2a4e-3b5d-4f7a-9c8e-1d2b3a4c5e6f",
  "event": "processing.started",
  "timestamp": "2026-10-20T09:15:02.481Z",
  "data": {
    "video_asset_id": "0b6f7c8e-2d4a-4e1b-9f3c-5a6b7c8d9e0f"
  }
}
```

## Event payloads [#event-payloads]

### upload.started [#upload-started]

Sluby sends it after the tus creation request (`POST /api/v1/uploads`) has created the upload, its upload session and its video asset.

| Field            | Type           | Description                                                          |
| ---------------- | -------------- | -------------------------------------------------------------------- |
| `upload_id`      | string         | The tus upload id (a UUID), the last path segment of the upload URL. |
| `session_id`     | string         | The upload session id. It is the same value as `upload_id`.          |
| `video_asset_id` | string or null | The asset created for this upload.                                   |
| `file_size`      | number         | The file size in bytes declared when the upload was created.         |

```json
{
  "upload_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "session_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "video_asset_id": "0b6f7c8e-2d4a-4e1b-9f3c-5a6b7c8d9e0f",
  "file_size": 52428800
}
```

### upload.completed [#upload-completed]

Sluby sends it once the last byte has arrived and it has hashed the file, marked the upload completed and queued the asset for transcoding.

| Field            | Type   | Description                                  |
| ---------------- | ------ | -------------------------------------------- |
| `upload_id`      | string | The tus upload id.                           |
| `session_id`     | string | The upload session id, equal to `upload_id`. |
| `video_asset_id` | string | The asset the upload belongs to.             |
| `sha256`         | string | Lowercase hex SHA-256 of the uploaded file.  |
| `file_size`      | number | The file size in bytes.                      |

```json
{
  "upload_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "session_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "video_asset_id": "0b6f7c8e-2d4a-4e1b-9f3c-5a6b7c8d9e0f",
  "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
  "file_size": 52428800
}
```

### upload.failed [#upload-failed]

Sluby sends it when all bytes arrived but finishing the upload failed: hashing the file, marking the upload completed, or queuing the transcode. Sluby also marks the asset `failed`.

| Field            | Type           | Description                                  |
| ---------------- | -------------- | -------------------------------------------- |
| `upload_id`      | string         | The tus upload id.                           |
| `session_id`     | string         | The upload session id, equal to `upload_id`. |
| `video_asset_id` | string or null | The asset the upload belongs to.             |
| `error`          | string         | The error message.                           |

### processing.started [#processing-started]

Sluby sends it once per processing run of an asset:

- when the transcode stage starts the run after an upload or after a [retry](/developers/reference/api/assets/post-assets-id-retry) that starts at transcoding;
- when a retry restarts at the Sia upload stage, because the transcode output already exists.

Automatic retries of a stage inside one run do not send it again.

| Field            | Type   | Description                |
| ---------------- | ------ | -------------------------- |
| `video_asset_id` | string | The asset being processed. |

### asset.ready [#asset-ready]

Sluby sends it when the finalize stage has stored the asset's records and the asset is `ready`. If the finalize job runs again for an asset that is already ready, Sluby sends `asset.ready` again, so one asset can produce more than one `asset.ready` event (each with its own `id`).

| Field                  | Type     | Description                                                                                                             |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `video_asset_id`       | string   | The asset.                                                                                                              |
| `manifest_object_id`   | string   | Sia object id of the HLS master playlist (64 lowercase hex characters).                                                 |
| `thumbnail_object_ids` | string[] | Sia object ids of the thumbnails.                                                                                       |
| `duration_ms`          | number   | Duration in milliseconds.                                                                                               |
| `resolution`           | string   | Source resolution as `<width>x<height>`, for example `1920x1080`.                                                       |
| `segment_count`        | number   | Number of media segments in a rendition (the highest count among the renditions).                                       |
| `total_storage_bytes`  | number   | Size in bytes of the renditions' media, their playlists and the master playlist stored on Sia. Thumbnails do not count. |
| `status`               | string   | Always `ready`.                                                                                                         |

```json
{
  "video_asset_id": "0b6f7c8e-2d4a-4e1b-9f3c-5a6b7c8d9e0f",
  "manifest_object_id": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
  "thumbnail_object_ids": ["7c6a180b36896a0a8c02787eeafb0e4c7c6a180b36896a0a8c02787eeafb0e4c"],
  "duration_ms": 63480,
  "resolution": "1920x1080",
  "segment_count": 11,
  "total_storage_bytes": 48211968,
  "status": "ready"
}
```

[Upload pipeline](/developers/concepts/upload-pipeline) describes the rendition ladder and segment format.

### asset.errored [#asset-errored]

Sluby sends it when a processing stage fails for good (its automatic retries are used up or the failure is unrecoverable) and Sluby moves the asset to `failed`. Sluby sends nothing if the asset was deleted or is already `ready` or `failed`.

| Field            | Type   | Description                                                 |
| ---------------- | ------ | ----------------------------------------------------------- |
| `video_asset_id` | string | The asset.                                                  |
| `stage`          | string | The stage that failed: `transcode`, `upload` or `finalize`. |
| `error`          | string | The error message.                                          |

```json
{
  "video_asset_id": "0b6f7c8e-2d4a-4e1b-9f3c-5a6b7c8d9e0f",
  "stage": "transcode",
  "error": "No video stream found"
}
```

## Request headers [#request-headers]

Every delivery is a `POST` to the endpoint URL with these headers:

| Header                 | Value                                                                                                                                         |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`         | `application/json`                                                                                                                            |
| `User-Agent`           | `Sluby-Webhooks`                                                                                                                              |
| `X-Sluby-Event`        | The event name, the same as `event` in the body.                                                                                              |
| `X-Sluby-Delivery`     | Delivery id, `dlv_` followed by a UUID. All attempts of one delivery to one endpoint share it. A resend and a test event each get a new one.  |
| `X-Sluby-Timestamp`    | Unix time in seconds at which this attempt was signed.                                                                                        |
| `X-Sluby-Signature-V1` | Lowercase hex HMAC-SHA256 of `<X-Sluby-Timestamp>.<body>`. See [Signature scheme](#signature-scheme).                                         |
| `X-Sluby-Signature`    | Lowercase hex HMAC-SHA256 of the body alone. Deprecated: it binds no time, so a captured request keeps verifying. Use `X-Sluby-Signature-V1`. |
| `Content-Length`       | Length of the body in bytes.                                                                                                                  |

## Signature scheme [#signature-scheme]

Each endpoint has a signing secret: 64 hex characters (32 random bytes), returned once when you create the endpoint and once when you rotate it.

To verify a request:

1. Read the raw request body as a string, exactly as received, before any JSON parsing.
2. Build the signed string: the `X-Sluby-Timestamp` value, a period, then the raw body.
3. Compute HMAC-SHA256 of the signed string, using the secret string as the key (its UTF-8 bytes, not the bytes the hex decodes to).
4. Hex-encode the result and compare it with `X-Sluby-Signature-V1` in constant time. Hex comparison is case-insensitive.
5. Check the timestamp against your clock (see [Timestamps and replay window](#timestamps-and-replay-window)).

`@sluby/sdk` does all five steps in `verifyRequest` (Node.js) and `verifyRequestAsync` (Web Crypto). See [the SDK reference](/developers/reference/sdk#webhooks).

```ts title="verify.ts"
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody is the request body exactly as received, before JSON parsing
export function verifySluby(
  rawBody: string,
  timestamp: string,
  signatureV1: string,
  secret: string,
): boolean {
  const ts = Number(timestamp);
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const given = signatureV1.toLowerCase();
  if (given.length !== expected.length || !/^[0-9a-f]+$/.test(given)) return false;
  return timingSafeEqual(Buffer.from(given, 'hex'), Buffer.from(expected, 'hex'));
}
```

Sluby reads the secret when it sends each attempt. After you [rotate the secret](/developers/reference/api/webhooks/post-webhooks-id-rotate-secret), every later attempt, including retries already queued, is signed with the new secret, and the old secret stops verifying at once.

## Timestamps and replay window [#timestamps-and-replay-window]

Sluby sets `X-Sluby-Timestamp` for each attempt, so a retry carries a new timestamp and a new `X-Sluby-Signature-V1` over the same body. The body's `timestamp` field is the time the event was created and stays the same.

Sluby does not enforce a window; your receiver does. The SDK refuses a request whose `X-Sluby-Timestamp` is more than 300 seconds from the receiver's clock in either direction (`DEFAULT_WEBHOOK_TOLERANCE_SECONDS`), and accepts a `toleranceSeconds` option to change that. The SDK also requires the timestamp to be 1 to 12 digits.

## Response and timeout [#response-and-timeout]

| Your endpoint                                                | Result                                           |
| ------------------------------------------------------------ | ------------------------------------------------ |
| Answers `2xx`                                                | Delivered.                                       |
| Answers `3xx`                                                | Failed attempt. Sluby does not follow redirects. |
| Answers any other status                                     | Failed attempt.                                  |
| Sends no status line within 10 seconds (DNS lookup included) | Failed attempt.                                  |
| Cannot be resolved, connected to, or reached over TLS        | Failed attempt.                                  |

Sluby decides on the status line alone. It never reads or stores the response body.

## Retries [#retries]

A delivery gets 4 attempts. The first runs as soon as the event is queued; after a failed attempt, the next one waits:

| Attempt | Wait after the previous failure |
| ------- | ------------------------------- |
| 1       | none                            |
| 2       | 10 seconds                      |
| 3       | 1 minute                        |
| 4       | 5 minutes                       |

After the fourth failed attempt Sluby gives up on that delivery. You can [resend it](#redelivery) from the delivery log. Sluby keeps pending deliveries and retries in Redis, so they survive a restart of the backend. Failed deliveries do not pause or disable an endpoint.

## Duplicates and ordering [#duplicates-and-ordering]

- Use the body's `id` to drop duplicates. Retries and resends of one event keep its `id`.
- `asset.ready` can arrive more than once for one asset, with different `id`s (see [asset.ready](#asset-ready)).
- A retried delivery arrives after events that happened later. Order events by the body's `timestamp` if order matters to you.

## Paused and deleted endpoints [#paused-and-deleted-endpoints]

Setting `is_active` to `false` with [`PATCH /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/patch-webhooks-id) pauses an endpoint. A paused endpoint receives no new events, and deliveries already queued for it are dropped when their turn comes, without a delivery log entry. Deleting an endpoint does the same and also deletes its delivery log.

## Receiver addresses [#receiver-addresses]

An endpoint URL must start with `https://` or `http://` and be at most 2,048 characters. Every address its host resolves to must be a public address: Sluby refuses loopback, private, link-local, shared (CGNAT), documentation, multicast and other reserved ranges, including IPv6 forms that carry such an IPv4 address. The server operator can allow specific networks with [`WEBHOOK_ALLOWED_NETWORKS`](/self-hosting/configuration#webhook_allowed_networks).

Sluby checks the URL when you create or change the endpoint and again before every attempt, and connects only to the addresses it checked. An attempt to a host that now resolves to a refused address fails.

## Test events [#test-events]

[`POST /api/v1/webhooks/{id}/test`](/developers/reference/api/webhooks/post-webhooks-id-test) sends one `webhook.test` event to the endpoint right away and answers with the outcome (`delivered`, `status_code`, `error`). Sluby makes a single attempt with no retries, signed and with the same headers as any delivery, and records it in the delivery log. Sluby sends it whatever the endpoint's subscriptions, and also when the endpoint is paused.

```json title="webhook.test body"
{
  "id": "evt_2c4e6a8b-0d1f-4a3c-8e5b-7d9f1b3d5e7a",
  "event": "webhook.test",
  "timestamp": "2026-10-20T09:20:44.102Z",
  "data": {
    "webhook_id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9"
  }
}
```

## Redelivery [#redelivery]

[`POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver`](/developers/reference/api/webhooks/post-webhooks-id-deliveries-deliveryid-redeliver) queues the logged payload again. `deliveryId` is the `id` of a delivery log entry.

- The resend keeps the event's `id` and `timestamp`, so a receiver that already handled the event can drop it.
- It gets a new `X-Sluby-Delivery`, which the endpoint returns as `delivery_id` with status `202`.
- It gets the same 4 attempts and retry waits as any delivery, and its attempts are logged with `manual: true`.
- The resent body is the stored JSON serialized again, so its key order can differ from the original bytes. The signature covers the bytes that are sent, so verify against the raw body you receive.
- A paused endpoint answers `409` with `This webhook is paused. Resume it to resend.`

## Delivery log [#delivery-log]

Sluby records one log entry per attempt, including test events and resends, but not deliveries dropped for a paused or deleted endpoint. Each entry holds the event name, the event `id`, the exact payload sent, the HTTP status your endpoint answered (or none when no response arrived), whether it was delivered, the attempt number (1 to 4), the time, whether it was a manual resend, and for a failed attempt the reason. Sluby never stores the response body.

Sluby writes these failure reasons:

| Reason                                                                                                                                            | Cause                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Your endpoint answered <status>`                                                                                                                 | A status outside `2xx` and `3xx`.                                                                                 |
| `Your endpoint answered <status>. Redirects are not followed.`                                                                                    | A `3xx` status.                                                                                                   |
| `No response within 10 seconds`                                                                                                                   | The 10 second timeout ran out.                                                                                    |
| `<host> could not be found. Check the address.`                                                                                                   | DNS lookup failed or returned no address.                                                                         |
| `Webhooks can only reach public addresses, and <host> points to <place>. To allow it, add the network to WEBHOOK_ALLOWED_NETWORKS on the server.` | The host resolves to a refused address. `<place>` is `this machine`, `a private network` or `a reserved address`. |
| `Could not connect (<code>)`                                                                                                                      | Connection refused, reset or unreachable.                                                                         |
| `Could not make a secure connection (<code>)`                                                                                                     | A TLS or certificate error.                                                                                       |
| `The request failed` or `The request failed (<code>)`                                                                                             | Any other request error.                                                                                          |

[`GET /api/v1/webhooks/{id}/deliveries`](/developers/reference/api/webhooks/get-webhooks-id-deliveries) returns the newest entries first and takes a `limit` ([Pagination](/developers/reference/api-conventions#pagination)). Sluby keeps entries for 30 days: a sweep that runs when the backend starts and then every hour deletes older ones.

[`GET /api/v1/webhooks`](/developers/reference/api/webhooks/get-webhooks) and [`GET /api/v1/webhooks/{id}`](/developers/reference/api/webhooks/get-webhooks-id) also report `last_delivery_at` and `last_delivery_ok` for each endpoint, taken from its newest log entry.


# Configuration reference (/self-hosting/configuration)

This page lists every setting a Sluby server reads: the backend, the web proxy, the Studio build, the production override with Caddy, and the image builds. You set them in the `.env` file in the folder where you cloned Sluby. Docker Compose reads that file and passes each value to the service that needs it. Two exceptions: `STUDIO_API_PROXY_TARGET` goes in `frontend/.env`, and the rows that say Compose sets the value (`DATABASE_URL`, `REDIS_URL`, `PORT`, `HOST`, `UPLOAD_DIR`, `TRANSCODE_OUTPUT_DIR`) ignore `.env` in the Compose stack.

## How settings are read [#how-settings-are-read]

- Docker Compose reads `.env` from the project folder and substitutes the values into `docker-compose.yml` (and `docker-compose.prod.yml` when you use it).
- An empty value counts as unset. `SIA_DATA_SHARDS=` behaves exactly like leaving the line out, so the backend takes its own default.
- On/off settings accept `true`, `false`, `1` or `0`. The backend refuses any other value, such as `yes` or `TRUE`, and does not start.
- The backend reads its settings once, at startup. After you change one, run `docker compose up -d` (with the same `-f` files you started with) so Compose recreates the containers whose settings changed.
- The `VITE_` settings are compiled into the Studio when the web image is built. After you change one, rebuild the web image: `docker compose up -d --build web` (with the same `-f` files you started with).
- When the backend finds an invalid value, it prints `Refusing to start, the configuration is not valid:` followed by one line per problem, and exits. See [Troubleshooting](/self-hosting/troubleshooting#the-backend-refuses-to-start).

The **Default** column shows the value the shipped Docker Compose stack runs with. Where the backend's own default differs (it applies when you run the backend from source), the description says so.

## Backend: server and logging [#backend-server-and-logging]

Read by the `backend` service.

| Variable                                                    | Default                 | Description                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="node_env">`NODE_ENV`</span>                       | `development`           | `development`, `production` or `test`. `production` turns on the startup checks (a strong `SESSION_SECRET` is required, `AUTH_DISABLED=true` is refused, `BOOTSTRAP_API_KEY` must be a generated key) and switches the logs to JSON. Outside production the logs are colored text. `docker-compose.prod.yml` sets it to `production`.                                                     |
| <span id="log_level">`LOG_LEVEL`</span>                     | `info`                  | Log level of the backend and of the Sia storage SDK it uses: `fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`.                                                                                                                                                                                                                                                              |
| <span id="expose_error_stacks">`EXPOSE_ERROR_STACKS`</span> | `false`                 | `true` adds the internal error message and stack trace to API error responses. They contain file paths and internals, so use it only for debugging. The backend logs a warning at startup while it is on.                                                                                                                                                                                 |
| <span id="public_url">`PUBLIC_URL`</span>                   | `http://localhost:8080` | The address people open in the browser, without a trailing slash. The backend builds upload URLs, the GitHub callback URL, invite and reset links, signed playback URLs and watch page links from it. The session cookie is marked `Secure` only when it starts with `https://`. `docker-compose.prod.yml` sets it to `https://` plus `DOMAIN`. Backend default: `http://localhost:3000`. |
| <span id="port">`PORT`</span>                               | `3000`                  | Port the backend listens on. Compose sets it to `3000`, the port the web proxy connects to (`backend:3000`). Backend default: `3000`.                                                                                                                                                                                                                                                     |
| <span id="host">`HOST`</span>                               | `0.0.0.0`               | Address the backend listens on. Compose sets it to `0.0.0.0`. Backend default: `0.0.0.0`.                                                                                                                                                                                                                                                                                                 |

## Backend: database and queue [#backend-database-and-queue]

| Variable                                                | Default                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="postgres_password">`POSTGRES_PASSWORD`</span> | `sluby`                                                      | Password of the `sluby` database user. Compose passes it to the `postgres` service and puts it, unencoded, into `DATABASE_URL`, so use letters and digits only: generate one with `openssl rand -hex 32`. A value with `/` makes the backend refuse to start with `DATABASE_URL: Invalid URL`. `docker-compose.prod.yml` requires it. The `postgres` image applies it only when it creates the database on an empty volume, so set it before the first start. |
| <span id="database_url">`DATABASE_URL`</span>           | `postgresql://sluby:<POSTGRES_PASSWORD>@postgres:5432/sluby` | PostgreSQL connection string. Compose sets it for the backend container, so you do not set it in the Compose stack. Backend default: `postgresql://sluby:sluby@localhost:5432/sluby`.                                                                                                                                                                                                                                                                         |
| <span id="redis_url">`REDIS_URL`</span>                 | `redis://redis:6379`                                         | Redis connection string, used for the job queues. Compose sets it for the backend container. Backend default: `redis://localhost:6379`.                                                                                                                                                                                                                                                                                                                       |

To run the backend from source against the Compose databases, `docker-compose.dev.yml` publishes PostgreSQL on `127.0.0.1:5433` and Redis on `127.0.0.1:6380`. Then set these two lines in `.env`:

```bash title=".env"
DATABASE_URL=postgresql://sluby:sluby@localhost:5433/sluby
REDIS_URL=redis://localhost:6380
```

## Backend: Sia storage [#backend-sia-storage]

How to get these values: [Connect Sia storage](/self-hosting/sia-storage).

| Variable                                                  | Default                 | Description                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="sia_indexer_url">`SIA_INDEXER_URL`</span>       | `https://sia.storage`   | Base URL of the indexer's application API, without a trailing slash. The backend connects to this indexer to store and read media on Sia.                                                                                                                                                                                                                                               |
| <span id="sia_network">`SIA_NETWORK`</span>               | `mainnet`               | The Sia network the indexer runs on: `mainnet`, `zen`, `testnet` or `anagami`. Used for labels in the Studio and to pick the explorer for host and contract links (`zen` and `testnet` link to Zen Siascan, every other value to Siascan).                                                                                                                                              |
| <span id="sia_app_id">`SIA_APP_ID`</span>                 | empty                   | The 32-byte app ID (hex) that `connect-indexer.mjs` prints. Keep it the same across restarts. `docker-compose.prod.yml` requires it.                                                                                                                                                                                                                                                    |
| <span id="sia_app_key">`SIA_APP_KEY`</span>               | empty                   | The 32-byte app key (hex) that `connect-indexer.mjs` prints. The backend signs every indexer request with it. It can read and delete everything this app stores, so keep it secret. Without it the backend starts but uploads fail, and it logs a warning. `docker-compose.prod.yml` requires it.                                                                                       |
| <span id="sia_data_shards">`SIA_DATA_SHARDS`</span>       | unset                   | Data shards per slab. Leave both shard settings unset for the SDK default of 10 data and 20 parity shards (30 hosts per slab). Set both, and only to fit an indexer with a smaller host pool. The SDK and the indexer reject ratios whose recovery probability is under 99.99% or whose redundancy is outside 1.5x to 4x. When only one of the two is set, uploads use the SDK default. |
| <span id="sia_parity_shards">`SIA_PARITY_SHARDS`</span>   | unset                   | Parity shards per slab. See `SIA_DATA_SHARDS`.                                                                                                                                                                                                                                                                                                                                          |
| <span id="sia_admin_url">`SIA_ADMIN_URL`</span>           | `http://127.0.0.1:9980` | Admin API of a self-hosted indexd, without a trailing slash. Used only when `SIA_ADMIN_PASSWORD` is set, to add contract IDs and the wallet address to the storage breakdown.                                                                                                                                                                                                           |
| <span id="sia_admin_password">`SIA_ADMIN_PASSWORD`</span> | empty                   | HTTP Basic password of that admin API (the indexd `adminAPI.password`). Empty turns the admin lookups off.                                                                                                                                                                                                                                                                              |

## Backend: sign-in and sessions [#backend-sign-in-and-sessions]

How to use these: [Set up sign-in](/self-hosting/sign-in).

| Variable                                                      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="session_secret">`SESSION_SECRET`</span>             | unset   | Secret that signs session cookies and private playback URLs. The setup code for the first admin is also derived from it. Outside production, when it is unset, the backend generates one on its first start and keeps it in its database, so restarts sign nobody out. In production the backend refuses to start unless it is set, at least 32 characters long, and not the old public development value. Generate one with `openssl rand -base64 32`. Changing it signs everyone out and makes signed links already handed out stop working. `docker-compose.prod.yml` requires it. |
| <span id="auth_disabled">`AUTH_DISABLED`</span>               | `false` | `true` turns sign-in off: every request acts as one local admin account. The API then sends no CORS headers to origins that are not listed in `CORS_ORIGIN`. Production refuses to start with it on, and `docker-compose.prod.yml` forces it to `false`.                                                                                                                                                                                                                                                                                                                              |
| <span id="github_client_id">`GITHUB_CLIENT_ID`</span>         | unset   | Client ID of a GitHub OAuth app. GitHub sign-in is offered when both GitHub settings are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| <span id="github_client_secret">`GITHUB_CLIENT_SECRET`</span> | unset   | Client secret of that GitHub OAuth app.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| <span id="github_allowed_users">`GITHUB_ALLOWED_USERS`</span> | empty   | Setting from versions before members and roles. The first start after the upgrade removes the GitHub accounts it refused. After that the backend ignores it and logs a warning at every start while it is set. Remove it after the upgrade.                                                                                                                                                                                                                                                                                                                                           |
| <span id="operator_users">`OPERATOR_USERS`</span>             | empty   | Setting from versions before members and roles, as comma-separated `<provider>:<entry>` values such as `github:octocat`. The first start after the upgrade makes the listed accounts admins. After that the backend ignores it and logs a warning at every start while it is set. Remove it after the upgrade.                                                                                                                                                                                                                                                                        |
| <span id="bootstrap_api_key">`BOOTSTRAP_API_KEY`</span>       | unset   | An API key with every scope that the backend creates before it takes requests. It is created once: after you delete or rotate it, it is never created again, and the backend logs a warning while the old value is still set. In production it must look like a generated key (`sluby_` and at least 32 more letters, digits, `-` or `_`). Generate one with `node -e "console.log('sluby_' + require('crypto').randomBytes(32).toString('base64url'))"`.                                                                                                                             |

## Backend: API access and limits [#backend-api-access-and-limits]

| Variable                                                              | Default                            | Description                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="cors_origin">`CORS_ORIGIN`</span>                           | empty                              | Comma-separated browser origins (`scheme://host[:port]`, no path, no trailing slash) whose pages can call the API with the Studio session cookie. Every other origin can still call the API with an API key, without cookies, unless `AUTH_DISABLED` is on. `docker-compose.prod.yml` sets it to `https://` plus `DOMAIN`. |
| <span id="trust_proxy">`TRUST_PROXY`</span>                           | `loopback, linklocal, uniquelocal` | Which proxy hops the backend trusts for the client address in `X-Forwarded-For`: a hop count, `true`, `false`, or comma-separated addresses, CIDR ranges and the names `loopback`, `linklocal` and `uniquelocal`. The default trusts private networks, which covers the web proxy alone and Caddy in front of it.          |
| <span id="api_ip_rate_limit">`API_IP_RATE_LIMIT`</span>               | `600`                              | Requests per minute one client address can make to `/api/v1` without a valid API key or session (sign-in routes, the API spec, failed authentication).                                                                                                                                                                     |
| <span id="api_key_rate_limit_max">`API_KEY_RATE_LIMIT_MAX`</span>     | `10000`                            | The highest per-minute rate limit an API key can have. Creating a key that asks for more is refused, and older keys are held to this value.                                                                                                                                                                                |
| <span id="api_keys_per_account_max">`API_KEYS_PER_ACCOUNT_MAX`</span> | `100`                              | How many API keys can be active at once. Revoked and expired keys do not count. Creating a key beyond this number is refused.                                                                                                                                                                                              |
| <span id="metrics_token">`METRICS_TOKEN`</span>                       | unset                              | When set, `GET /metrics` requires `Authorization: Bearer <token>`, on the backend port and through the web proxy. Unset, it answers only requests made straight to the backend port; through the web proxy it answers `404`. See [Prometheus metrics](/self-hosting/operations#prometheus-metrics).                        |
| <span id="webhook_allowed_networks">`WEBHOOK_ALLOWED_NETWORKS`</span> | empty                              | Comma-separated CIDRs or addresses of private or otherwise special networks that webhook receivers can be on, such as `10.0.5.0/24,fd00:5::/64`. Empty: webhooks reach public addresses only.                                                                                                                              |

## Backend: uploads, transcoding and delivery [#backend-uploads-transcoding-and-delivery]

| Variable                                                            | Default                 | Description                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="max_upload_size">`MAX_UPLOAD_SIZE`</span>                 | `10737418240`           | Largest upload in bytes (10 GiB).                                                                                                                                                                                                                                                 |
| <span id="transcode_max_rendition">`TRANSCODE_MAX_RENDITION`</span> | `1080p`                 | Tallest rendition the transcoder makes: `2160p`, `1440p`, `1080p`, `720p`, `540p` or `360p`. `1440p` and `2160p` add renditions above 1080p for sources that tall. A lower value drops renditions. The full ladder is in [Upload pipeline](/developers/concepts/upload-pipeline). |
| <span id="cache_max_size_mb">`CACHE_MAX_SIZE_MB`</span>             | `256`                   | Size of the backend's in-memory object cache in megabytes. It holds whole objects of up to 8 MB that are read without a `Range` header (manifests, playlists, thumbnails) and counts against the backend container's memory. Larger objects are streamed and never held.          |
| <span id="upload_dir">`UPLOAD_DIR`</span>                           | `/app/uploads`          | Directory for incoming uploads. Compose sets it and mounts the `uploads` volume there. Backend default: `./uploads`.                                                                                                                                                              |
| <span id="transcode_output_dir">`TRANSCODE_OUTPUT_DIR`</span>       | `/app/transcode-output` | Directory for transcoder output. Compose sets it and mounts the `transcode-output` volume there. Backend default: `./transcode-output`.                                                                                                                                           |

## Backend: background jobs [#backend-background-jobs]

What these jobs do: [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation).

| Variable                                                                    | Default   | Description                                                                                                                                                   |
| --------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="reconcile_enabled">`RECONCILE_ENABLED`</span>                     | `true`    | Runs the scheduled reconciliation, which compares the database with what the indexer stores. `false` stops the schedule. Runs you start on demand still work. |
| <span id="reconcile_interval_ms">`RECONCILE_INTERVAL_MS`</span>             | `3600000` | Time between scheduled reconciliation runs, in milliseconds (one hour).                                                                                       |
| <span id="reconcile_page_size">`RECONCILE_PAGE_SIZE`</span>                 | `500`     | Page size when reconciliation reads the indexer's object list. At most `500`, because the indexer answers larger pages with an error.                         |
| <span id="deletion_gc_enabled">`DELETION_GC_ENABLED`</span>                 | `true`    | Runs the deletion sweep, which finishes deletions that stopped before every object was unpinned.                                                              |
| <span id="deletion_gc_interval_ms">`DELETION_GC_INTERVAL_MS`</span>         | `900000`  | Time between deletion sweeps, in milliseconds (15 minutes).                                                                                                   |
| <span id="deletion_stuck_threshold_ms">`DELETION_STUCK_THRESHOLD_MS`</span> | `600000`  | How long ago a video must have been deleted before the sweep treats its unfinished deletion as stuck and starts it again, in milliseconds (10 minutes).       |

## Web proxy [#web-proxy]

The `web` service is nginx. It serves the Studio and passes the API and video delivery to the backend. It checks these values when the container starts and exits with a message such as `WEB_DELIVERY_RATE=fast is not valid (expected a rate such as 50r/s or 600r/m)` when one is malformed.

| Variable                                                  | Default  | Description                                                                                                                                                                 |
| --------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="web_port">`WEB_PORT`</span>                     | `8080`   | Port on `127.0.0.1` where the base stack publishes the web proxy. Set `PUBLIC_URL` to match. `docker-compose.prod.yml` publishes no web port; Caddy connects to it instead. |
| <span id="web_delivery_rate">`WEB_DELIVERY_RATE`</span>   | `100r/s` | Request rate per client address on delivery paths (`/v1/`), as `<n>r/s` or `<n>r/m`.                                                                                        |
| <span id="web_delivery_burst">`WEB_DELIVERY_BURST`</span> | `400`    | Requests a client can make on delivery paths above that rate before nginx answers `429`.                                                                                    |
| <span id="web_delivery_conn">`WEB_DELIVERY_CONN`</span>   | `200`    | Open connections per client address on delivery paths.                                                                                                                      |
| <span id="web_auth_rate">`WEB_AUTH_RATE`</span>           | `10r/s`  | Request rate per client address on sign-in paths (`/api/v1/auth/`) and `/metrics`, as `<n>r/s` or `<n>r/m`.                                                                 |
| <span id="web_auth_burst">`WEB_AUTH_BURST`</span>         | `50`     | Requests a client can make on sign-in paths and `/metrics` above that rate before nginx answers `429`.                                                                      |
| <span id="web_auth_conn">`WEB_AUTH_CONN`</span>           | `20`     | Open connections per client address on sign-in paths and `/metrics`.                                                                                                        |

## Studio build [#studio-build]

These are compiled into the Studio's JavaScript when the web image is built, so every visitor's browser receives them. Rebuild the web image after changing them: `docker compose up -d --build web` (with the same `-f` files you started with).

| Variable                                                                  | Default                 | Description                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <span id="vite_sluby_sia_indexer_url">`VITE_SLUBY_SIA_INDEXER_URL`</span> | unset                   | Indexer URL of the viewer identity for streaming from Sia in the browser. Use an `https://` URL: the Studio's content security policy (`connect-src 'self' https:`) blocks plain `http://` addresses. The Studio streams from Sia only when all three `VITE_SLUBY_SIA_` values are set. See [Stream from Sia in the browser](/self-hosting/direct-playback). |
| <span id="vite_sluby_sia_app_id">`VITE_SLUBY_SIA_APP_ID`</span>           | unset                   | App ID of the viewer identity that `provision-viewer.mjs` prints.                                                                                                                                                                                                                                                                                            |
| <span id="vite_sluby_sia_app_key">`VITE_SLUBY_SIA_APP_KEY`</span>         | unset                   | App key of the viewer identity that `provision-viewer.mjs` prints. It is public once built in. Never put `SIA_APP_KEY` here.                                                                                                                                                                                                                                 |
| <span id="vite_sia_explorer_url">`VITE_SIA_EXPLORER_URL`</span>           | unset                   | Sia explorer for host, contract and address links in the Studio. Unset, the Studio uses `https://zen.siascan.com` when `SIA_NETWORK` is `zen` or `testnet`, and `https://siascan.com` otherwise.                                                                                                                                                             |
| <span id="studio_api_proxy_target">`STUDIO_API_PROXY_TARGET`</span>       | `http://localhost:3000` | Only for the Studio's development server (`npm run dev` in `frontend/`), read from `frontend/.env`: where it forwards `/api`, `/v1`, `/health` and `/watch`.                                                                                                                                                                                                 |

## Production with Caddy [#production-with-caddy]

Read by `docker-compose.prod.yml` and the `caddy` service. See [Run in production](/self-hosting/production).

| Variable                                  | Default        | Description                                                                                                                                                                                    |
| ----------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="domain">`DOMAIN`</span>         | none, required | The domain the server answers on, such as `sluby.example.com`. Caddy gets and renews its TLS certificate. The override also sets `PUBLIC_URL` and `CORS_ORIGIN` to `https://` plus this value. |
| <span id="acme_email">`ACME_EMAIL`</span> | none, required | Email address Caddy gives the certificate authority when it requests the certificate.                                                                                                          |

`docker-compose.prod.yml` also requires `POSTGRES_PASSWORD`, `SESSION_SECRET`, `SIA_APP_ID` and `SIA_APP_KEY`, and it sets `NODE_ENV=production` and `AUTH_DISABLED=false` whatever `.env` says.

## Backend image build [#backend-image-build]

| Variable                                                  | Default | Description                                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="sia_storage_native">`SIA_STORAGE_NATIVE`</span> | unset   | Path, relative to `backend/vendor/`, of a custom-built Sia storage native module to put in the backend image instead of the standard one, for example `sia-storage-linux-x64-gnu/sia-storage.node`. The build fails when the file is missing. `backend/vendor/README.md` explains how to build one. |

## Local indexer stack [#local-indexer-stack]

Read by `docker-compose.sia.yml`, which runs indexd, its own PostgreSQL, walletd and a CPU miner for the Zen testnet. It is separate from the Sluby stack.

| Variable                                                              | Default | Description                                                      |
| --------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| <span id="indexd_postgres_password">`INDEXD_POSTGRES_PASSWORD`</span> | none    | Password of the `indexd` user in the indexer's own PostgreSQL.   |
| <span id="walletd_api_password">`WALLETD_API_PASSWORD`</span>         | `1234`  | API password of walletd, which the miner uses.                   |
| <span id="miner_address">`MINER_ADDRESS`</span>                       | none    | Wallet address the miner pays out to: the indexd wallet address. |


# Stream from Sia in the browser (/self-hosting/direct-playback)

By default the Studio player streams every video through your server. With a viewer identity built into the Studio, the player streams hybrid: playlists, the start of a video and any segment needed urgently come through your server, and the rest comes from Sia hosts straight to the viewer's browser. This page registers that identity and builds it into the Studio. How the delivery modes work: [Playback and delivery](/developers/concepts/playback).

## The viewer identity [#the-viewer-identity]

The viewer identity is a second app registered with your indexer, separate from the one in `SIA_APP_ID` and `SIA_APP_KEY` that uploads your videos. The browser uses it to read the objects your server shares with it. Its key is compiled into the Studio's JavaScript, so every visitor can read it.

<Callout type="warn" title="Use the viewer key only">
  Put only the values from `provision-viewer.mjs` in the `VITE_SLUBY_SIA_` lines. Never put
  `SIA_APP_KEY` there: it can read and delete everything your server stores, and the Studio build
  puts these values into the JavaScript every visitor downloads.
</Callout>

## Turn it on [#turn-it-on]

Run these commands in the Sluby folder. On a production server, add `-f docker-compose.yml -f docker-compose.prod.yml` after `docker compose`.

<Steps>
<Step>

### Register the viewer identity [#register-the-viewer-identity]

```bash
docker compose run --rm --no-deps backend node scripts/provision-viewer.mjs
```

The script uses the indexer URL you pass as its argument, and `SIA_INDEXER_URL` from `.env` without one. It prints a URL: open it in the browser where you are signed in to your indexer account and approve it, as you did for [Connect Sia storage](/self-hosting/sia-storage).

</Step>
<Step>

### Copy the lines into .env [#copy-the-lines-into-env]

The script prints:

```bash title=".env"
VITE_SLUBY_SIA_INDEXER_URL=https://sia.storage
VITE_SLUBY_SIA_APP_ID=<64 hex characters>
VITE_SLUBY_SIA_APP_KEY=<64 hex characters>
```

Put all three lines in `.env`, without the leading spaces the script prints. The indexer URL must start with `https://`: the Studio page's Content Security Policy allows connections to its own origin and to `https:` addresses only. See [`VITE_SLUBY_SIA_INDEXER_URL`](/self-hosting/configuration#vite_sluby_sia_indexer_url).

If the script ends with `Account is not ready yet: contracts are still forming.`, it also notes that the account needs a small balance to pay egress before playback works. Until then, the player keeps playing through your server.

</Step>
<Step>

### Rebuild the web image [#rebuild-the-web-image]

The values are compiled into the Studio, so rebuild and restart the `web` service:

```bash
docker compose up -d --build web
```

</Step>
<Step>

### Check it in the Studio [#check-it-in-the-studio]

Open a ready video in the Studio. The badge on the player reads **Sia and this server** while the video starts, then shows how much has come from Sia, for example **62% from Sia**. Without a viewer identity it reads **Through this server**. It reads the same in a browser that cannot run hls.js and plays the video with its own HLS support. More about the badge: [Watch a video](/studio/watch).

</Step>
</Steps>

## Where it applies [#where-it-applies]

- **The Studio player**: hybrid delivery, as above.
- **The public watch page** (`/watch/<id>`, which the Studio's watch links and iframe embed codes open): streams through your server.
- **Your own apps**: `@sluby/player` streams from Sia when you give its client a viewer identity. See [Play videos in React](/developers/guides/play-react).

How hybrid delivery picks between Sia and your server for each segment: [Hybrid](/developers/concepts/playback#hybrid).

## Turn it off [#turn-it-off]

Remove the three `VITE_SLUBY_SIA_` lines from `.env` (or leave them empty) and rebuild the web image:

```bash
docker compose up -d --build web
```

## Related [#related]

- [Playback and delivery](/developers/concepts/playback)
- [Direct playback problems](/self-hosting/troubleshooting#direct-playback)


# Install Sluby (/self-hosting)

This page takes you from an empty machine to a running Sluby server with the Studio open in your browser and your first admin account created. Everything runs in Docker Compose on one machine and listens on `http://localhost:8080`. To serve it on a domain with TLS afterwards, continue with [Run in production](/self-hosting/production).

## Requirements [#requirements]

- Docker with the Docker Compose plugin (the `docker compose` command) and BuildKit. The backend image builds only with BuildKit.
- An x86-64 (`amd64`) or ARM64 (`arm64`) processor. On ARM64 the backend image compiles the Sia storage module from source while it builds.
- Git.
- An account on [sia.storage](https://sia.storage), the hosted Sia indexer Sluby connects to by default.

## What runs [#what-runs]

The stack in `docker-compose.yml` has four services:

| Service    | Image                            | Role                                                                     |
| ---------- | -------------------------------- | ------------------------------------------------------------------------ |
| `postgres` | `postgres:18-alpine`             | the database                                                             |
| `redis`    | `redis:8-alpine`                 | the job queues                                                           |
| `backend`  | built from `backend/Dockerfile`  | the API, the upload and transcoding workers, and video delivery          |
| `web`      | built from `frontend/Dockerfile` | nginx serving the Studio and passing the API and delivery to the backend |

Only `web` is published, on `127.0.0.1:8080`. Data lives in the Docker volumes `pgdata`, `redis-data`, `uploads`, `transcode-output` and `nginx-cache`. How the parts work together: [Architecture](/developers/concepts/architecture).

## Install [#install]

<Steps>
<Step>

### Get the code [#get-the-code]

```bash
git clone https://github.com/justmert/Sluby.git
cd Sluby
```

Run every later command in this folder.

</Step>
<Step>

### Create .env [#create-env]

```bash
cp .env.example .env
```

The defaults in `.env.example` run the local stack against sia.storage with sign-in turned on. Every setting is described in the [configuration reference](/self-hosting/configuration).

</Step>
<Step>

### Build the images [#build-the-images]

```bash
docker compose build
```

</Step>
<Step>

### Connect to Sia [#connect-to-sia]

```bash
docker compose run --rm --no-deps backend node scripts/connect-indexer.mjs
```

The script prints a URL. Open it in the browser where you are signed in to sia.storage and approve the connection. The script then prints three lines:

```bash title=".env"
SIA_INDEXER_URL=https://sia.storage
SIA_APP_ID=<64 hex characters>
SIA_APP_KEY=<64 hex characters>
```

In `.env`, replace the `SIA_INDEXER_URL`, `SIA_APP_ID` and `SIA_APP_KEY` lines with these three. Details, and how to use another indexer: [Connect Sia storage](/self-hosting/sia-storage).

</Step>
<Step>

### Start Sluby [#start-sluby]

```bash
docker compose up -d
```

The backend applies the database migrations before it starts. `web` starts once the backend reports healthy. Check that all four services are up:

```bash
docker compose ps
```

</Step>
<Step>

### Find the setup code [#find-the-setup-code]

```bash
docker compose logs backend | grep "setup code"
```

The matching line ends with this message, with your code in place of `XXXXX-XXXXX`:

```text
No admin can sign in yet. Open http://localhost:8080/studio and set up the first admin with the setup code XXXXX-XXXXX.
```

More about the setup code: [Set up sign-in](/self-hosting/sign-in).

</Step>
<Step>

### Create the first admin [#create-the-first-admin]

Open `http://localhost:8080`. It redirects to the Studio at `/studio`. Click **Set up the first admin**, then fill in **Setup code**, **Your name**, **Email** and **Password** (at least 10 characters) and click **Create admin account**. The Studio signs you in.

</Step>
</Steps>

## Next steps [#next-steps]

<Cards>
  <Card title="Upload a video" href="/studio/upload" />
  <Card title="Invite members" href="/studio/members" />
  <Card title="Run in production" href="/self-hosting/production" />
  <Card title="Set up sign-in" href="/self-hosting/sign-in" />
  <Card title="Stream from Sia in the browser" href="/self-hosting/direct-playback" />
  <Card title="Monitor and maintain" href="/self-hosting/operations" />
</Cards>


# Monitor and maintain (/self-hosting/operations)

This page covers running a Sluby server day to day: the health endpoint, the status view, logs, Prometheus metrics, the storage check that compares your database with Sia, and upgrades.

The commands below are for the base stack. On a production server, add `-f docker-compose.yml -f docker-compose.prod.yml` after `docker compose`.

## Service health [#service-health]

The `postgres`, `redis`, `backend` and `web` services have Docker health checks. See their state with:

```bash
docker compose ps
```

The web proxy starts only after the backend reports healthy, and its own health check goes through to the backend, so `web` turns unhealthy when it can no longer reach the backend.

## Health endpoint [#health-endpoint]

`GET /health` answers while the backend process is up:

```bash
curl http://localhost:8080/health
```

```json
{ "status": "ok", "timestamp": "2026-10-20T09:00:00.000Z", "version": "0.2.0" }
```

It reports liveness only, so a slow indexer never makes Docker restart the backend. The state of the database, Redis and the Sia indexer is in the status view below. The `version` field is the backend's version.

## Status view [#status-view]

Admins see the full status in the Studio under **Deployment** > **Health**: database, Redis, the Sia indexer with account usage and hosts, the last storage check and the delivery cache. See [Overview, health and metrics](/studio/overview).

The same data comes from `GET /api/v1/system/status`. Admins get the full status, members a health summary: [system status reference](/developers/reference/api/ops/get-system-status).

## Logs [#logs]

```bash
docker compose logs -f backend
```

- [`LOG_LEVEL`](/self-hosting/configuration#log_level) sets how much the backend logs.
- With [`NODE_ENV`](/self-hosting/configuration#node_env) set to `production` each line is a JSON object. Otherwise the lines are colored text.
- Requests to `/health` log at `debug`, so the health checks do not fill the log at `info`.
- Docker keeps at most five files of 10 MB of logs per service, then drops the oldest.

## Prometheus metrics [#prometheus-metrics]

The backend serves Prometheus metrics at `GET /metrics` on its port 3000. The Compose files publish no backend port, so a scraper reaches it in one of two ways:

| Scraper                              | URL                                                 | Without `METRICS_TOKEN`                  | With `METRICS_TOKEN`                        |
| ------------------------------------ | --------------------------------------------------- | ---------------------------------------- | ------------------------------------------- |
| On the Compose network               | `http://backend:3000/metrics`                       | Served                                   | Served with `Authorization: Bearer <token>` |
| Anywhere else, through the web proxy | `https://<your domain>/metrics` (your `PUBLIC_URL`) | `404`, as for a path that does not exist | Served with `Authorization: Bearer <token>` |

So metrics are never public: through the web proxy they need [`METRICS_TOKEN`](/self-hosting/configuration#metrics_token), and without it the proxy answers `404` and does not reveal that the endpoint exists. The backend tells the two apart by the `X-Forwarded-For` header, which the web proxy always sets on `/metrics`, replacing any value the client sent. A request with `X-Forwarded-For` or `Forwarded` counts as proxied, so a proxy of your own in front of port 3000 that adds either header is treated the same way.

To scrape from outside the server, set a token:

```bash title=".env"
METRICS_TOKEN=<generated value>
```

and give your scraper the same value as a bearer token, for example in Prometheus:

```yaml title="prometheus.yml"
scrape_configs:
  - job_name: sluby
    scheme: https
    authorization:
      credentials: <generated value>
    static_configs:
      - targets: ['video.example.com']
```

The web proxy limits `/metrics` per client address like sign-in ([`WEB_AUTH_RATE`](/self-hosting/configuration#web_auth_rate) and the settings next to it), which a scrape every few seconds stays well under.

To look at the metrics from the server:

```bash
docker compose exec backend node -e "fetch('http://127.0.0.1:3000/metrics').then(r => r.text()).then(console.log)"
```

Add `{ headers: { Authorization: 'Bearer <token>' } }` as the second argument to `fetch` when a token is set.

Besides the Node.js process metrics, the backend exports:

| Metric                              | Type                  | Meaning                                                                                                     |
| ----------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
| `sluby_upload_success_total`        | counter               | successful uploads                                                                                          |
| `sluby_upload_failure_total`        | counter               | failed uploads                                                                                              |
| `sluby_upload_bytes_total`          | counter               | bytes uploaded                                                                                              |
| `sluby_processing_duration_seconds` | histogram             | time from the start to the end of a video's processing job, counted when the video becomes ready            |
| `sluby_processing_queue_depth`      | gauge                 | jobs waiting or running across the transcode, upload and finalize queues; `NaN` while Redis does not answer |
| `sluby_redis_up`                    | gauge                 | `1` when Redis answered the queue depth read of this scrape within 2 seconds, `0` otherwise                 |
| `sluby_playback_initiation_total`   | counter, label `mode` | playback URLs handed out                                                                                    |
| `sluby_segment_requests_total`      | counter, label `kind` | objects served through the server (`manifest`, `media`, `object`)                                           |
| `sluby_bandwidth_bytes_total`       | counter               | bytes served through the server                                                                             |
| `sluby_cache_hits_total`            | counter               | whole-object cache lookups served from memory                                                               |
| `sluby_cache_misses_total`          | counter               | whole-object cache lookups that fetched the object from Sia                                                 |
| `sluby_sia_upload_duration_seconds` | histogram             | time of each upload to Sia (one upload carries several objects packed together)                             |

## Storage check [#storage-check]

The storage check (reconciliation) compares the objects your database expects with what the indexer stores, and reports the differences. It runs on a schedule, and a separate sweep on its own schedule finishes deletions that stopped partway. What the report means: [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation).

- **In the Studio**: an admin sees the result on the **Storage check** card of the Health page and starts a run with **Check now**.
- **With the API**: read the latest report with [`GET /api/v1/reconciliation`](/developers/reference/api/reconciliation/get-reconciliation) and start a run with [`POST /api/v1/reconciliation/run`](/developers/reference/api/reconciliation/post-reconciliation-run), which needs an admin's key with the `manage` scope.

Turn the schedules on or off and change their intervals with [`RECONCILE_ENABLED`](/self-hosting/configuration#reconcile_enabled), [`RECONCILE_INTERVAL_MS`](/self-hosting/configuration#reconcile_interval_ms), [`DELETION_GC_ENABLED`](/self-hosting/configuration#deletion_gc_enabled) and [`DELETION_GC_INTERVAL_MS`](/self-hosting/configuration#deletion_gc_interval_ms). The configuration reference lists each default.

## Housekeeping the backend does [#housekeeping-the-backend-does]

At startup and then every hour, the backend cleans up on its own. Nothing needs to be scheduled for this. It removes:

- uploads that expired unfinished ([when an upload expires](/developers/concepts/upload-pipeline#unfinished-and-cancelled-uploads));
- source files it no longer needs;
- ended Studio sessions past their retention ([sessions](/developers/concepts/accounts-and-roles#sessions));
- webhook delivery records past their retention ([delivery log](/developers/reference/webhook-events#delivery-log)).

## Upgrade [#upgrade]

<Steps>
<Step>

### Get the new code [#get-the-new-code]

```bash
git pull
```

</Step>
<Step>

### Rebuild and restart [#rebuild-and-restart]

```bash
docker compose up -d --build
```

</Step>
<Step>

### Check the migrations [#check-the-migrations]

The backend applies database migrations every time its container starts, before it takes requests, and skips the ones it already applied. Check the log:

```bash
docker compose logs backend | grep -i migration
```

A successful start logs `Running migrations...` and `Migrations complete.` A failed one logs `Migration failed:` with the error, and the backend does not start.

</Step>
</Steps>

When several backend containers start at once, they apply migrations one at a time; the later ones find nothing left to do.

On stop or restart, the backend stops taking requests and gives running work 25 seconds to finish. Docker waits 30 seconds before it kills the container.

## Related [#related]

- [Troubleshooting](/self-hosting/troubleshooting)
- [Configuration reference](/self-hosting/configuration)


# Run in production (/self-hosting/production)

This page puts your Sluby server on a public domain over HTTPS. The production override, `docker-compose.prod.yml`, adds Caddy in front of the stack, which gets and renews a TLS certificate for your domain. It also turns on the production checks, requires the secrets, and publishes nothing but ports 80 and 443.

Install the stack first with [Install Sluby](/self-hosting) and connect it to Sia with [Connect Sia storage](/self-hosting/sia-storage). This page assumes the Sluby folder and its `.env`.

## Before you start [#before-you-start]

- A domain or subdomain, for example `sluby.example.com`, whose A or AAAA record points at the server.
- Ports 80 and 443 of the server reachable from the internet. The override publishes `80/tcp`, `443/tcp` and `443/udp` for Caddy.

## Deploy [#deploy]

<Steps>
<Step>

### Generate the secrets [#generate-the-secrets]

Generate one value for the database password and one for the session secret:

```bash
openssl rand -hex 32
openssl rand -base64 32
```

Use the hex value for the database password. Compose puts the password inside the database URL, and a `/` (which base64 output can contain) makes that URL invalid, so the backend refuses to start.

</Step>
<Step>

### Set the production lines in .env [#set-the-production-lines-in-env]

```bash title=".env"
DOMAIN=sluby.example.com
ACME_EMAIL=you@example.com
POSTGRES_PASSWORD=<the hex value>
SESSION_SECRET=<the base64 value>
SIA_APP_ID=<from connect-indexer.mjs>
SIA_APP_KEY=<from connect-indexer.mjs>
```

Compose refuses to start the production stack while any of these six is empty. What each one does: [`DOMAIN`](/self-hosting/configuration#domain), [`ACME_EMAIL`](/self-hosting/configuration#acme_email), [`POSTGRES_PASSWORD`](/self-hosting/configuration#postgres_password), [`SESSION_SECRET`](/self-hosting/configuration#session_secret), [`SIA_APP_ID`](/self-hosting/configuration#sia_app_id), [`SIA_APP_KEY`](/self-hosting/configuration#sia_app_key).

</Step>
<Step>

### Start the stack [#start-the-stack]

```bash
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
```

Use both `-f` files in every later `docker compose` command on this server, so Compose keeps the production settings.

</Step>
<Step>

### Create the first admin [#create-the-first-admin]

```bash
docker compose -f docker-compose.yml -f docker-compose.prod.yml logs backend | grep "setup code"
```

Open `https://sluby.example.com/studio`, click **Set up the first admin** and enter the code. More on the setup code: [Create the first admin](/self-hosting/sign-in#create-the-first-admin).

</Step>
</Steps>

## What the override changes [#what-the-override-changes]

| Setting                                            | Base stack                | With `docker-compose.prod.yml`                                                             |
| -------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
| Published ports                                    | `web` on `127.0.0.1:8080` | `caddy` on `80`, `443` and `443/udp`; nothing else                                         |
| TLS                                                | none                      | Caddy, for `DOMAIN`                                                                        |
| [`NODE_ENV`](/self-hosting/configuration#node_env) | `development`             | `production`                                                                               |
| `PUBLIC_URL`                                       | `http://localhost:8080`   | `https://` plus `DOMAIN`                                                                   |
| `CORS_ORIGIN`                                      | empty                     | `https://` plus `DOMAIN`                                                                   |
| `AUTH_DISABLED`                                    | from `.env`               | always `false`                                                                             |
| Required in `.env`                                 | nothing                   | `DOMAIN`, `ACME_EMAIL`, `POSTGRES_PASSWORD`, `SESSION_SECRET`, `SIA_APP_ID`, `SIA_APP_KEY` |

The override sets `NODE_ENV`, `PUBLIC_URL`, `CORS_ORIGIN` and `AUTH_DISABLED` itself, so values for them in `.env` have no effect on the production stack.

With `NODE_ENV=production` the backend runs its startup checks and writes JSON logs. What it checks: [`NODE_ENV`](/self-hosting/configuration#node_env).

Caddy compresses responses with zstd or gzip, sends `Strict-Transport-Security: max-age=31536000`, removes the `Server` header and passes every request to the `web` service.

## Move a local install to production [#move-a-local-install-to-production]

The production stack uses the same volumes as the local stack, so your videos and accounts stay. Two settings behave differently when the data already exists:

- **`POSTGRES_PASSWORD`**: the `postgres` image sets the password only when it creates the database on an empty volume. A database created by the local stack keeps the password it started with: `sluby`, unless you set `POSTGRES_PASSWORD` before its first start. While the local stack is still running, change the password inside the database to the hex value you generated:

  ```bash
  docker compose exec postgres psql -U sluby -d sluby -c "ALTER USER sluby PASSWORD '<the hex value>'"
  ```

  Then set the same value as `POSTGRES_PASSWORD` in `.env`.

- **`SESSION_SECRET`**: the local stack ran with a secret it generated and stored in its database. Setting your own secret signs everyone out and makes signed links handed out earlier stop working ([`SESSION_SECRET`](/self-hosting/configuration#session_secret)). Accounts stay in the database, so an admin who could sign in before can sign in again. When no admin can sign in, the backend logs a new setup code at start: [Create the first admin](/self-hosting/sign-in#create-the-first-admin).

## Run behind your own proxy [#run-behind-your-own-proxy]

If the server already has a reverse proxy that terminates TLS, run the base stack without the override and point your proxy at the web service on `127.0.0.1:8080` (or the port in [`WEB_PORT`](/self-hosting/configuration#web_port)).

Set these lines in `.env`:

```bash title=".env"
NODE_ENV=production
PUBLIC_URL=https://sluby.example.com
CORS_ORIGIN=https://sluby.example.com
POSTGRES_PASSWORD=<openssl rand -hex 32>
SESSION_SECRET=<openssl rand -base64 32>
```

Start the base stack:

```bash
docker compose up -d --build
```

Configure your proxy to:

- pass the original `Host` header, `X-Forwarded-For` and `X-Forwarded-Proto: https`. The web service takes the client address from `X-Forwarded-For` when the connection comes from a loopback or private address, and passes the scheme on to the backend.
- accept request bodies of at least 10 MiB. The Studio uploads in 8 MiB chunks and `@sluby/sdk` in 10 MiB chunks by default ([`chunkSize`](/developers/reference/sdk#uploadfileoptions)).
- send `Strict-Transport-Security` if you want HSTS. The web service does not send it.

## Related [#related]

- [Configuration reference](/self-hosting/configuration)
- [Set up sign-in](/self-hosting/sign-in), including GitHub sign-in for your domain
- [Monitor and maintain](/self-hosting/operations)


# Connect Sia storage (/self-hosting/sia-storage)

Sluby stores every video on Sia through an indexer: a service your server talks to over HTTP that keeps track of the hosts holding your data. This page connects your server to an indexer once and gives you the two lines that identify it, `SIA_APP_ID` and `SIA_APP_KEY`.

The default indexer is [sia.storage](https://sia.storage). Before you start, create an account there and sign in to it in your browser.

## Connect the server [#connect-the-server]

Run these commands in the folder where you cloned Sluby, with `.env` already created from `.env.example`.

<Steps>
<Step>

### Build the backend image [#build-the-backend-image]

```bash
docker compose build backend
```

</Step>
<Step>

### Run the connect script [#run-the-connect-script]

```bash
docker compose run --rm --no-deps backend node scripts/connect-indexer.mjs
```

The script prints `Connecting Sluby to the indexer at https://sia.storage`, then a URL under `1. Open this URL while signed in to your indexer account and approve it:`.

</Step>
<Step>

### Approve the connection [#approve-the-connection]

Open the URL in the browser where you are signed in to your indexer account and approve it. The script waits at `2. Waiting for approval...` and continues on its own once you approve. You never enter a recovery phrase or password in the script.

</Step>
<Step>

### Copy the lines into .env [#copy-the-lines-into-env]

After approval the script prints:

```text
Connected. Add these to .env:

SIA_INDEXER_URL=https://sia.storage
SIA_APP_ID=<64 hex characters>
SIA_APP_KEY=<64 hex characters>
```

In `.env`, replace the `SIA_INDEXER_URL`, `SIA_APP_ID` and `SIA_APP_KEY` lines with these three.

If the script also prints `The account is not ready yet: it is still forming storage contracts.`, start Sluby anyway. Uploads start working once your indexer dashboard shows the indexer as operational.

</Step>
<Step>

### Start or restart Sluby [#start-or-restart-sluby]

```bash
docker compose up -d
```

On a production server, add the same `-f docker-compose.yml -f docker-compose.prod.yml` you start it with.

The backend logs `sia-storage SDK ready` once it is connected:

```bash
docker compose logs backend | grep "sia-storage SDK ready"
```

</Step>
</Steps>

<Callout type="warn" title="Keep SIA_APP_KEY secret">
  `SIA_APP_KEY` can read and delete everything this server stores on Sia. Keep `.env` out of version
  control and out of backups that other people can read.
</Callout>

## Use another indexer [#use-another-indexer]

To connect to an indexer other than sia.storage, pass its base URL to the script. The URL must use `http` or `https`, and the backend container must be able to reach it.

```bash
docker compose run --rm --no-deps backend node scripts/connect-indexer.mjs https://indexer.example.com
```

The script prints `SIA_INDEXER_URL` with that URL; copy it into `.env` together with the app ID and key. Without an argument the script uses `SIA_INDEXER_URL` from `.env`, and `https://sia.storage` when that is empty.

Set [`SIA_NETWORK`](/self-hosting/configuration#sia_network) to the network that indexer runs on, for example:

```bash title=".env"
SIA_NETWORK=zen
```

For a self-hosted indexd, four more lines are optional: its admin API address and password, and the shard counts. Read what each one does in the configuration reference before you set it:

```bash title=".env"
SIA_ADMIN_URL=http://indexd.example.com:9980
SIA_ADMIN_PASSWORD=<indexd admin password>
SIA_DATA_SHARDS=<data shards>
SIA_PARITY_SHARDS=<parity shards>
```

See [`SIA_ADMIN_URL`](/self-hosting/configuration#sia_admin_url), [`SIA_ADMIN_PASSWORD`](/self-hosting/configuration#sia_admin_password), [`SIA_DATA_SHARDS`](/self-hosting/configuration#sia_data_shards) and [`SIA_PARITY_SHARDS`](/self-hosting/configuration#sia_parity_shards).

## Connect again [#connect-again]

Each run of the script registers a new app with the indexer. When `SIA_APP_KEY` is already set, the script says so first: `SIA_APP_KEY is already set; connecting again registers a second app.` The backend uses the app in `.env` for every upload, read and delete on Sia, so keep the app ID and key your videos were uploaded with.

## Related [#related]

- [How Sluby stores videos on Sia](/developers/concepts/storage-on-sia)
- [Stream from Sia in the browser](/self-hosting/direct-playback), which registers a second, public viewer identity
- [Troubleshooting Sia connection errors](/self-hosting/troubleshooting#sia-storage)


# Set up sign-in (/self-hosting/sign-in)

People sign in to the Studio with an email and password, and with GitHub when you add a GitHub OAuth app. This page covers what you do on the server: claim a fresh install with the setup code, turn on GitHub sign-in, make a reset link for a locked-out admin, and turn sign-in off for local development. Inviting people and changing roles happens in the Studio: [Invite and manage members](/studio/members).

The commands below are for the base stack. On a production server, add `-f docker-compose.yml -f docker-compose.prod.yml` after `docker compose`.

## Create the first admin [#create-the-first-admin]

While no admin can sign in, the backend logs a setup code at every start. Whoever can read the server's logs can claim the install with it.

<Steps>
<Step>

### Read the code from the log [#read-the-code-from-the-log]

```bash
docker compose logs backend | grep "setup code"
```

```text
No admin can sign in yet. Open http://localhost:8080/studio and set up the first admin with the setup code XXXXX-XXXXX.
```

The address in the line comes from [`PUBLIC_URL`](/self-hosting/configuration#public_url).

</Step>
<Step>

### Fill in the setup form [#fill-in-the-setup-form]

Open the Studio, click **Set up the first admin**, and fill in **Setup code**, **Your name**, **Email** and **Password** (at least 10 characters). Click **Create admin account**. The Studio signs you in as an admin.

The code ignores case, spaces and dashes.

</Step>
</Steps>

The setup code is derived from [`SESSION_SECRET`](/self-hosting/configuration#session_secret), so it changes when the secret changes. Once an admin exists, the form answers `This server already has an admin. Sign in instead.` Whenever no admin can sign in, the backend logs a setup code again at its next start.

## Add GitHub sign-in [#add-github-sign-in]

GitHub sign-in lets in members whose account has GitHub linked (on their Settings page, or by joining with GitHub from an invite link) and people who open an invite link. Anyone else who tries it sees a message that their GitHub account is not a member of the workspace.

<Steps>
<Step>

### Create a GitHub OAuth app [#create-a-github-oauth-app]

Open [GitHub developer settings](https://github.com/settings/developers) and create a new OAuth app. Set **Authorization callback URL** to your `PUBLIC_URL` followed by `/api/v1/auth/github/callback`:

```text
https://sluby.example.com/api/v1/auth/github/callback
```

For the local stack it is `http://localhost:8080/api/v1/auth/github/callback`. Sluby asks GitHub for the `read:user` scope only.

</Step>
<Step>

### Put the client ID and secret in .env [#put-the-client-id-and-secret-in-env]

```bash title=".env"
GITHUB_CLIENT_ID=<client id>
GITHUB_CLIENT_SECRET=<client secret>
```

See [`GITHUB_CLIENT_ID`](/self-hosting/configuration#github_client_id) and [`GITHUB_CLIENT_SECRET`](/self-hosting/configuration#github_client_secret).

</Step>
<Step>

### Restart the backend [#restart-the-backend]

```bash
docker compose up -d
```

The sign-in screen now offers GitHub. Members link their GitHub account from Settings: [Link your GitHub account](/studio/account#link-your-github-account).

</Step>
</Steps>

## Make a reset link from the command line [#make-a-reset-link-from-the-command-line]

Admins make reset links for members on the Members page ([Give someone a reset link](/studio/members#give-someone-a-reset-link)). When no admin can sign in to make one, for example because the only admin forgot their password, make it on the server:

```bash
docker compose exec backend node dist/db/reset-link.js --email you@example.com
```

```text
Reset link for <name>:

  https://sluby.example.com/studio/reset/<token>

It works once, until <date>. Using it sets a new password and signs out every other session of the account.
```

The link works once and for 7 days. The script finds the account by the email it signs in with, so it cannot make a link for an account that signs in with GitHub only. For a removed account it refuses and says that an admin can restore it on the Members page.

When you run the backend from source, use `npm run admin:reset-link --workspace=backend -- --email you@example.com` instead.

## Create an admin API key from the command line [#create-an-admin-api-key-from-the-command-line]

To call the API before anyone has signed in, for example from a provisioning script, create a key with every scope on the server:

```bash
docker compose exec backend node dist/db/seed-api-key.js --name provisioning
```

The script prints the key once, after `Key:`. The key acts as an admin. To have the backend create a key you choose at startup instead, set [`BOOTSTRAP_API_KEY`](/self-hosting/configuration#bootstrap_api_key). What each scope allows: [Scopes](/developers/reference/api-conventions#scopes).

## Turn sign-in off for local development [#turn-sign-in-off]

On a machine only you can reach, skip sign-in with this line:

```bash title=".env"
AUTH_DISABLED=true
```

Run `docker compose up -d` to apply it. Every visitor then acts as one local admin account, and the Studio shows a banner that starts with **Sign-in is off.** What the setting allows and where it is refused: [`AUTH_DISABLED`](/self-hosting/configuration#auth_disabled).

To turn sign-in back on, set `AUTH_DISABLED=false` and run `docker compose up -d` again.

## Related [#related]

- [Accounts, roles and sessions](/developers/concepts/accounts-and-roles)
- [Sign in and out](/studio/sign-in), from the Studio side
- [Sign-in problems](/self-hosting/troubleshooting#sign-in)


# Troubleshooting (/self-hosting/troubleshooting)

Each entry quotes the exact text Sluby prints or shows, then gives the cause and the fix. To read the backend's log, run `docker compose logs backend` in the Sluby folder. On a production server, add `-f docker-compose.yml -f docker-compose.prod.yml` after `docker compose` in every command on this page.

After you change `.env`, run `docker compose up -d` so Compose recreates the containers whose settings changed. Variable meanings are in the [configuration reference](/self-hosting/configuration).

## Docker Compose and image builds [#docker-compose-and-image-builds]

### required variable DOMAIN is missing a value [#required-variable-domain-is-missing-a-value]

```text
required variable DOMAIN is missing a value: set DOMAIN in .env
```

`docker-compose.prod.yml` stops before starting anything while a variable it requires is empty, and the message names the variable ([the list](/self-hosting/configuration#production-with-caddy)). For `SIA_APP_ID` and `SIA_APP_KEY` the message ends with `run the indexer connect step and set SIA_APP_ID` (or `SIA_APP_KEY`). Set the variable in `.env` ([Run in production](/self-hosting/production)); for the Sia values, run the connect step in [Connect Sia storage](/self-hosting/sia-storage).

### The backend image builds only with BuildKit [#the-backend-image-builds-only-with-buildkit]

```text
the backend image builds for linux/amd64 and linux/arm64 with buildkit only, not '<arch>'
```

The backend image builds for `linux/amd64` and `linux/arm64` only, and only with BuildKit. The build targeted another platform, or ran without BuildKit, which leaves the architecture empty (`''` in the message). Build for `amd64` or `arm64` with BuildKit enabled.

### A web proxy limit is not valid [#a-web-proxy-limit-is-not-valid]

```text
WEB_DELIVERY_RATE=fast is not valid (expected a rate such as 50r/s or 600r/m)
```

The `web` container checks its `WEB_` limits at start and exits when one is malformed. Rates take the form `<number>r/s` or `<number>r/m`; bursts and connection counts are whole numbers. Fix the value in `.env`. See [`WEB_DELIVERY_RATE`](/self-hosting/configuration#web_delivery_rate).

## The backend refuses to start [#the-backend-refuses-to-start]

The backend checks its settings before it does anything else. When one is wrong it prints this and exits:

```text
Refusing to start, the configuration is not valid:
  <one line per problem>
```

The problem lines it prints:

| Problem line                                                                                                                                                                        | Fix                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `SESSION_SECRET is not set. Set a strong one (openssl rand -base64 32), so sessions survive restarts and cannot be forged.`                                                         | Production only. Set [`SESSION_SECRET`](/self-hosting/configuration#session_secret) to the output of `openssl rand -base64 32`. |
| `SESSION_SECRET is only <n> characters (minimum 32).`                                                                                                                               | Production only. Use a secret of at least 32 characters, such as the output of `openssl rand -base64 32`.                       |
| `SESSION_SECRET is the old development default, which is public.`                                                                                                                   | Production only. Generate a new secret with `openssl rand -base64 32`.                                                          |
| `AUTH_DISABLED=true gives every visitor full access.`                                                                                                                               | Production only. Set `AUTH_DISABLED=false`.                                                                                     |
| `BOOTSTRAP_API_KEY is not a generated key (sluby_ and at least 32 more letters, digits, - or _). Generate one: ...`                                                                 | Production only. Generate a key with the `node -e` command the message prints, or remove the line.                              |
| `AUTH_DISABLED: Invalid option: expected one of "0"\|"1"\|"true"\|"false"`                                                                                                          | On/off settings accept only `true`, `false`, `1` and `0`. The same message names any other on/off setting.                      |
| `CORS_ORIGIN: "https://a.example.com/" is not an origin (scheme://host[:port], no path or trailing slash). Leave CORS_ORIGIN unset to let any origin call the API without cookies.` | Write each origin as `https://host` or `https://host:port`, with no path and no trailing slash.                                 |
| `TRANSCODE_MAX_RENDITION: Invalid option: expected one of "2160p"\|"1440p"\|"1080p"\|"720p"\|"540p"\|"360p"`                                                                        | Use one of the listed values.                                                                                                   |
| `RECONCILE_PAGE_SIZE: Too big: expected number to be <=500`                                                                                                                         | Use `500` or less.                                                                                                              |
| `WEBHOOK_ALLOWED_NETWORKS: not an IP address or network: <value>`                                                                                                                   | List CIDRs or addresses, such as `10.0.5.0/24`.                                                                                 |
| `OPERATOR_USERS: "<value>" names no sign-in provider: write <provider>:<entry>, such as github:id:583231 or github:octocat`                                                         | Fix the entry or remove the setting.                                                                                            |

Any other line has the form `<VARIABLE>: <problem>` and names the setting to fix.

### Migration failed [#migration-failed]

```text
Migration failed: <error>
```

The backend could not apply the database migrations at start, so the container stops. The error that follows says why. When the backend cannot log in to PostgreSQL, check `POSTGRES_PASSWORD`: the database keeps the password it was created with, see [Move a local install to production](/self-hosting/production#move-a-local-install-to-production).

### Could not load or store the session secret [#could-not-load-or-store-the-session-secret]

```text
Could not load or store the session secret
```

Outside production, without `SESSION_SECRET`, the backend keeps a generated secret in its database. This line means it could not read or write it, which stops the start. The error logged with it says why; check that PostgreSQL is up with `docker compose ps`.

### Could not seed BOOTSTRAP_API_KEY [#could-not-seed-bootstrap_api_key]

```text
Could not seed BOOTSTRAP_API_KEY
```

The backend could not create the key from [`BOOTSTRAP_API_KEY`](/self-hosting/configuration#bootstrap_api_key) and stops. The error logged with it says why.

## Warnings at startup [#warnings-at-startup]

| Log line                                                                                                                            | What to do                                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `PUBLIC_URL is http on <host>: Studio session cookies are sent without TLS and are not marked Secure. Serve the Studio over https.` | Serve the Studio over HTTPS and set `PUBLIC_URL` to the `https://` address: [Run in production](/self-hosting/production). |
| `GITHUB_ALLOWED_USERS is set but ignored: ...`                                                                                      | The setting was read once during the upgrade to members and roles. Remove it from `.env`.                                  |
| `OPERATOR_USERS is set but ignored: ...`                                                                                            | Same as above. Remove it from `.env`.                                                                                      |
| `BOOTSTRAP_API_KEY was deleted or rotated away earlier and is not seeded again. Remove it from the environment, or set a new key.`  | Remove the line, or set a new generated key to get another bootstrap key.                                                  |
| `EXPOSE_ERROR_STACKS is on: error responses carry internal messages and stack traces`                                               | Set `EXPOSE_ERROR_STACKS=false` once you are done debugging.                                                               |

## Sia storage [#sia-storage]

### SIA_APP_KEY is not set [#sia_app_key-is-not-set]

```text
SIA_APP_KEY is not set: uploads need an indexer connection (see connect-indexer)
```

The backend runs, but uploads cannot reach Sia. Run the connect step in [Connect Sia storage](/self-hosting/sia-storage) and put `SIA_APP_ID` and `SIA_APP_KEY` in `.env`.

### SIA_APP_KEY is not registered with the indexer [#sia_app_key-is-not-registered-with-the-indexer]

```text
Could not connect to the Sia indexer at startup
```

The error logged with it reads:

```text
SIA_APP_KEY is not registered with the indexer at SIA_INDEXER_URL. Run npm run connect-indexer against that indexer and set the SIA_APP_ID and SIA_APP_KEY it prints.
```

The indexer at `SIA_INDEXER_URL` does not know this app key. Check that `SIA_INDEXER_URL` is the indexer you ran the connect step against. If it is, run the connect step again and put the new values in `.env`. For any other error logged with `Could not connect to the Sia indexer at startup`, the backend tries again on the next upload or status check; check that the indexer URL is reachable from the server.

### The connect script fails [#the-connect-script-fails]

```text
Connecting failed: <message>
```

`connect-indexer.mjs` stopped before it finished. `provision-viewer.mjs` prints `Provisioning failed: <message>` in the same case. The text after the colon says why. Run the script again, open the URL it prints while signed in to your indexer account, and approve the connection.

```text
"<value>" is not an http or https url
```

The indexer URL passed to the script, or `SIA_INDEXER_URL`, is not an `http` or `https` URL. Pass the full URL, such as `https://sia.storage`.

### The account is not ready yet [#the-account-is-not-ready-yet]

```text
The account is not ready yet: it is still forming storage contracts. Uploads start working once the dashboard shows the indexer as operational.
```

The connection worked and the values it printed are valid. Put them in `.env` and wait until your indexer dashboard shows the indexer as operational before you upload.

### An upload to Sia stored nothing [#an-upload-to-sia-stored-nothing]

```text
Sia upload stored nothing for 600s and was cancelled
```

The backend stopped an upload to Sia because no part of it was stored on a host for 10 minutes. Check the Sia indexer on the Studio's Health page ([Overview, health and metrics](/studio/overview)), then retry the video ([Follow processing and retry](/studio/processing)).

## Sign-in [#sign-in]

| Message                                                                                                | Cause and fix                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `That setup code is wrong. Copy it from the server log.`                                               | Read the current code with `docker compose logs backend \| grep "setup code"` and use the newest line. The code changes when `SESSION_SECRET` changes.                                                                                                                                                                                    |
| `This server already has an admin. Sign in instead.`                                                   | An admin exists. Sign in, or make a reset link: [Set up sign-in](/self-hosting/sign-in#make-a-reset-link-from-the-command-line).                                                                                                                                                                                                          |
| `Sign-in with GitHub is not set up on this server.`                                                    | Set both `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` and restart: [Add GitHub sign-in](/self-hosting/sign-in#add-github-sign-in).                                                                                                                                                                                                       |
| `GitHub account <login> is not a member of this workspace. Ask an admin for an invite.`                | GitHub sign-in works only for members whose account has GitHub linked and for people joining with an invite. An admin invites the person: [Invite someone](/studio/members#invite-someone).                                                                                                                                               |
| `You signed in, but this browser did not keep the session. Allow cookies for this site and try again.` | The browser blocks cookies for this site, or the Studio is open at another address than `PUBLIC_URL`. When `PUBLIC_URL` starts with `https://`, the session cookie is marked `Secure`, and a browser does not keep a `Secure` cookie on a plain `http://` address other than `localhost`. Open the Studio at the address in `PUBLIC_URL`. |

If GitHub refuses to send you back to Sluby after sign-in, compare the OAuth app's **Authorization callback URL** with `PUBLIC_URL` followed by `/api/v1/auth/github/callback`. Sluby sends that address to GitHub, and GitHub accepts it only when it matches the app's callback URL.

For a member who forgot their password, an admin makes a reset link on the Members page. For a locked-out admin, see [Make a reset link from the command line](/self-hosting/sign-in#make-a-reset-link-from-the-command-line).

## Rate limits [#rate-limits]

```text
Too many requests. Try again in a few seconds.
```

A client went over a per-address limit and got status `429` with this message in the `error` field of the JSON body. The web proxy limits video delivery and sign-in per client address ([`WEB_DELIVERY_RATE`](/self-hosting/configuration#web_delivery_rate), [`WEB_AUTH_RATE`](/self-hosting/configuration#web_auth_rate) and the settings next to them). The backend limits API calls made without a valid key or session per client address ([`API_IP_RATE_LIMIT`](/self-hosting/configuration#api_ip_rate_limit)), and holds each API key and session to its own per-minute limit ([Rate limits](/developers/reference/api-conventions#rate-limits)). When many viewers share one address, such as an office network, raise the matching per-address limit.

## Direct playback [#direct-playback]

**The player badge keeps reading Through this server.** The Studio streams from Sia only when all three `VITE_SLUBY_SIA_` values were set when the web image was built. Check the three lines in `.env`, then rebuild with `docker compose up -d --build web`. See [Stream from Sia in the browser](/self-hosting/direct-playback). The badge also reads **Through this server** in a browser where hls.js cannot run and the video plays natively, such as Safari on some iPhones.

**The browser console shows `Sluby: Sia is unavailable for now, playing through the gateway.`** The player could not read from Sia and plays through your server. Check that `VITE_SLUBY_SIA_INDEXER_URL` starts with `https://` (the Studio's Content Security Policy blocks other addresses), and that the viewer account is ready: `provision-viewer.mjs` reports when contracts are still forming and the account needs a balance to pay egress.

## Metrics [#metrics]

```json
{ "error": "Metrics token required" }
```

[`METRICS_TOKEN`](/self-hosting/configuration#metrics_token) is set and the request to `/metrics` sent no token or a different one. Send `Authorization: Bearer <token>` with the value of `METRICS_TOKEN`. See [Monitor and maintain](/self-hosting/operations#prometheus-metrics).

When `METRICS_TOKEN` is not set, `/metrics` through the web proxy answers `404` instead (`Route GET /metrics not found`): set a token to scrape from outside the Compose network.


# Manage your account (/studio/account)

The **Settings** page shows who you are signed in as and lets you change how you sign in, end sessions on other browsers, and choose the Studio's theme. Open it from **Settings** at the bottom of the sidebar. Every member and admin can use it.

## Account [#account]

The **Account** section shows your name, the email or GitHub `@login` you signed in with, and your role: **Admin** or **Member**.

## Change your name [#change-your-name]

<Steps>
  <Step>In the **Account** section, click **Edit name**.</Step>
  <Step>Type your **Name**, up to 100 characters, and click **Save name**.</Step>
</Steps>

Your team sees the new name on the **Members** page. Signing in with GitHub keeps the name you chose.

## Change your email [#change-your-email]

The email is the one you sign in with. Your password stays the same.

<Steps>
  <Step>Under **Sign-in methods**, click **Change email** in the **Password** row.</Step>
  <Step>Enter the **New email** and your **Current password**.</Step>
  <Step>Click **Change email**.</Step>
</Steps>

From then on you sign in with the new email; the old one no longer works. If another member already signs in with that email, the dialog says "Another account already signs in with this email." under **New email**.

## Change your password [#change-your-password]

<Steps>
  <Step>Under **Sign-in methods**, click **Change password** in the **Password** row.</Step>
  <Step>
    Enter your **Current password**, then a **New password** of at least 10 characters, and type it
    again in **Confirm new password**.
  </Step>
  <Step>Click **Change password**.</Step>
</Steps>

This browser stays signed in. Every other browser signed in as you is signed out, and the confirmation says how many, for example "Password changed. Signed out 2 other browsers."

If the current password is wrong, the dialog shows "Your current password is wrong." under that field. For all password rules, see [Password rules](/studio/sign-in#password-rules).

If the **Password** row says "Ask an admin for a reset link to add a password.", your account has no password yet. An admin can give you one with a [reset link](/studio/members#give-someone-a-reset-link).

## Link your GitHub account [#link-your-github-account]

The **GitHub** row appears when the server offers GitHub sign-in. If it says **Not linked to this account.**:

<Steps>
  <Step>Click **Link GitHub**.</Step>
  <Step>Finish signing in on GitHub.</Step>
</Steps>

GitHub sends you back to **Settings**, and the row shows your `@login`. From then on you can use **Continue with GitHub** on the sign-in screen ([Sign in with GitHub](/studio/sign-in#sign-in-with-github)).

A GitHub account can belong to only one member. If it already belongs to someone else, nothing is linked and the Studio shows, for example, "GitHub account example-dev already belongs to another member."

## Remove GitHub [#remove-github]

When your account has both a password and GitHub, the **GitHub** row has a **Remove** button:

<Steps>
  <Step>Click **Remove** in the **GitHub** row.</Step>
  <Step>Click **Remove** again in the dialog.</Step>
</Steps>

You then sign in with your email and password only, and browsers that signed in with GitHub are signed out. You can link GitHub again later.

The **Remove** button does not appear when this browser signed in with GitHub (sign in with your password first), or when GitHub is your only way to sign in.

## Sign out other browsers [#sign-out-other-browsers]

The **Signed-in browsers** section lists every browser where you are signed in, for example "Chrome on macOS". The browser you are using has a **This browser** badge. Each row says when the browser was last active and when it signed in. Hover over that line to see when the session expires.

- To sign out one other browser, click **End session** on its row.
- To sign out every browser, this one included, click **Sign out everywhere**, then **Sign out everywhere** again in the dialog. You return to the sign-in screen. Your API keys keep working.

To sign out only this browser, click **Sign out** in the account menu ([Sign out](/studio/sign-in#sign-out)).

## Choose a theme [#choose-a-theme]

Under **Appearance**, pick **System**, **Light** or **Dark**. **System** is the default and follows your operating system's setting. The choice is saved in this browser only, so other browsers keep their own.

You can also change the theme from **Theme** in the account menu. The sun or moon button next to the account menu switches straight between light and dark.

## When sign-in is off [#when-sign-in-is-off]

If the server runs with sign-in turned off, **Account** says "Sign-in is off on this server." and the **Sign-in methods** and **Signed-in browsers** sections do not appear. **Appearance** works as usual.


# Create and manage API keys (/studio/api-keys)

An API key lets your server call the Sluby REST API and SDK. Create, rotate and revoke keys on the **API keys** page, under **Developers** in the sidebar. Members and admins can both use it.

<Callout type="warn" title="Keys are server secrets">
  Never put an API key in browser code. The Studio shows a new key only once, so copy it straight
  into your server's configuration.
</Callout>

## Create a key [#create-a-key]

<Steps>
  <Step>On the **API keys** page, click **Create key**.</Step>
  <Step>
    Enter a **Name** that tells you where the key is used, for example "Production web app". Names
    can be up to 100 characters.
  </Step>
  <Step>
    Under **Scopes**, tick what the key can do. **upload** and **read** are ticked by default. Tick
    at least one.
  </Step>
  <Step>
    Set the **Rate limit** in requests per minute. The default is 100, and the line under the field
    shows the highest value this server allows.
  </Step>
  <Step>Click **Create key**.</Step>
</Steps>

A notice appears above the table: **Key “Production web app” created** and "Copy it now. It is shown only once." Click **Copy key**, then close the notice. To check the key on screen, click **Show**.

If you close the notice before copying, the Studio asks **Close without copying?** first. If you follow a link to another Studio page, it asks **Leave without the key?**, and if you reload or close the tab, the browser asks you to confirm. A key you did not copy cannot be shown again; create or rotate another one instead.

## Scopes [#scopes]

Each key has one or more scopes:

- **upload**: Upload videos.
- **read**: See videos, playback URLs and storage details.
- **manage**: Edit and delete videos, keys and webhooks.

For exactly which API calls each scope allows, see [Scopes](/developers/reference/api-conventions#scopes).

## The keys table [#the-keys-table]

The page header shows how many keys you have and how many the server allows, for example "2 of 100 used." The table lists every key in the Studio, whoever created it. The columns are:

- **Name**: the name you gave the key.
- **Key**: the first characters of the key, so you can match it to the one on your server.
- **Can**: the key's scopes.
- **Last used**: when the key last made a request, or **Never**.
- **Created** and **Created by**: when and by whom. **Server** means the key was made on the server, not by a member.
- **Status**: **Active**, or **Replaced** with the time left for an old key that is being rotated out.

Narrow screens hide some columns.

A key acts with the role of the member who created it, and a key made on the server acts as an admin. While the member who created a key is [removed](/studio/members#remove-a-member), the key stops working; it works again when the member is restored.

## Rename a key [#rename-a-key]

Open the row menu and choose **Rename**, or click the key's name. Type the new name and press Enter (or click outside the field) to save, or press Escape to cancel. The key itself does not change.

## Rotate a key [#rotate-a-key]

Rotating gives you a new key with the same name, scopes and rate limit, while the old key keeps working long enough for your servers to switch. The new key counts as created by you, so it acts with your role.

<Steps>
  <Step>Open the row menu of the key and choose **Rotate**.</Step>
  <Step>
    Under **Old key keeps working for**, pick **1 hour**, **1 day**, **7 days** or **Stop now**. **1
    hour** is the default.
  </Step>
  <Step>Click **Rotate key**.</Step>
  <Step>Copy the new key from the notice and update your servers.</Step>
</Steps>

The notice says when the old key stops working. Until then the old key stays in the table with the status **Replaced** and the time left. A replaced key has no **Rotate** item; rotate its replacement instead.

## Revoke a key [#revoke-a-key]

Open the row menu, choose **Revoke** and confirm **Revoke this key?** with **Revoke**. The key stops working right away. This cannot be undone.

## When you reach the key limit [#when-you-reach-the-key-limit]

The limit counts every key in the table, including replaced keys that still work. When you reach it, **Create key** is disabled and the page says "You have 100 keys, the most allowed. Revoke one to create another." (with your server's limit in place of 100). Revoke a key you no longer use, then create the new one. The person who runs the server sets the limit ([configuration](/self-hosting/configuration#api_keys_per_account_max)).


# Delete videos (/studio/delete)

Delete a video from its page, or delete several at once from the **Videos** page. Deleting is final: there is no trash and no undo.

<Callout type="warn" title="Deletion cannot be undone">
  A deleted video leaves your library at once, the server removes its files from Sia, and every link
  and embed of it stops working. To keep a copy, keep the original file.
</Callout>

## Delete one video [#delete-one-video]

<Steps>
  <Step>Open the video from **Videos**.</Step>
  <Step>
    Click **Delete video** in the **Delete video** card beside or below the player, or open **More**
    next to **Copy embed code** and choose **Delete video**.
  </Step>
  <Step>
    Read the confirmation, for example "It is removed from your library now and its 9 files are
    removed from Sia in the background. Every embed stops working. This cannot be undone." Click
    **Delete video**.
  </Step>
</Steps>

The Studio says "Video deleted" and returns to **Videos**.

You can also delete from the list: open the video's actions menu (the button at the end of its row) and choose **Delete…**. The dialog asks "Delete this video?" Click **Delete**.

A video that failed processing or whose upload was interrupted has a **Delete video** button in the player area too.

## Delete several videos [#delete-several-videos]

<Steps>
  <Step>
    On the **Videos** page, tick the box at the start of each video you want to delete. To select a
    whole page, use the box in the table heading or **Select all** in the grid. To go beyond one
    page, click **Select all N results** in the bar that appears. Above 500 results it reads
    **Select the first 500 results**: one delete takes at most 500 videos.
  </Step>
  <Step>Click **Delete** in the bar at the bottom of the page.</Step>
  <Step>The dialog asks, for example, "Delete 3 videos?" Click **Delete**.</Step>
</Steps>

The Studio confirms with "3 videos deleted". If some videos could not be deleted, it names each one with the reason, for example "Could not delete “Intro”." followed by why. With more than three failures it gives the count and the first reason instead. Videos that could not be deleted stay selected, so you can try again.

## What happens when you delete [#what-happens-when-you-delete]

- The video leaves your library and every Studio list at once.
- The server removes its files from Sia in the background. A video whose file never arrived has nothing on Sia, so only the library entry goes.
- The video's watch page, stream URL and embed code stop working for public and private videos alike: a player that opens them finds no video.
- Anyone who opens the video's Studio page sees **Video not found**.

For the steps the server takes, see [deletion and reconciliation](/developers/concepts/deletion-and-reconciliation).

If someone deletes a video you uploaded in this tab before its processing finishes, its row on the upload page shows **Deleted** and "This video was deleted before processing finished."

## Delete an unfinished upload [#delete-an-unfinished-upload]

Uploads that stopped partway, for example when a tab closed, are listed under **Unfinished from earlier** on the upload page. Click **Delete** on a row and confirm to remove the part already sent and its video entry ([Upload a video](/studio/upload#continue-an-upload-after-closing-the-tab)).


# Get started (/studio)

Sluby Studio is the web app where your team uploads, watches and shares videos stored on Sia. This page takes you from a fresh account to a first video you can send to someone.

## 1. Open the Studio [#1-open-the-studio]

Open your server's address followed by `/studio`, for example `https://sluby.example.com/studio`. What you see depends on how you arrive:

- **Set up Sluby Studio**: the server has no admin yet, and you are the first person. Continue with [Create the first admin](#create-the-first-admin).
- **Join Sluby Studio**: you opened an invite link. Continue with [Join from an invite](#join-from-an-invite).
- **Sign in to Sluby Studio**: you already have an account. Sign in with your email and password ([Sign in and out](/studio/sign-in)).

### Create the first admin [#create-the-first-admin]

The first account on a new server is an admin, and it needs the server's setup code. The person who runs the server finds the code in the server's log ([how to find the setup code](/self-hosting/sign-in#create-the-first-admin)). Ask them for it if that is not you.

<Steps>
  <Step>
    Enter the **Setup code**. It looks like `XXXXX-XXXXX`. Upper or lower case and the dash do not
    matter.
  </Step>
  <Step>Fill in **Your name**, **Email** and **Password** (at least 10 characters).</Step>
  <Step>Click **Create admin account**. You are signed in and the Studio opens.</Step>
</Steps>

If the screen says "That setup code is wrong. Copy it from the server log.", check the code with the person who runs the server. If it says "This server already has an admin. Sign in instead.", someone set up the server first: click **Sign in instead**.

As the admin, you invite everyone else from the **Members** page ([Invite and manage members](/studio/members)).

### Join from an invite [#join-from-an-invite]

<Steps>
  <Step>Open the invite link an admin sent you.</Step>
  <Step>
    Fill in **Your name**, **Email** and **Password** (at least 10 characters), then click **Join**.
    If the server offers it, you can click **Continue with GitHub** instead.
  </Step>
</Steps>

You are signed in and the Studio opens on the **Overview** page.

## 2. Upload a video [#2-upload-a-video]

<Steps>
  <Step>Click **Upload video** at the top of the sidebar, or press `U`.</Step>
  <Step>Drop a video file on the page, or click **Choose files** and pick one.</Step>
  <Step>
    Check the **Title**, leave **Who can watch** on **Public**, and click **Start upload**.
  </Step>
</Steps>

A progress bar shows how much is sent. After the upload, the server processes the video: it converts it for streaming and stores it on Sia. You can leave the page meanwhile; the upload keeps going while the tab stays open. More in [Upload a video](/studio/upload) and [Follow processing and retry](/studio/processing).

When the video is ready, its row on the upload page shows a check mark. On any other Studio page, a notice reads "“Title” is ready".

## 3. Watch it [#3-watch-it]

Open **Videos** in the sidebar and click the video's title. Press play in the player at the top of the video page. More in [Watch a video](/studio/watch).

## 4. Copy its link [#4-copy-its-link]

<Steps>
  <Step>On the video page, click the **Share** tab under the player.</Step>
  <Step>Click the **Link** tab in the code box, then **Copy**.</Step>
</Steps>

Anyone with this link can watch a public video on its own page. To put the player on your site instead, click **Copy embed code** next to the video's title. More in [Share or embed a video](/studio/share).

## Next steps [#next-steps]

<Cards>
  <Card title="Find and edit videos" href="/studio/library">
    Search, filter, preview and rename your videos.
  </Card>
  <Card title="Choose who can watch" href="/studio/privacy">
    Make a video private and control who can play it.
  </Card>
  <Card title="Invite and manage members" href="/studio/members">
    Admins: bring your team in.
  </Card>
  <Card title="Build with Sluby" href="/developers">
    Upload and play videos from your own app.
  </Card>
</Cards>


# Find and edit videos (/studio/library)

The **Videos** page lists your team's videos. Find a video by searching, filtering or sorting, preview it without leaving the list, and change its title or description.

Open it from **Videos** in the sidebar. The line under the heading counts your videos, for example "12 videos, 1 processing. Drop files anywhere on this page to upload." Dropping files there opens them on the [upload page](/studio/upload).

## Search [#search]

Type in **Search by title or ID** above the list. The list updates as you type. It finds videos whose title or description contains the text you typed (upper or lower case does not matter), or whose video ID matches a full ID you pasted.

Press `/` anywhere on the page to jump to the search field. Press Escape in the field to clear it.

## Filter [#filter]

- **Status**: **All**, **Ready**, **Processing**, **Uploading**, **Waiting for file** or **Failed**. For what each status means, see [video statuses](/studio/processing#video-statuses).
- **Access**: **All**, **Public** or **Private**.

**Clear filters** appears while a search or filter is set and removes them all.

If some videos never received their file within 10 minutes, a line under the list says, for example, "2 uploads never started." Click **Show them** to filter the list to **Waiting for file**.

## Sort [#sort]

In the table, click a column heading to sort by it: **Video** (title), **Length**, **Size** or **Uploaded**. Click it again to reverse the order. The list starts with the newest videos first.

In the grid, use the **Sort** menu: **Newest first**, **Oldest first**, **Title A to Z**, **Title Z to A**, **Longest first**, **Shortest first**, **Largest first** or **Smallest first**.

## Table or grid [#table-or-grid]

Switch between **Table** and **Grid** at the right of the toolbar. The Studio remembers your choice in this browser.

- **Table** shows each video's **Status**, **Access**, **Length**, **Plays**, **Size** and **Uploaded** date.
- **Grid** shows each video as a tile with its status.

The list shows 24 videos per page. Use **Previous** and **Next** under the list to move between pages.

On a phone, the page shows one card per video and a row of status buttons with counts in place of the toolbar.

The page address keeps your search, filters, sort, view and page, so you can bookmark a filtered list or share it with a teammate.

## Open or preview a video [#open-or-preview-a-video]

- Click a video's title to open its video page.
- To watch a ready video without leaving the list, open the video's actions menu (the button at the end of its row) and choose **Preview**, or focus the title and press Space. A panel opens with the player and the embed code. Press the left and right arrow keys, or **Previous video** and **Next video**, to step through the ready videos on the page. **Open video** goes to the video page.

The actions menu also has **Copy embed code**, **Open video**, **Copy stream URL** (public videos), **Make private** or **Make public**, **Copy video ID** and **Delete…**. Some items show only for ready videos.

## Work with several videos [#work-with-several-videos]

Tick the box at the start of each row (or each tile) to select videos. Shift-click a second box to select every video in between. The box in the table heading, or **Select all** in the grid, selects every video on the page.

A bar appears at the bottom with what you can do with the selection: **Make public** (when some selected videos are private), **Make private** (when some are public), **Copy embed code** (ready videos only) and **Delete**. When the whole page is selected and there are more results, the bar offers **Select all N results**. Above 500 results it offers **Select the first 500 results** instead. Press Escape or click the close button on the bar (**Clear selection**) to clear the selection.

For deleting, see [Delete videos](/studio/delete). For changing who can watch, see [Choose who can watch](/studio/privacy).

## Edit the title and description [#edit-the-title-and-description]

<Steps>
  <Step>Open the video from **Videos**.</Step>
  <Step>
    To change the title, click the pencil button next to it (**Edit title**). Type the new title and
    press Enter.
  </Step>
  <Step>
    To change the description, click **Edit** in the **Description** card. Type the new text and
    press `Ctrl Enter` (`⌘ Enter` on a Mac).
  </Step>
</Steps>

Clicking outside the field also saves. Press Escape to cancel. The Studio confirms with "Changes saved".

- **Title**: required, up to 200 characters.
- **Description**: optional, up to 5,000 characters. A counter appears near the limit.

If someone else changed the video since you opened it, the field says "This video was changed somewhere else. Reload it to see the latest, then edit again." Click **Reload**, then save again to keep what you typed, or press Escape to keep their version.

## Details on the video page [#details-on-the-video-page]

The **Details** card on the video page shows:

| Field           | What it shows                                                                            |
| --------------- | ---------------------------------------------------------------------------------------- |
| **Access**      | Public or private, with a control to change it ([Choose who can watch](/studio/privacy)) |
| **Length**      | The video's duration                                                                     |
| **Quality**     | The qualities the video plays in, for example 1080p                                      |
| **Size**        | The video's total storage size                                                           |
| **Plays**       | How many times a player loaded the video. Studio previews do not count.                  |
| **Last played** | When a player last loaded it, or **Never**                                               |
| **Uploaded**    | The upload date                                                                          |
| **Video ID**    | The video's ID, with **Copy**                                                            |


# Invite and manage members (/studio/members)

Admins use the **Members** page to decide who can sign in to the Studio and what each person can do. Open it from **Members** at the bottom of the sidebar.

Only admins see **Members** in the sidebar. A member who opens the page sees **For admins only** and a **Back to overview** button.

## Roles [#roles]

Every person has one of two roles. The Studio describes them like this:

- **Member**: Uploads and manages videos, API keys and webhooks.
- **Admin**: Also manages members and sees server health and metrics.

For the full list of what each role allows, see [Roles and what each can do](/developers/concepts/accounts-and-roles#roles).

## Invite someone [#invite-someone]

An invite is a link that lets new people join your Studio. Each person chooses their own name, email and password when they join. One link can be for one person or for a group.

<Steps>
  <Step>On the **Members** page, click **Invite people**.</Step>
  <Step>Under **Role**, pick **Member** or **Admin**. **Member** is the default.</Step>
  <Step>
    Under **Who can join**, pick **One person**, **A number of people** or **Anyone with the link**.
    For **A number of people**, enter a whole number from 2 to 1000 under **Number of people**.
  </Step>
  <Step>
    Under **Link works for**, pick **1 day**, **7 days** or **30 days**. **7 days** is the default.
  </Step>
  <Step>Click **Create link**. The dialog changes to **Invite link created**.</Step>
  <Step>
    Click the copy button next to the link, send the link to the people you want to invite, then
    click **Done**.
  </Step>
</Steps>

A link for more than one person joins everyone as a member. When you pick **Admin**, **Who can join** switches to **One person** and cannot be changed, because anyone can pass a link on.

Under the link, the dialog says who can join with it and the exact date and time it stops working. The Studio shows the link only once: if you lose it, revoke the invite and create a new one.

What an invited person sees is on [Join from an invite link](/studio/sign-in#join-from-an-invite-link).

## Pending invites [#pending-invites]

The **Pending invites** section lists every invite that still lets someone join. Its columns are **Role**, **Joined**, **Created by**, **Created** and **Expires** (the time left). **Joined** counts the people who joined with the link: "3 of 10" for a link for 10 people, "4 (no limit)" for a link for anyone. An invite leaves the list when its last person joins, when it expires, or when you revoke it.

To withdraw an invite, open the row menu, choose **Revoke**, then click **Revoke** in the **Revoke this invite?** dialog. The link stops working right away for anyone who has not joined yet. People who already joined stay members. You cannot undo this.

## The members table [#the-members-table]

The table lists everyone, including removed members:

- **Name**: your own row carries a **You** badge.
- **Signs in with**: each way the person signs in, for example **Password** with their email or **GitHub** with their `@login`.
- **Role**: a menu to switch between **Member** and **Admin**.
- **Status**: **Active**, or **Removed** for someone who can no longer sign in. Removed rows show in lighter text.
- **Last sign-in**: when they last signed in, or **Never**.

## Change someone's role [#change-someones-role]

Pick a new role in the **Role** column, or open the row menu and choose **Make admin** or **Make member**. The Studio confirms with a message such as "Alex is now an admin." The new role takes effect right away, for the person's Studio sessions and for the API keys they created.

If you make yourself a member, the Studio asks **Stop being an admin?** first. When you click **Make me a member**, the page reloads without **Members**, **Health** and **Metrics**. Another admin can make you an admin again.

You cannot change the role of a removed member until you restore them.

## Remove a member [#remove-a-member]

<Steps>
  <Step>Open the row menu of the person and choose **Remove**.</Step>
  <Step>In the **Remove this member?** dialog, click **Remove**.</Step>
</Steps>

The person can no longer sign in, every browser they are signed in on is signed out right away, and the API keys they created stop working. They stay in the table with the status **Removed**.

**Remove** is not offered on your own row. Another admin has to remove you.

## Restore a member [#restore-a-member]

Open the row menu of a removed member and choose **Restore**. They can sign in again with the role they had before, and their API keys work again.

## Give someone a reset link [#give-someone-a-reset-link]

When a member forgets their password, an admin creates a reset link for them. With it they set a new password.

<Steps>
  <Step>Open the row menu of the person and choose **Create reset link**.</Step>
  <Step>Click **Create link** in the **Create a reset link?** dialog.</Step>
  <Step>
    In **Reset link created**, click the copy button next to the link, send the link only to that
    person, then click **Done**.
  </Step>
</Steps>

The Studio shows a reset link only once. It works once, for 7 days. When the person sets a new password with it, their other browsers are signed out. What they see is on [Set a new password from a reset link](/studio/sign-in#set-a-new-password-from-a-reset-link).

A reset link also works for someone who signs in with GitHub only: with it they choose an email and password, so they can sign in with a password as well.

## The last admin [#the-last-admin]

The Studio always keeps at least one admin who can sign in. If you try to make the last such admin a member, or to remove them, the Studio refuses and shows "This is the last admin who can sign in. Make someone else an admin first." Make another person an admin, then try again.


# Overview, health and metrics (/studio/overview)

The **Overview** page shows your library totals, what needs your attention and your newest videos. Admins also get **Health**, which says whether the server and its Sia storage work, and **Metrics**, which shows server activity since it last started.

## Overview [#overview]

Open **Overview** at the top of the sidebar (`/studio`). Every member of the team sees the same totals and videos.

### Get started [#get-started]

The **Get started** card lists four steps, shows how many are done (for example "2 of 4 done"), and ticks each step on its own as soon as it is done. The first step that is not done is marked as the next one. Each open step has a link that takes you to it.

| Step                     | Done when                                                                                       | Link                                                                          |
| ------------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Connect Sia**          | The server reaches the Sia indexer and its Sia account is ready.                                | Only when this fails: **Open health** for admins, "Ask an admin." for members |
| **Upload a video**       | At least one video has started uploading its file.                                              | **Upload video**                                                              |
| **Play it on your site** | A player outside the Studio loaded one of your videos. Previews inside the Studio do not count. | **Get embed code**, which opens the share options of a ready video            |
| **Create an API key**    | You have an active API key. This step is optional.                                              | **Create key**                                                                |

Click **Hide** to remove the card. Once all four steps are done, the card closes by itself. Either way it stays hidden for your account in this browser.

### Totals [#totals]

| Card                    | What it counts                                                                                                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Videos**              | All videos in the library. The line under it splits them by status, for example "4 ready · 1 failed · 1 processing · 2 waiting for file".                                   |
| **Stored on Sia**       | The size of all your videos on Sia, before Sia adds redundancy. When the Sia account has a storage limit, admins see the figure against it, for example "of 50 GB".         |
| **Playable time**       | The total length of all ready videos.                                                                                                                                       |
| **Plays, last 30 days** | Player loads of your videos over the last 30 days. Repeat loads of the same video by the same viewer within 30 minutes count once, and previews in the Studio do not count. |

### Needs attention [#needs-attention]

**Needs attention** lists problems, most urgent first, with a count next to the heading. It shows up to five rows; click **and N more** to see the rest. With nothing to fix, it says "Nothing needs your attention."

| Label           | Meaning                                                                                              | What to do                                                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Down**        | The Sia indexer, the database or the job queue does not work. The row names which one.               | Admins click **Open health**. Members ask an admin.                                                                            |
| **Missing**     | The last storage check found files that Sia no longer holds.                                         | Admins click **Open health** and read the [storage check](#storage-check).                                                     |
| **Failed**      | A video failed to process.                                                                           | Click **Retry**, or **Upload again** when retrying cannot help. See [Follow processing and retry](/studio/processing).         |
| **Failing**     | The last delivery to a webhook failed.                                                               | Click **Open webhook**. See [Receive webhooks](/developers/guides/webhooks).                                                   |
| **Paused**      | A webhook is paused, so it gets no events.                                                           | Click **Open webhook**.                                                                                                        |
| **Interrupted** | An upload started more than 10 minutes ago and has not finished, and this browser is not sending it. | Click **Open video**. See [Continue an upload after closing the tab](/studio/upload#continue-an-upload-after-closing-the-tab). |

### Status [#status]

The **Status** card gives one verdict and a row for each service the server needs: **Database**, **Queue** and **Sia storage**. Each row shows "OK" with the response time, or **Not responding**. The card checks again every 20 seconds. Admins get an **Open health** link.

| Verdict         | Meaning                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------- |
| **All working** | Every service works.                                                                              |
| **Degraded**    | The database and queue work, but the Sia indexer does not answer or the Sia account is not ready. |
| **Down**        | The database or the queue does not answer.                                                        |

### Recent videos [#recent-videos]

**Recent videos** lists your six newest videos with their **Status**, **Access** (**Public** or **Private**), **Plays** and when they were **Uploaded**. Videos that are processing show their progress. Click a title to open the video, or **All videos** to open the [Videos](/studio/library) page. Interrupted uploads are left out of this list and appear under **Needs attention**.

## Health [#health]

**Health** and **Metrics** are in the **Deployment** group of the sidebar, for admins only. A member who opens either page sees "For admins only". For admins, a dot next to **Health** in the sidebar shows the server's verdict from any page.

Under the page title, a line says when the server was last checked, that the page refreshes every 20 seconds, the backend version and how long the server has been running. The chip at the top right gives the verdict:

| Chip                            | Meaning                                                                                               |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **All services working**        | The database, the job queue and the Sia indexer all answer, and the Sia account is ready.             |
| **Sia indexer needs attention** | The database and job queue work, but the Sia indexer does not answer or the Sia account is not ready. |
| **Some services are down**      | The database or the job queue does not answer.                                                        |

### Services [#services]

| Card             | What it shows                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| **Database**     | PostgreSQL and its response time.                                                                            |
| **Queue**        | Redis, its response time and how many jobs are waiting.                                                      |
| **Sia indexer**  | The indexer's host, the Sia network and the response time. Hover to see the full indexer URL.                |
| **Stream cache** | How much of the server's in-memory cache for streamed files is in use, and the share of lookups it answered. |

A service that fails shows **Not working**. Click **Details** under it to read the error.

### Sia account [#sia-account]

The **Sia account** card shows the account this server stores videos with:

- **Stored**: how much data is stored, against the account's limit, with a bar. The line below gives the space it takes on Sia hosts with redundancy.
- **Hosts**: how many Sia hosts are good for upload out of all hosts, and how many countries they are in.
- **App**: the app name the server uses on the indexer.
- **Account key**: the start and end of the account key. Hover to see all of it.

To learn what these numbers mean on Sia, see [Storage on Sia](/developers/concepts/storage-on-sia).

### Storage check [#storage-check]

The **Storage check** card compares the files your videos use with the files Sia holds. It shows when the last check ran, how long it took and how many files it compared. Its chip reads **All present**, **Needs attention** or **Check failed**. Two tiles count what the check found:

- **missing files**: files a video uses that Sia no longer holds. Click **Show missing files** to see them grouped by video, with a link to each video. The copy button next to the list (**Copy missing file IDs**) copies every missing file ID.
- **unused files still stored**: files on Sia that no video on this server uses, for example from another app on the same Sia account. The Sia account still pays to store them. The check never deletes them.

Click **Check now** to start a check. The Studio confirms with "Storage check started", or "A check is already running" if one has not finished yet. If a check stops before it finishes, the card says "The check stopped before it finished. Start it again." and **Details** holds the error. For how checks run, see [Deletion and reconciliation](/developers/concepts/deletion-and-reconciliation).

## Metrics [#metrics]

**Metrics** shows what the server did since it last started. It reads new figures every 10 seconds, and the line at the bottom says when they last arrived.

| Card                        | What it shows                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Uploads**                 | Uploads received in full, with how many failed and how much data arrived.                                                       |
| **Processing time**         | The average time a processing job took to make a video ready, how many jobs that covers and how many jobs wait in the queue.    |
| **Sia upload time**         | The average time an upload of files to Sia took, and how many uploads that covers.                                              |
| **Playback URLs**           | Public, signed and direct-from-Sia playback URLs the server handed out, with how many were direct from Sia and how many signed. |
| **Streamed by this server** | Data the server streamed to viewers, and the number of requests.                                                                |
| **Cache hit ratio**         | The share of stream cache lookups answered from memory.                                                                         |
| **Uptime**                  | How long the server has been running.                                                                                           |
| **Memory**                  | The memory the server process uses, with how much of its heap is in use.                                                        |

Two charts follow:

- **Streaming throughput**: bytes per second the server streamed, measured every 10 seconds while the page is open. It covers at most the last 10 minutes and marks the peak and the current rate.
- **Streaming requests**: requests the server answered since it started, split into **Video segments**, **Playlists** and **Other files**.

Both charts count only video data that passes through this server. A viewer who plays a video straight from Sia does not add to them ([how playback works](/developers/concepts/playback)).


# Choose who can watch (/studio/privacy)

Decide whether anyone with a link can play a video, or only viewers your own site lets in with a signed link. You set this when you [upload a video](/studio/upload) and can change it at any time.

## Public and private [#public-and-private]

| Access      | Who can play the video                                                                                                                                    |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Public**  | Anyone with its watch page link, embed code or stream URL.                                                                                                |
| **Private** | Only viewers with a signed URL: a link that carries an expiry and a signature. Opening the watch page without one shows "This video needs a signed link". |

To give viewers a private video, see [Share a private video](/studio/share#share-a-private-video).

## Change one video [#change-one-video]

<Steps>
  <Step>Open the video from **Videos**.</Step>
  <Step>In the **Details** card, find **Access** and click **Public** or **Private**.</Step>
  <Step>
    In the **Make this video private?** or **Make this video public?** box, click **Make private**
    or **Make public**.
  </Step>
</Steps>

When it saves, you see "The video is private now" or "The video is public now". If saving fails, the reason shows in the same box and nothing changes.

## Change several videos [#change-several-videos]

<Steps>
  <Step>
    On the **Videos** page, select the videos ([work with several
    videos](/studio/library#work-with-several-videos)).
  </Step>
  <Step>
    In the bar that appears, click **Make private** or **Make public**. The bar shows **Make
    private** when at least one selected video is public, and **Make public** when at least one is
    private.
  </Step>
  <Step>Confirm in the dialog.</Step>
</Steps>

The Studio reports how many changed, for example "3 videos are now private". To change a single video from the list, open its actions menu and choose **Make private** or **Make public**.

## What changes for viewers [#what-changes-for-viewers]

When you make a video private:

- Players without a signed URL stop working within a minute. This covers the watch page link, the embed code and the stream URL, including players that are already playing.
- Signed URLs created before the change stop working. Create new ones after the change.
- A player that already streams the video straight from Sia keeps playing until its Sia links expire ([why](/developers/concepts/playback#revocation)).

When you make a video public, anyone with its watch page link, embed code or stream URL can play it. Signed URLs created before the change stop working on playback IDs set to **Signed URL required**, so create new ones for those.

## Playback IDs [#playback-ids]

A playback ID is a second ID for the same video. Share or embed with it, and delete it later to stop those links without touching the video or its other IDs. The video ID itself keeps working either way.

Playback IDs are on the **Playback IDs** tab of a ready video. The table shows each ID's **Name**, **Playback ID**, **Access**, **Stream URL** and **Created** date. **Access** is **Open** or **Signed URL**.

### Create a playback ID [#create-a-playback-id]

<Steps>
  <Step>Click **New playback ID**.</Step>
  <Step>
    Optionally enter a **Name** (up to 100 characters), for example the site where you use it.
  </Step>
  <Step>
    Under **Who can play**, pick **Anyone with the URL** or **Signed URL required**, then click
    **Create**.
  </Step>
</Steps>

**Signed URL required** protects only that playback ID's own links. The Studio says so: "Players need a signed URL from your server. The video's files on Sia stay public unless the video itself is private." To keep the whole video behind signed URLs, make the video private.

On a private video, the form starts on **Signed URL required**, and every playback ID needs a signed URL, whatever you pick.

### Use or delete a playback ID [#use-or-delete-a-playback-id]

Each row has copy buttons for the ID and its stream URL. Its actions menu has **Copy embed code**, **Copy stream URL** and **Delete**. When the ID needs a signed URL, the row also has **Copy signed URL**, which copies a stream URL that works for 1 hour.

To use the ID in any code sample, pick it in **Play by** on the **Share** tab.

## Stop links you already shared [#stop-links-you-already-shared]

- **Delete the playback ID** the links use. Its stream URL, watch page and embed code stop working for anyone who opens them after you delete it. The video and its other playback IDs keep working. Deleting cannot be undone.
- **Revoke signed URLs** to stop the signed URLs you already gave out without changing who can watch (see [Revoke signed URLs](#revoke-signed-urls)).
- **Make the video private** to stop every link without a signature, and every signed URL created before the change (see [What changes for viewers](#what-changes-for-viewers)).
- **Delete the video** to stop every link for good. See [Delete videos](/studio/delete).

### Revoke signed URLs [#revoke-signed-urls]

The **Signed URLs** card on a ready video's page cancels every signed URL created for it so far. It shows on a private video, and on a public video that has a playback ID set to **Signed URL required**.

<Steps>
  <Step>Open the video from **Videos**.</Step>
  <Step>In the **Signed URLs** card, click **Revoke signed URLs**.</Step>
  <Step>In the **Revoke signed URLs?** box, click **Revoke**.</Step>
</Steps>

When it is done, you see "Signed URLs revoked". If it fails, the reason shows in the same box and nothing changes. Revoking cannot be undone, but signed URLs created after it work as usual.

On a private video:

- Every signed URL created before stops working within a minute, including those of its playback IDs. A player that plays one through your server stops once it has played what it already loaded.
- A player that streams the video straight from Sia keeps playing until its Sia links expire, at most an hour ([why](/developers/concepts/playback#revocation)).
- The preview on the video's page starts again with a new signed URL.

On a public video, the signed URLs of its **Signed URL required** playback IDs stop working at once, so a player needs a new one to start. Players that are already playing are not cut off, because the video's files are public. The watch page link, the embed code and the stream URL of the video and of its open playback IDs keep working.

Your server can do the same with the revoke endpoint ([Revoke signed URLs](/developers/guides/private-videos#revoke-signed-urls)).


# Follow processing and retry (/studio/processing)

After a file is uploaded, the server converts it for streaming and stores it on Sia. Follow that work from the Studio, read the log of each run, and restart a video whose processing failed.

## The four steps [#the-four-steps]

Every video goes through the same four steps. The Studio draws them as a progress bar with these names:

| Step             | What happens                                               |
| ---------------- | ---------------------------------------------------------- |
| **Upload**       | The file is sent to this server and resumes if interrupted |
| **Transcode**    | Converted into several qualities for streaming             |
| **Store on Sia** | Video, playlists and thumbnails are stored on Sia          |
| **Publish**      | The video becomes playable                                 |

For what happens inside each step, see [the upload pipeline](/developers/concepts/upload-pipeline).

While a video processes, the Studio names its current stage and a percentage, for example "Storing on Sia, 72%". The stage names are:

| Stage            | Meaning                                                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Waiting to start | The file has arrived and processing has not started yet.                                                                                              |
| Transcoding      | The server converts the video into several qualities.                                                                                                 |
| Storing on Sia   | The server stores the converted files on Sia. A second line "Waiting for the Sia uploader" means transcoding is done and storing has not started yet. |
| Publishing       | The server makes the video playable.                                                                                                                  |
| Done             | Processing finished. The video is ready to play.                                                                                                      |
| Failed           | Processing stopped with an error. See [When processing fails](#when-processing-fails).                                                                |

When a step fails, the server tries it again by itself, unless the file is not a readable video. The stage then reads, for example, "Transcoding, trying again".

## Video statuses [#video-statuses]

Each video has one status. It shows as a badge next to the title on the video page and on each video on the **Videos** page.

| Status               | Meaning                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Waiting for file** | The video was created and no file has arrived yet.                                                                                                      |
| **Uploading**        | The file is arriving.                                                                                                                                   |
| **Processing**       | The file has arrived and is being processed. In the video list the badge names the stage instead, for example **Storing on Sia**.                       |
| **Ready**            | The video plays, and its links and embed code work.                                                                                                     |
| **Failed**           | Processing stopped with an error.                                                                                                                       |
| **Interrupted**      | The video was created more than 10 minutes ago and its file has not fully arrived. See [When an upload is interrupted](#when-an-upload-is-interrupted). |

## Where to follow progress [#where-to-follow-progress]

- **Upload page**: each row you started in this browser shows the stage and a progress bar. Click **Details** on the row to see the processing log.
- **Top bar**: while uploads run, a progress ring shows in the top bar. Click it for the **Uploads** list.
- **Videos page**: a processing video shows its stage and percentage in the list.
- **Video page**: until the video is ready, the player area shows the four steps. It reads **Uploading** while the file arrives, then **Processing** with the stage and the percentage. The page updates by itself.

When a video you uploaded in this tab finishes, a notice "“Title” is ready" appears on any other Studio page. On the upload page, the row itself turns into a check mark and a link.

## Read the processing log [#read-the-processing-log]

<Steps>
  <Step>Open the video from **Videos**.</Step>
  <Step>Click the **Activity** tab under the player.</Step>
</Steps>

The tab shows when the run started and finished, how many times it was tried again ("Tried again 2 times"), and the processing log: one line per event, with the time, the stage and a message. If the run failed, the line it failed on is red.

Before the whole file has arrived, the tab says "Nothing has run yet. Processing starts once the whole file has arrived."

## When processing fails [#when-processing-fails]

A failed video shows **Processing failed** in the player area, with one sentence about what went wrong:

- The file is not a readable video.
- The original file is no longer on the server.
- Transcoding the video failed.
- Storing the video on Sia failed. Retrying usually works.
- Publishing the video failed. Retrying usually works.
- Processing stopped with an error.
- Processing failed before it recorded a reason.

Click **Details** under the message to see the server's own error text.

The card offers one of two actions next to **Delete video**:

- **Retry processing** when a new run can help.
- **Upload a different file** when it cannot, for example when the file is not a readable video. This opens the upload page.

## Retry processing [#retry-processing]

<Steps>
  <Step>
    Find the failed video. On the **Videos** page, failed videos show the reason in red and a
    **Retry** button. On the video page, the button reads **Retry processing**.
  </Step>
  <Step>Click **Retry** or **Retry processing**.</Step>
</Steps>

The server starts a new run from **Transcoding**, or from **Storing on Sia** when transcoding already finished in an earlier run. The Studio confirms with a notice such as "Processing restarted from Storing on Sia". The video's status returns to **Processing**, and you follow it as before.

If the retry is refused, the notice starts with "Could not retry" and gives the reason.

On the upload page, a row whose processing failed also has **Retry processing** or **Upload a different file**.

## When an upload is interrupted [#when-an-upload-is-interrupted]

If a video was created more than 10 minutes ago, its file has not fully arrived, and this browser is not sending it, the Studio marks it **Interrupted**. The video page shows **Upload interrupted**: "The browser sending this file stopped. Add the same file again in that browser to continue, or delete this video. Unfinished uploads are removed after 24 hours."

To continue it, see [Continue an upload after closing the tab](/studio/upload#continue-an-upload-after-closing-the-tab). To remove it, click **Delete video**.

## When the Studio cannot read the status [#when-the-studio-cannot-read-the-status]

If the Studio cannot reach the server to read the processing status, the player area says "Could not read the processing status." and offers **Check again**. Processing on the server continues meanwhile.

On the upload page, if processing has not started a minute after the file was sent, the row says "Processing has not started after a minute. Check again, or open the video." with **Check again** and **Open video** buttons.


# Share or embed a video (/studio/share)

Copy a link that opens the video on its own page, or embed code that puts the player on your site. Sharing works once the video's status is **Ready**. Before that, the **Share** tab says "Available once the video is ready."

## Copy the watch page link [#copy-the-watch-page-link]

The watch page shows only the video, in a player that fills the window. Anyone with the link can watch a public video there.

<Steps>
  <Step>Open the video from **Videos**.</Step>
  <Step>Click the **Share** tab under the player.</Step>
  <Step>Click the **Link** tab in the code box, then **Copy**.</Step>
</Steps>

To check the page first, click **Open watch page**. It opens in a new tab.

The watch page of a public video carries its title, and its thumbnail when it has one, for apps that show link previews.

## Copy the embed code [#copy-the-embed-code]

On the video page, click **Copy embed code** next to the title. For a public video this copies an iframe that you paste into any web page. The Studio confirms with "Embed code copied".

You can also copy it from the **Videos** page: open a video's actions menu and choose **Copy embed code**, or select several videos and click **Copy embed code** in the bar that appears. That copies the code of every selected video that is ready, one after another.

The **Share** tab offers the same video in other forms. Click a tab, then **Copy**:

| Tab            | What you get                                                                                                                                       |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Iframe**     | An iframe of the watch page. Nothing to install.                                                                                                   |
| **Link**       | The watch page address.                                                                                                                            |
| **React**      | A component for a React app, using `@sluby/player` and `@sluby/sdk`. The install command `npm install @sluby/player @sluby/sdk` is under the code. |
| **HTML**       | A `<video>` element that plays the stream with hls.js.                                                                                             |
| **Stream URL** | The address of the video's HLS stream, for any player that plays HLS.                                                                              |

For code beyond these samples, see [Play videos in React](/developers/guides/play-react) and [Play videos without React](/developers/guides/play-hls).

### Change how the embed plays [#change-how-the-embed-plays]

Add these to the end of the watch page address in the iframe or link:

| Add           | Effect                                   |
| ------------- | ---------------------------------------- |
| `?autoplay=1` | Starts playing on load, muted.           |
| `?muted=1`    | Starts muted.                            |
| `?loop=1`     | Plays again from the start when it ends. |

Join several with `&`, for example `https://sluby.example.com/watch/<id>?autoplay=1&loop=1`.

## Share with a playback ID [#share-with-a-playback-id]

By default the code uses the video ID. To share under a separate ID that you can delete later without touching the video, create a playback ID on the **Playback IDs** tab (see [Playback IDs](/studio/privacy#playback-ids)). Then, on the **Share** tab, pick it in **Play by**. The code samples and **Open watch page** switch to that ID.

## Share a private video [#share-a-private-video]

A private video plays only through a signed URL: a link that carries an expiry and a signature. On a private video:

- The **Share** tab says "Private videos play only through signed URLs. Your server creates them with an API key. Never put a key in browser code."
- **Copy embed code** copies the **Server** sample, the server code that creates signed URLs. The **Iframe**, **React** and **HTML** tabs show page code that asks that server for a signed URL.

Hand the **Server** sample to the person who runs your site, or follow [Serve private videos](/developers/guides/private-videos).

### Get a signed link for a quick test [#get-a-signed-link-for-a-quick-test]

<Steps>
  <Step>
    On the video page, click the **Playback IDs** tab and create a playback ID if the video has none
    ([create a playback ID](/studio/privacy#create-a-playback-id)).
  </Step>
  <Step>In the playback ID's row, click **Copy signed URL**.</Step>
</Steps>

The Studio copies a stream URL that works for 1 hour and says when it stops, for example "Signed URL copied. It works until 3:45 PM". It is an HLS stream address, so open it in a player that plays HLS. How long signed URLs last and how they are checked is on [Playback and delivery](/developers/concepts/playback#signed-urls).

## When a shared link does not play [#when-a-shared-link-does-not-play]

The watch page tells the viewer why:

| The viewer sees                         | Why                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **This video needs a signed link**      | The video is private, or the playback ID requires a signed URL, and the link has no valid signature. |
| **This link has expired**               | The signed link was valid but its time ran out. Send a new one.                                      |
| **This video is not available**         | The video or playback ID was deleted, or the video is still processing.                              |
| **This video is unavailable right now** | The server could not look up the video. Try again in a moment.                                       |

To stop links you already shared from working, see [Choose who can watch](/studio/privacy#stop-links-you-already-shared).


# Sign in and out (/studio/sign-in)

Sign in to the Studio, join a team from an invite link, or set a new password from a reset link. This page also explains the messages the sign-in screen shows and what to do about each.

## Sign in with email and password [#sign-in-with-email-and-password]

<Steps>
  <Step>
    Open the Studio at your server's address, for example `https://sluby.example.com/studio`. The
    screen reads **Sign in to Sluby Studio**.
  </Step>
  <Step>
    Enter your **Email** and **Password**. The eye button in the password field (**Show password**)
    shows what you typed.
  </Step>
  <Step>Click **Sign in**. The Studio opens.</Step>
</Steps>

Your email is not case sensitive. There is no sign-up form: the line under the form reads "New here? Ask an admin for an invite link."

## Sign in with GitHub [#sign-in-with-github]

When the server has GitHub sign-in set up, the sign-in screen shows **Continue with GitHub** under the form. Click it, approve the request on GitHub, and you return to the Studio page you started from.

GitHub sign-in works only for a GitHub account that already belongs to a member of this Studio. That is the case when you joined with GitHub from an invite link, or when you linked GitHub in [Settings](/studio/account#link-your-github-account). Otherwise the screen says "GitHub account `<handle>` is not a member of this workspace. Ask an admin for an invite."

## Join from an invite link [#join-from-an-invite-link]

An admin sends you an invite link that starts with your server's address and contains `/studio/join/`.

<Steps>
  <Step>
    Open the link. The screen reads **Join Sluby Studio** and says whether you join as an admin or a
    member, and until when the invite works.
  </Step>
  <Step>
    Fill in **Your name**, **Email** and **Password**. You choose your own email. The password needs
    at least 10 characters.
  </Step>
  <Step>Click **Join**. You are signed in and the Studio opens on the Overview page.</Step>
</Steps>

To join with your GitHub account instead, click **Continue with GitHub** on the same screen. The button shows only when the server has GitHub sign-in set up.

An invite link stops working when it expires, when an admin revokes it, or once as many people have joined with it as the admin allowed. If yours no longer works, ask the admin for a new one ([how admins create invites](/studio/members#invite-someone)).

## Set a new password from a reset link [#set-a-new-password-from-a-reset-link]

You cannot reset your own password from the sign-in screen. If you forgot it, ask an admin for a reset link ([how admins create reset links](/studio/members#give-someone-a-reset-link)). The link contains `/studio/reset/`.

<Steps>
  <Step>
    Open the link. The screen reads **Set a new password** and shows until when the link works.
  </Step>
  <Step>
    Enter a **New password** (at least 10 characters) and type it again in **Confirm new password**.
  </Step>
  <Step>
    Click **Set password**. You are signed in, and every other browser signed in to your account is
    signed out.
  </Step>
</Steps>

If you signed in only with GitHub until now, the screen reads "Choose the email and password you will sign in with." and also asks for an **Email**. After that you can sign in with either method.

## Sign out [#sign-out]

Click your initials at the top right to open the account menu, then click **Sign out**. On a phone, open the menu button at the top left: the account menu sits at the bottom of the sheet. The Studio returns to the sign-in screen.

You can also press `Ctrl K` (`⌘K` on a Mac), type "Sign out" and press Enter.

To sign out every browser at once, or one browser you do not recognize, use **Signed-in browsers** in [Settings](/studio/account#sign-out-other-browsers).

## Password rules [#password-rules]

These rules apply wherever you choose a password: when you join, set up the first admin, use a reset link, or change your password.

- At least 10 characters.
- At most 256 characters.

## Messages on the sign-in screen [#messages-on-the-sign-in-screen]

### When sign-in fails [#when-sign-in-fails]

| Message                                                                                                                                       | What to do                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Wrong email or password.                                                                                                                      | Check both and try again. If you forgot the password, ask an admin for a reset link.                                          |
| This account was removed from this workspace. Ask an admin to restore it.                                                                     | An admin removed you. Only an admin can restore your account.                                                                 |
| Too many attempts. Try again in 5 minutes.                                                                                                    | The server limits sign-in attempts. Wait for the time the message names, then try again.                                      |
| You signed in, but this browser did not keep the session. Allow cookies for this site and try again.                                          | Allow cookies for the Studio's address in your browser settings, then sign in again.                                          |
| GitHub account `<handle>` is not a member of this workspace. Ask an admin for an invite.                                                      | Join from an invite link first, or link GitHub in Settings while signed in with your password.                                |
| GitHub account `<handle>` already belongs to another member.                                                                                  | That GitHub account is linked to a different person in this Studio. Use another GitHub account or sign in with your password. |
| Sign-in was canceled on GitHub.                                                                                                               | You declined on GitHub. Click **Continue with GitHub** again to retry.                                                        |
| That sign-in link expired. Try again.                                                                                                         | The GitHub sign-in took too long or finished in a different browser. Click **Continue with GitHub** again in this browser.    |
| GitHub did not confirm the sign-in. Try again.                                                                                                | Click **Continue with GitHub** again.                                                                                         |
| Sign-in with GitHub is not set up on this server.                                                                                             | Sign in with your email and password.                                                                                         |
| That invite link does not exist, was already used, has expired, or was withdrawn (one sentence each, ending in "Ask an admin for a new one.") | Joining with GitHub from an invite link failed because the link no longer works. Ask the admin for a new invite link.         |
| Sign-in did not finish. Try again.                                                                                                            | Start the sign-in again.                                                                                                      |

The number in "Too many attempts" is the wait the server asks for, so it differs from case to case.

### When your session ends [#when-your-session-ends]

If your session ends while the Studio is open, the Studio returns to the sign-in screen with one of these notices. Sign in again to continue.

| Notice                                                                    | Why                                                                                                                                                         |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your session expired. Sign in again to continue.                          | Your session reached its end date.                                                                                                                          |
| You were signed out from another browser.                                 | This browser's session was ended elsewhere: from **Signed-in browsers** in Settings, with **Sign out everywhere**, by a password change or by a reset link. |
| Your account was removed from this workspace. Ask an admin to restore it. | An admin removed you from the team. Only an admin can restore you.                                                                                          |
| Your session ended. Sign in again to continue.                            | The browser no longer has a session, for example after its cookies were cleared.                                                                            |

For how long a session lasts, see [accounts, roles and sessions](/developers/concepts/accounts-and-roles#sessions).

### When an invite or reset link does not work [#when-an-invite-or-reset-link-does-not-work]

The link screen shows one of these messages and a **Go to sign in** button. Ask an admin for a new link.

- This link does not exist. Ask an admin for a new one.
- This link was already used. Ask an admin for a new one.
- This link has expired. Ask an admin for a new one.
- This link was withdrawn. Ask an admin for a new one.

### When the Studio cannot reach the server [#when-the-studio-cannot-reach-the-server]

Instead of the sign-in form, the Studio shows one of these, with a **Try again** button:

- **Could not reach the server**: check your connection, or ask the person who runs the server whether it is running.
- **The server ran into a problem**: the server answered with an error. Try again in a moment.
- **Could not check your session**: the server gave an answer the Studio could not use. The screen shows the reason.


# See how a video is stored on Sia (/studio/storage)

Check where a video lives on Sia: how many files it has, how much space it takes with redundancy, and which hosts and countries hold it. The details come from the Sia indexer the server is connected to.

## Open the Storage tab [#open-the-storage-tab]

<Steps>
  <Step>
    Open the video from **Videos**. The video must be **Ready**: the tab appears once processing is
    done.
  </Step>
  <Step>Click the **Storage** tab under the player.</Step>
</Steps>

## Sia storage [#sia-storage]

The card opens with one sentence in the form "This video is stored as N files on N hosts in N countries. Sia keeps N× the data, so the video stays playable if some hosts go offline."

Click **What do these numbers mean?** for a short definition of each Sia term. The figures:

| Figure         | What it means                                                                                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Objects**    | How many files make up the video on Sia: playlists, video files and thumbnails.                                                                                                                  |
| **Size**       | The size of those files.                                                                                                                                                                         |
| **On Sia**     | The space they take on Sia, with redundancy. When small files leave part of a slab empty, the line under it also shows how much of that is padding.                                              |
| **Redundancy** | How many times over Sia stores the data, as a ratio such as **3×**, with the shard counts under it in the form "N data + N parity shards". **Mixed** means the slabs use different shard counts. |
| **Slabs**      | The fixed-size blocks the files are packed into. A slab shared by several files counts once.                                                                                                     |
| **Sectors**    | The pieces hosts store, about 4.2 MB each, each on one host.                                                                                                                                     |
| **Hosts**      | How many hosts store part of the video.                                                                                                                                                          |
| **Countries**  | How many countries those hosts are in.                                                                                                                                                           |

Under the figures, "From the Sia indexer at" names the indexer's address and its network.

## Objects [#objects]

One row per Sia object of the video:

| Column        | What it shows                                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Object**    | What the object is: **Main playlist**, **Playlist**, **Video** (with its quality, for example 720p) or **Thumbnail**. |
| **Object ID** | The object's ID on Sia, with a copy button.                                                                           |
| **Size**      | The object's size.                                                                                                    |
| **Slabs**     | How many slabs it uses. A badge such as **2 shared** counts slabs it shares with other objects of this video.         |
| **Sectors**   | How many sectors hold it.                                                                                             |
| **Hosts**     | How many hosts hold it.                                                                                               |

## Host distribution and countries [#host-distribution-and-countries]

**Host distribution** lists each host with its country and how many sectors of the video it stores. Each host links to its page on Siascan (Zen Siascan when the server uses the Zen test network), or on another explorer if the person who runs the server set one. A host shows **Unknown** when the indexer did not report its location. The first 12 hosts show; click **Show all N hosts** for the rest.

**Countries** shows how many sectors and hosts of the video are in each country. Its bar compares the country's sectors with the country that holds the most. The first 8 show; click **Show all N countries** for the rest.

## On-chain [#on-chain]

When the server knows them, an **On-chain** card links the indexer's wallet and the file contracts with the hosts that store this video. File contracts are the on-chain agreements that pay hosts to keep their sectors. Each link opens the same explorer as the host links, in a new tab.

## When details are missing [#when-details-are-missing]

- **Could not load Sia storage details**: the server could not get the details. Click **Try again** when it is offered.
- **The Sia indexer did not describe N of N objects**: the indexer answered for only some objects, and the figures cover only those. Reload the page to ask again.

For how Sluby splits and stores video on Sia, see [Storage on Sia](/developers/concepts/storage-on-sia).


# Upload a video (/studio/upload)

Upload one or more video files from your computer. Each file gets a title and a public or private setting, then the Studio sends it to your server, which converts it for streaming and stores it on Sia.

## Upload a file [#upload-a-file]

<Steps>
  <Step>
    Click **Upload video** at the top of the sidebar, or press `U` on any Studio page. The **Upload
    videos** page opens.
  </Step>
  <Step>
    Drag files onto the box that reads **Drop video files here**, or click **Choose files**. You can
    add several files at once.
  </Step>
  <Step>
    For each file, check the **Title**. The Studio fills it in from the file name, for example
    `product_walkthrough-v2.mov` becomes "product walkthrough v2". Add a **Description** if you
    like.
  </Step>
  <Step>
    Under **Who can watch**, pick **Public** ("Anyone with the link or embed") or **Private** ("Only
    with signed links"). Each new file starts with the choice you made last. See [Choose who can
    watch](/studio/privacy) for what each means.
  </Step>
  <Step>
    Click **Start upload**, or press Enter in the title field. With several files waiting, a second
    button starts them all, for example **Upload 3 videos**.
  </Step>
</Steps>

You can also drop files anywhere on the **Videos** page. They open on the upload page, ready for a title.

The `U` shortcut does not fire while you type in a field or while a menu or dialog is open. Adding `?upload=1` to any Studio address, for example `https://sluby.example.com/studio?upload=1`, also opens the upload page.

## Accepted files and limits [#accepted-files-and-limits]

- **File types**: the drop box lists MP4, MOV, M4V, MKV, WebM and AVI. Files that are not videos are skipped with a message such as "notes.txt is not a video file."
- **Size**: the drop box shows the server's limit, for example "up to 10.7 GB each". A file over the limit shows "Too large for this server." in the list and a line such as "11.8 GB is over this server's 10.7 GB limit." under its title, and **Start upload** stays disabled. The person who runs the server sets this limit ([`MAX_UPLOAD_SIZE`](/self-hosting/configuration#max_upload_size)).
- **Empty files** are skipped: "clip.mp4 is empty and was skipped."
- **Title**: required, up to 200 characters. An empty title shows "Enter a title."
- **Description**: optional, up to 5,000 characters. A counter appears near the limit.

If you add a file you already uploaded from this browser, the form says "You uploaded this file 2 days ago as “Title”." with an **Open video** link, so you can avoid a duplicate.

## Follow the upload [#follow-the-upload]

Files you add and uploads you start appear in the **Files** list on the upload page. A summary above the list counts them, for example "1 uploading · 2 queued · 1 done".

While a file is sending, its row shows a progress bar and a line like "5.4 of 12 MB · 220 KB/s · about 30 s left". Once the whole file is sent, the row reads "File sent. Waiting for the server to confirm." Processing starts after that. To follow processing, see [Follow processing and retry](/studio/processing).

When a video is ready, its row turns into one line with a check mark, the title as a link to the video, and **Copy embed code**. If you are on another Studio page, a notice "“Title” is ready" appears with a **Copy embed code** button.

### Uploads keep going while you use the Studio [#uploads-keep-going-while-you-use-the-studio]

You can leave the upload page and keep working: uploads continue on every other Studio page. While uploads run, a progress ring shows in the top bar. Click it to see the **Uploads** list, and click **Open uploads** to return to the upload page.

Closing the browser tab stops the upload. While an upload is sending, the browser asks you to confirm before the tab closes.

### One file at a time [#one-file-at-a-time]

The Studio sends one file at a time. Files you start while another is sending wait in the list as **Queued, 2nd**, **Queued, 3rd** and so on, with a line such as "Starts when Intro finishes." To take a file out of the queue, click the close button on its row.

## Pause, resume and cancel [#pause-resume-and-cancel]

- **Pause** stops sending and keeps what was sent. The row shows "Paused" and how much is sent, for example "40% · 4.8 of 12 MB sent".
- **Resume** continues from where the file stopped.
- **Cancel** stops the upload and removes what was sent. The row says "Upload canceled. Nothing was kept."

If the server does not confirm the cancel, the row reads "Upload stopped but not cleaned up." with a **Try again** button.

## When the connection drops [#when-the-connection-drops]

If your connection drops, the row shows **Offline** and "The connection dropped. The upload continues when you are back online." The upload continues by itself once you are back online.

If the upload fails for another reason, the row shows **Failed**, the reason, and **Resume upload** when the file can continue. Files queued behind it wait: a **Queue paused** notice offers **Skip to next** to move on without it.

## Continue an upload after closing the tab [#continue-an-upload-after-closing-the-tab]

If the tab closed or the browser quit partway through an upload, you can continue it from the same browser.

<Steps>
  <Step>
    Open the upload page. A section **Unfinished from earlier** lists each upload that stopped
    partway, with how much was sent and when it started.
  </Step>
  <Step>
    Click **Choose file** on the row and pick the same file, or add the same file to the drop box.
    The upload continues from where it stopped, with the title and settings you gave it.
  </Step>
</Steps>

If you pick a different file, the row says "This is not the same file." and names the file it expects.

Continue within 24 hours of starting the upload. After that the server removes the partial file, and the same file starts over as a new upload.

To discard an unfinished upload, click **Delete** on its row and confirm. The server deletes the part already sent and the video entry.

### Uploads in another tab [#uploads-in-another-tab]

A file already uploading in another tab of the same browser cannot be added again: the page says "This file is already uploading in another tab." Those uploads show under **Uploading in another tab**. Manage them in the tab that sends them.


# Watch a video (/studio/watch)

Play any ready video on its video page in the Studio, choose the quality, and see whether the video streams from Sia or through your server.

## Play a video [#play-a-video]

<Steps>
  <Step>Open **Videos** in the sidebar and click the video's title.</Step>
  <Step>Press play in the player at the top of the page.</Step>
</Steps>

The player appears once the video's status is **Ready**. Before that, the same area shows its processing progress ([Follow processing and retry](/studio/processing)).

Private videos play in the Studio too. The Studio asks your server for a signed link for you.

The player uses your browser's own video controls, including its fullscreen button.

To watch without leaving the video list, use **Preview** on the **Videos** page ([Find and edit videos](/studio/library#open-or-preview-a-video)).

To send the video to someone or put it on your site, see [Share or embed a video](/studio/share).

## Pick a quality [#pick-a-quality]

A **Quality** menu sits on the top right of the player once the video loads.

- **Auto** lets the player choose and switch the quality as it plays. While **Auto** is on, the menu shows the quality playing now, for example "Auto (720p)".
- Pick a named quality, such as **1080p**, to keep the player on it.

The qualities offered are the ones the server made for this video. They are also listed in the **Quality** row of the video's **Details** card. For how the server picks them, see [the upload pipeline](/developers/concepts/upload-pipeline).

## Where the video streams from [#where-the-video-streams-from]

A badge next to the **Quality** menu shows where the video's data comes from:

| Badge                   | Meaning                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sia and this server** | The video starts through your server and the rest streams straight from Sia to your browser. Shown before the first part of the video has loaded. |
| **75% from Sia**        | The same mix, with the share of the data loaded so far that came straight from Sia. The number updates as the video plays.                        |
| **Through this server** | Your server fetches the video from Sia and passes it to your browser.                                                                             |

The Studio streams from Sia in your browser when the server is set up for it ([Stream from Sia in the browser](/self-hosting/direct-playback)). Otherwise, and in browsers that play the video with their built-in player (such as Safari on some iPhones), the badge reads **Through this server**. For how the delivery modes work, see [playback and delivery](/developers/concepts/playback).

## When a video does not play [#when-a-video-does-not-play]

If the player cannot play the video, a message **Could not play this video** appears under it with the reason. Reload the page to try again. If the video was deleted in another tab or browser while you had it open, the Studio says "This video was deleted in another tab or browser" and shows **Video not found**.


# Liveness probe. (/developers/reference/api/ops/get-health)

Answers while the process is up; dependency health is GET /api/v1/system/status, so a flaky indexer never restarts the container.

Full spec: /openapi.json

## GET /health

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "Liveness probe.",
  "description": "Answers while the process is up; dependency health is GET /api/v1/system/status, so a flaky indexer never restarts the container.",
  "security": [],
  "responses": {
    "200": {
      "description": "The process is up.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Health"
          }
        }
      }
    }
  }
}
```

# Platform metrics (prometheus registry as JSON). (/developers/reference/api/ops/get-metrics)

The registry counts the whole process, so only an admin may read it.

Full spec: /openapi.json

## GET /api/v1/metrics

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "Platform metrics (prometheus registry as JSON).",
  "description": "The registry counts the whole process, so only an admin may read it.",
  "x-required-scope": "read",
  "x-required-identity": "admin",
  "responses": {
    "200": {
      "description": "Metrics.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Metrics"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# This OpenAPI document. (/developers/reference/api/ops/get-openapi-json)



Full spec: /openapi.json

## GET /api/v1/openapi.json

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "This OpenAPI document.",
  "security": [],
  "responses": {
    "200": {
      "description": "The OpenAPI 3.1 document.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    }
  }
}
```

# Interactive API reference. (/developers/reference/api/ops/get-docs)



Full spec: /openapi.json

## GET /api/v1/docs

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "Interactive API reference.",
  "security": [],
  "responses": {
    "200": {
      "description": "HTML documentation page.",
      "content": {
        "text/html": {}
      }
    }
  }
}
```

# Library totals for the workspace. (/developers/reference/api/ops/get-stats)

The same totals for every member and key.

Full spec: /openapi.json

## GET /api/v1/stats

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "Library totals for the workspace.",
  "description": "The same totals for every member and key.",
  "x-required-scope": "read",
  "responses": {
    "200": {
      "description": "Totals.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetStats"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Plays per day of the workspace’s videos. (/developers/reference/api/ops/get-stats-usage)

Plays of the workspace’s videos per UTC day for the last `days` days, today included, oldest first, with days without plays as 0. What counts as a play is described on `play_count` of an asset.

Full spec: /openapi.json

## GET /api/v1/stats/usage

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "Plays per day of the workspace’s videos.",
  "description": "Plays of the workspace’s videos per UTC day for the last `days` days, today included, oldest first, with days without plays as 0. What counts as a play is described on `play_count` of an asset.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "days",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 90,
        "default": 30
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Plays per day.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "days",
              "total"
            ],
            "properties": {
              "days": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "date",
                    "plays"
                  ],
                  "properties": {
                    "date": {
                      "type": "string",
                      "format": "date",
                      "description": "YYYY-MM-DD, UTC."
                    },
                    "plays": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              },
              "total": {
                "type": "integer",
                "minimum": 0,
                "description": "Plays over all the days."
              }
            }
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Live platform status: database, redis, Sia indexer, reconciliation, cache. (/developers/reference/api/ops/get-system-status)

Admins get the full report; members a health summary (see SystemStatus).

Full spec: /openapi.json

## GET /api/v1/system/status

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "Live platform status: database, redis, Sia indexer, reconciliation, cache.",
  "description": "Admins get the full report; members a health summary (see SystemStatus).",
  "x-required-scope": "read",
  "responses": {
    "200": {
      "description": "Status report.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SystemStatus"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Delivery cache statistics. (/developers/reference/api/ops/get-cache-stats)



Full spec: /openapi.json

## GET /v1/cache/stats

```json
{
  "tags": [
    "Ops"
  ],
  "summary": "Delivery cache statistics.",
  "security": [],
  "responses": {
    "200": {
      "description": "Cache stats.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CacheStats"
          }
        }
      }
    }
  }
}
```

# Begin a Studio sign-in with a provider. (/developers/reference/api/auth/get-auth-provider-login)

Sets the short-lived `sluby_signin` cookie (path /api/v1/auth) holding the handshake state and where to land afterwards, then redirects to the provider. `next` is a path on this server; anything that would leave the origin falls back to /studio.

Full spec: /openapi.json

## GET /api/v1/auth/{provider}/login

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Begin a Studio sign-in with a provider.",
  "description": "Sets the short-lived `sluby_signin` cookie (path /api/v1/auth) holding the handshake state and where to land afterwards, then redirects to the provider. `next` is a path on this server; anything that would leave the origin falls back to /studio.",
  "security": [],
  "parameters": [
    {
      "name": "provider",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "github"
        ]
      },
      "description": "The sign-in provider."
    },
    {
      "name": "next",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Studio path to land on after sign-in, /studio by default."
    },
    {
      "name": "invite",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "An invite token: join as a new member with this provider account instead of signing in. The token stays in the handshake cookie and is never sent to the provider."
    },
    {
      "name": "link",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "1"
        ]
      },
      "description": "Add this provider account to the signed-in account (needs the session cookie)."
    }
  ],
  "responses": {
    "302": {
      "description": "Redirect to the provider, or back to `next` with `signin_error`: `not_configured` when the provider is not configured on this server, `invite_not_found` for a malformed invite token, `not_signed_in` for `link=1` without a session."
    },
    "404": {
      "description": "No such sign-in provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# The provider's redirect back after sign-in. (/developers/reference/api/auth/get-auth-provider-callback)

Browser-facing: every outcome is a redirect into the Studio. Accepted only from the browser that started the sign-in: the `state` must match the `sluby_signin` cookie set by the login route, within ten minutes. The account is the provider's stable id (GitHub: the numeric account id), never the login. A failure redirects to the page the sign-in started from (or `/studio` once the handshake is lost) with `signin_error=<code>` added: `expired_handshake` (expired, or started in another browser), `not_a_member` (with `&handle=<login>`, nobody added this account; people join through invites), `disabled` (with `&handle`, an admin removed the member), `already_linked` (with `&handle`, joining or linking with an account another member already signs in with), `not_signed_in` (a link finished without the session it began in), `invite_not_found`, `invite_used`, `invite_expired`, `invite_revoked` (with `&handle`, joining with an invite that does not work), `cancelled` (the person declined at the provider), `provider_failed` (the provider refused the code or could not be reached) or `not_configured`. A join signs the new member in; a link keeps the current session.

Full spec: /openapi.json

## GET /api/v1/auth/{provider}/callback

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "The provider's redirect back after sign-in.",
  "description": "Browser-facing: every outcome is a redirect into the Studio. Accepted only from the browser that started the sign-in: the `state` must match the `sluby_signin` cookie set by the login route, within ten minutes. The account is the provider's stable id (GitHub: the numeric account id), never the login. A failure redirects to the page the sign-in started from (or `/studio` once the handshake is lost) with `signin_error=<code>` added: `expired_handshake` (expired, or started in another browser), `not_a_member` (with `&handle=<login>`, nobody added this account; people join through invites), `disabled` (with `&handle`, an admin removed the member), `already_linked` (with `&handle`, joining or linking with an account another member already signs in with), `not_signed_in` (a link finished without the session it began in), `invite_not_found`, `invite_used`, `invite_expired`, `invite_revoked` (with `&handle`, joining with an invite that does not work), `cancelled` (the person declined at the provider), `provider_failed` (the provider refused the code or could not be reached) or `not_configured`. A join signs the new member in; a link keeps the current session.",
  "security": [],
  "parameters": [
    {
      "name": "provider",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "github"
        ]
      },
      "description": "The sign-in provider."
    }
  ],
  "responses": {
    "302": {
      "description": "Signed in (redirect to `next` with a session cookie), or failed (redirect to `next`, or `/studio`, with `signin_error=<code>`)."
    },
    "404": {
      "description": "No such sign-in provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# How this server signs people in. (/developers/reference/api/auth/get-auth-config)

Public: the Studio reads it before anyone is signed in, to show the setup screen or the sign-in methods.

Full spec: /openapi.json

## GET /api/v1/auth/config

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "How this server signs people in.",
  "description": "Public: the Studio reads it before anyone is signed in, to show the setup screen or the sign-in methods.",
  "security": [],
  "responses": {
    "200": {
      "description": "The sign-in configuration.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuthConfig"
          }
        }
      }
    }
  }
}
```

# Set up the first admin with the setup code, and sign in. (/developers/reference/api/auth/post-auth-setup)

Works while `setup_required` is true: no admin who can sign in exists. The code is printed in the server log at startup. 10 attempts per client address in 10 minutes.

Full spec: /openapi.json

## POST /api/v1/auth/setup

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Set up the first admin with the setup code, and sign in.",
  "description": "Works while `setup_required` is true: no admin who can sign in exists. The code is printed in the server log at startup. 10 attempts per client address in 10 minutes.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SetupRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The admin exists and is signed in.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      },
      "headers": {
        "Set-Cookie": {
          "description": "The `sluby_session` cookie of the new session (HttpOnly, SameSite=Lax).",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "403": {
      "description": "Wrong setup code (`reason: bad_code`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "An admin already exists (`already_set_up`), the email is taken (`email_taken`), or sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Too many attempts; try again after `retry_after` seconds.",
      "headers": {
        "Retry-After": {
          "$ref": "#/components/headers/RetryAfter"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RateLimited"
          }
        }
      }
    }
  }
}
```

# Sign in with an email and password. (/developers/reference/api/auth/post-auth-password)

10 attempts per client address in 10 minutes, and 5 wrong passwords per email in 15 minutes.

Full spec: /openapi.json

## POST /api/v1/auth/password

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Sign in with an email and password.",
  "description": "10 attempts per client address in 10 minutes, and 5 wrong passwords per email in 15 minutes.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PasswordSignInRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Signed in.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      },
      "headers": {
        "Set-Cookie": {
          "description": "The `sluby_session` cookie of the new session (HttpOnly, SameSite=Lax).",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "description": "Wrong email or password (`reason: bad_credentials`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "The password is right but the account was removed (`disabled`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Too many attempts; try again after `retry_after` seconds.",
      "headers": {
        "Retry-After": {
          "$ref": "#/components/headers/RetryAfter"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RateLimited"
          }
        }
      }
    }
  }
}
```

# Change the signed-in member's password. (/developers/reference/api/auth/post-auth-password-change)

Studio sessions only. Every other session of the account ends; this one stays. `revoked` is how many ended.

Full spec: /openapi.json

## POST /api/v1/auth/password/change

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Change the signed-in member's password.",
  "description": "Studio sessions only. Every other session of the account ends; this one stays. `revoked` is how many ended.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PasswordChangeRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Changed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SessionsRevoked"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "description": "The current password is wrong (`reason: bad_credentials`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "The account has no password (`no_password`), or sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Too many attempts; try again after `retry_after` seconds.",
      "headers": {
        "Retry-After": {
          "$ref": "#/components/headers/RetryAfter"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RateLimited"
          }
        }
      }
    }
  }
}
```

# What an invite or reset link is for. (/developers/reference/api/auth/get-auth-invites-token)

Public: the join and reset pages call it with the token from their url. 30 link requests per client address in 10 minutes.

Full spec: /openapi.json

## GET /api/v1/auth/invites/{token}

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "What an invite or reset link is for.",
  "description": "Public: the join and reset pages call it with the token from their url. 30 link requests per client address in 10 minutes.",
  "security": [],
  "parameters": [
    {
      "name": "token",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "The token from the invite or reset link."
    }
  ],
  "responses": {
    "200": {
      "description": "The link works.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/LinkInfo"
          }
        }
      }
    },
    "403": {
      "description": "A reset link of a removed member (`disabled`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No such link.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "410": {
      "description": "The link was `used`, has `expired` or was `revoked` (in `reason`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Too many attempts; try again after `retry_after` seconds.",
      "headers": {
        "Retry-After": {
          "$ref": "#/components/headers/RetryAfter"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RateLimited"
          }
        }
      }
    }
  }
}
```

# Use an invite or reset link, and sign in. (/developers/reference/api/auth/post-auth-invites-token-accept)

An invite makes a new member with its role. A reset link sets the member’s password (their first, when they had none) and ends every other session of the account. Either way the link is used up and the browser is signed in.

Full spec: /openapi.json

## POST /api/v1/auth/invites/{token}/accept

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Use an invite or reset link, and sign in.",
  "description": "An invite makes a new member with its role. A reset link sets the member’s password (their first, when they had none) and ends every other session of the account. Either way the link is used up and the browser is signed in.",
  "security": [],
  "parameters": [
    {
      "name": "token",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "The token from the invite or reset link."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LinkAcceptRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Password set from a reset link, signed in.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      },
      "headers": {
        "Set-Cookie": {
          "description": "The `sluby_session` cookie of the new session (HttpOnly, SameSite=Lax).",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "201": {
      "description": "Joined with an invite, signed in.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      },
      "headers": {
        "Set-Cookie": {
          "description": "The `sluby_session` cookie of the new session (HttpOnly, SameSite=Lax).",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "403": {
      "description": "A reset link of a removed member (`disabled`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No such link.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Another account signs in with this email (`email_taken`), or sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "410": {
      "description": "The link was `used`, has `expired` or was `revoked` (in `reason`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Too many attempts; try again after `retry_after` seconds.",
      "headers": {
        "Retry-After": {
          "$ref": "#/components/headers/RetryAfter"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RateLimited"
          }
        }
      }
    }
  }
}
```

# The signed-in account. (/developers/reference/api/auth/get-auth-me)

The account id and display name, plus the provider, provider label and handle the browser signed in with, its role, every way it signs in (`sign_in`), and the session expiry. With AUTH_DISABLED it is the local dev account (`provider: "local"`, `auth_disabled: true`, `role: "admin"`).

Full spec: /openapi.json

## GET /api/v1/auth/me

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "The signed-in account.",
  "description": "The account id and display name, plus the provider, provider label and handle the browser signed in with, its role, every way it signs in (`sign_in`), and the session expiry. With AUTH_DISABLED it is the local dev account (`provider: \"local\"`, `auth_disabled: true`, `role: \"admin\"`).",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "The signed-in account, or the local dev account.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuthMe"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

# Change the signed-in member's name. (/developers/reference/api/auth/patch-auth-me)

Studio sessions only. The name the members list and the Studio show.

Full spec: /openapi.json

## PATCH /api/v1/auth/me

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Change the signed-in member's name.",
  "description": "Studio sessions only. The name the members list and the Studio show.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RenameRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Renamed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "409": {
      "description": "Sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# Change the email the signed-in member signs in with. (/developers/reference/api/auth/post-auth-email-change)

Studio sessions only. Needs the current password; the password itself stays. Counts against the same attempt limits as a password change.

Full spec: /openapi.json

## POST /api/v1/auth/email/change

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Change the email the signed-in member signs in with.",
  "description": "Studio sessions only. Needs the current password; the password itself stays. Counts against the same attempt limits as a password change.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EmailChangeRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Changed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "description": "The current password is wrong (`reason: bad_credentials`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Another account signs in with that email (`email_taken`), the account has no password (`no_password`), or sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Too many attempts; try again after `retry_after` seconds.",
      "headers": {
        "Retry-After": {
          "$ref": "#/components/headers/RetryAfter"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RateLimited"
          }
        }
      }
    }
  }
}
```

# Stop signing in with a provider. (/developers/reference/api/auth/delete-auth-identities-provider)

Studio sessions only. Takes a provider such as GitHub off the signed-in account. Sessions that signed in through it end. An email and password is changed, not removed.

Full spec: /openapi.json

## DELETE /api/v1/auth/identities/{provider}

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Stop signing in with a provider.",
  "description": "Studio sessions only. Takes a provider such as GitHub off the signed-in account. Sessions that signed in through it end. An email and password is changed, not removed.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "parameters": [
    {
      "name": "provider",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "github"
        ]
      },
      "description": "The sign-in provider."
    }
  ],
  "responses": {
    "200": {
      "description": "Removed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "description": "No such provider, or the account does not sign in with it.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "This browser signed in with it (`current_sign_in`), it is the only way to sign in (`last_sign_in`), or sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# End the current session and clear its cookie. (/developers/reference/api/auth/post-auth-logout)



Full spec: /openapi.json

## POST /api/v1/auth/logout

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "End the current session and clear its cookie.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Logged out.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    }
  }
}
```

# The signed-in user's live Studio sessions, newest first. (/developers/reference/api/auth/get-auth-sessions)

Studio sessions only: an API key cannot list sessions.

Full spec: /openapi.json

## GET /api/v1/auth/sessions

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "The signed-in user's live Studio sessions, newest first.",
  "description": "Studio sessions only: an API key cannot list sessions.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "The sessions.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StudioSessionList"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "409": {
      "description": "Sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# Sign out everywhere: end every session of the signed-in account. (/developers/reference/api/auth/delete-auth-sessions)

API keys are not touched; revoke them from the keys routes.

Full spec: /openapi.json

## DELETE /api/v1/auth/sessions

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "Sign out everywhere: end every session of the signed-in account.",
  "description": "API keys are not touched; revoke them from the keys routes.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Sessions ended; `revoked` is how many.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SessionsRevoked"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "409": {
      "description": "Sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# End one session of the signed-in user. (/developers/reference/api/auth/delete-auth-sessions-id)



Full spec: /openapi.json

## DELETE /api/v1/auth/sessions/{id}

```json
{
  "tags": [
    "Auth"
  ],
  "summary": "End one session of the signed-in user.",
  "security": [
    {
      "cookieAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Session id, from GET /api/v1/auth/sessions."
    }
  ],
  "responses": {
    "200": {
      "description": "Session ended.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Sign-in is disabled on this server.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# Start a resumable upload (tus 1.0.0 creation). (/developers/reference/api/uploads/post-uploads)

Creates the video asset and answers with the upload url in Location: `<PUBLIC_URL>/api/v1/uploads/<upload id>`. The upload id (a uuid) is also the id of GET and DELETE /api/v1/uploads/{id}. Send the bytes with PATCH to that url; a HEAD on it returns Upload-Metadata with videoAssetId. Metadata keys (values base64): filename, filetype (must be video/* when given), title (up to 200 characters, "Untitled" when missing), description (up to 5000 characters), accessTier or access_tier (public or private, default public). Errors answer plain text.

Full spec: /openapi.json

## POST /api/v1/uploads

```json
{
  "tags": [
    "Uploads"
  ],
  "summary": "Start a resumable upload (tus 1.0.0 creation).",
  "description": "Creates the video asset and answers with the upload url in Location: `<PUBLIC_URL>/api/v1/uploads/<upload id>`. The upload id (a uuid) is also the id of GET and DELETE /api/v1/uploads/{id}. Send the bytes with PATCH to that url; a HEAD on it returns Upload-Metadata with videoAssetId. Metadata keys (values base64): filename, filetype (must be video/* when given), title (up to 200 characters, \"Untitled\" when missing), description (up to 5000 characters), accessTier or access_tier (public or private, default public). Errors answer plain text.",
  "x-required-scope": "upload",
  "x-handled-by": "tus",
  "parameters": [
    {
      "name": "Tus-Resumable",
      "in": "header",
      "required": true,
      "schema": {
        "const": "1.0.0"
      }
    },
    {
      "name": "Upload-Length",
      "in": "header",
      "required": true,
      "schema": {
        "type": "integer",
        "minimum": 1
      },
      "description": "Size in bytes; at most MAX_UPLOAD_SIZE (10 GB by default)."
    },
    {
      "name": "Upload-Metadata",
      "in": "header",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "201": {
      "description": "Created; the upload url is in Location.",
      "headers": {
        "Location": {
          "schema": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "400": {
      "description": "Invalid metadata (tier, title, description) or an empty file.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "401": {
      "description": "No valid API key or session.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks the upload scope.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "413": {
      "description": "Larger than MAX_UPLOAD_SIZE.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "415": {
      "description": "Not a video file type.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "500": {
      "description": "The upload could not be created; nothing was kept.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

# Upload status. (/developers/reference/api/uploads/get-uploads-id)



Full spec: /openapi.json

## GET /api/v1/uploads/{id}

```json
{
  "tags": [
    "Uploads"
  ],
  "summary": "Upload status.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Upload id, the last segment of the tus Location."
    }
  ],
  "responses": {
    "200": {
      "description": "Status and progress.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UploadStatus"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Send upload bytes (tus). (/developers/reference/api/uploads/patch-uploads-id)



Full spec: /openapi.json

## PATCH /api/v1/uploads/{id}

```json
{
  "tags": [
    "Uploads"
  ],
  "summary": "Send upload bytes (tus).",
  "x-required-scope": "upload",
  "x-handled-by": "tus",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Upload id, the last segment of Location."
    },
    {
      "name": "Tus-Resumable",
      "in": "header",
      "required": true,
      "schema": {
        "const": "1.0.0"
      }
    },
    {
      "name": "Upload-Offset",
      "in": "header",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/offset+octet-stream": {}
    }
  },
  "responses": {
    "204": {
      "description": "Accepted; Upload-Offset is the new offset."
    },
    "400": {
      "description": "Invalid tus headers.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "401": {
      "description": "No valid API key or session.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "403": {
      "description": "The key lacks the upload scope.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "404": {
      "description": "No such upload in the workspace.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "409": {
      "description": "Upload-Offset does not match the bytes received so far.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "410": {
      "description": "The upload expired.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "413": {
      "description": "More bytes than the declared Upload-Length.",
      "content": {
        "text/plain": {
          "schema": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

# Cancel an upload in progress. (/developers/reference/api/uploads/delete-uploads-id)

Without Tus-Resumable this is the REST cancel: the partial file and the asset the upload created are removed, and the session is marked cancelled (200). With Tus-Resumable it is a tus termination, which does the same and answers 204. A finished upload is the source its asset is processed and retried from and cannot be cancelled: REST answers 409, tus 400; delete the asset instead (manage scope).

Full spec: /openapi.json

## DELETE /api/v1/uploads/{id}

```json
{
  "tags": [
    "Uploads"
  ],
  "summary": "Cancel an upload in progress.",
  "description": "Without Tus-Resumable this is the REST cancel: the partial file and the asset the upload created are removed, and the session is marked cancelled (200). With Tus-Resumable it is a tus termination, which does the same and answers 204. A finished upload is the source its asset is processed and retried from and cannot be cancelled: REST answers 409, tus 400; delete the asset instead (manage scope).",
  "x-required-scope": "upload",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Upload id, the last segment of the tus Location."
    }
  ],
  "responses": {
    "200": {
      "description": "Cancelled (REST).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    },
    "204": {
      "description": "Terminated (tus)."
    },
    "400": {
      "description": "A malformed id (REST), or a tus termination of a finished upload (plain text).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "The upload is no longer in progress (REST).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Upload offset and metadata (tus). (/developers/reference/api/uploads/head-uploads-id)



Full spec: /openapi.json

## HEAD /api/v1/uploads/{id}

```json
{
  "tags": [
    "Uploads"
  ],
  "summary": "Upload offset and metadata (tus).",
  "x-required-scope": "upload",
  "x-handled-by": "tus",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Upload id."
    },
    {
      "name": "Tus-Resumable",
      "in": "header",
      "required": true,
      "schema": {
        "const": "1.0.0"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Upload-Offset and Upload-Metadata headers."
    },
    "401": {
      "description": "No valid API key or session."
    },
    "403": {
      "description": "The key lacks the upload scope."
    },
    "404": {
      "description": "No such upload in the workspace."
    },
    "410": {
      "description": "The upload expired."
    }
  }
}
```

# List assets with search, filters, sorting and pagination. (/developers/reference/api/assets/get-assets)

Each parameter may be given once; a repeated or malformed one is a 400. Unknown parameters are ignored.

Full spec: /openapi.json

## GET /api/v1/assets

```json
{
  "tags": [
    "Assets"
  ],
  "summary": "List assets with search, filters, sorting and pagination.",
  "description": "Each parameter may be given once; a repeated or malformed one is a 400. Unknown parameters are ignored.",
  "x-required-scope": "read",
  "parameters": [
    {
      "$ref": "#/components/parameters/limit"
    },
    {
      "$ref": "#/components/parameters/cursor"
    },
    {
      "$ref": "#/components/parameters/page"
    },
    {
      "name": "status",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "created",
          "uploading",
          "processing",
          "ready",
          "failed"
        ]
      },
      "description": "Filter by status."
    },
    {
      "name": "access_tier",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "public",
          "private"
        ]
      }
    },
    {
      "name": "search",
      "in": "query",
      "schema": {
        "type": "string",
        "maxLength": 200
      },
      "description": "Case-insensitive match on title or description, or an exact asset id."
    },
    {
      "name": "sort",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "created_at",
          "title",
          "duration",
          "size"
        ],
        "default": "created_at"
      }
    },
    {
      "name": "order",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "asc",
          "desc"
        ],
        "default": "desc"
      },
      "description": "Cursor paging is only available for created_at desc; other orders use page."
    }
  ],
  "responses": {
    "200": {
      "description": "A page of assets.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetList"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Get an asset. (/developers/reference/api/assets/get-assets-id)



Full spec: /openapi.json

## GET /api/v1/assets/{id}

```json
{
  "tags": [
    "Assets"
  ],
  "summary": "Get an asset.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "responses": {
    "200": {
      "description": "The asset.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Asset"
          }
        }
      },
      "headers": {
        "ETag": {
          "description": "The asset’s version: its `updated_at` in milliseconds since the epoch, quoted. Send it back in If-Match on PATCH. Plays do not change it, so it never validates a cached copy: GET answers with `Cache-Control: no-store` and ignores If-None-Match.",
          "schema": {
            "type": "string",
            "example": "\"1767225600000\""
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Update asset metadata. (/developers/reference/api/assets/patch-assets-id)

Changing access_tier takes effect on the delivery gateway at once. An asset being deleted answers 404, as it does to every read. Send If-Match with the ETag of the version you edited (from GET or an earlier PATCH, or built from `updated_at` as `"<epoch milliseconds>"`) and the edit applies only if nobody changed the asset since; otherwise 412 with the asset as it is now. Processing changes the version too.

Full spec: /openapi.json

## PATCH /api/v1/assets/{id}

```json
{
  "tags": [
    "Assets"
  ],
  "summary": "Update asset metadata.",
  "description": "Changing access_tier takes effect on the delivery gateway at once. An asset being deleted answers 404, as it does to every read. Send If-Match with the ETag of the version you edited (from GET or an earlier PATCH, or built from `updated_at` as `\"<epoch milliseconds>\"`) and the edit applies only if nobody changed the asset since; otherwise 412 with the asset as it is now. Processing changes the version too.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    },
    {
      "name": "If-Match",
      "in": "header",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "One or more ETags, or `*` for any version. The weak form of an ETag (`W/\"…\"`, as a compressing proxy such as the bundled nginx sends it) matches the same version."
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Trimmed; no control characters."
            },
            "description": {
              "type": "string",
              "maxLength": 5000,
              "description": "No control characters other than tabs and line breaks."
            },
            "access_tier": {
              "type": "string",
              "enum": [
                "public",
                "private"
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Asset"
          }
        }
      },
      "headers": {
        "ETag": {
          "description": "The asset’s version: its `updated_at` in milliseconds since the epoch, quoted. Send it back in If-Match on PATCH. Plays do not change it, so it never validates a cached copy: GET answers with `Cache-Control: no-store` and ignores If-None-Match.",
          "schema": {
            "type": "string",
            "example": "\"1767225600000\""
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, or an If-Match that is not an ETag.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "412": {
      "description": "The asset changed since the If-Match version; nothing was saved.",
      "headers": {
        "ETag": {
          "description": "The asset’s version: its `updated_at` in milliseconds since the epoch, quoted. Send it back in If-Match on PATCH. Plays do not change it, so it never validates a cached copy: GET answers with `Cache-Control: no-store` and ignores If-None-Match.",
          "schema": {
            "type": "string",
            "example": "\"1767225600000\""
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error",
              "current"
            ],
            "properties": {
              "error": {
                "type": "string"
              },
              "current": {
                "$ref": "#/components/schemas/Asset"
              }
            }
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Delete an asset. (/developers/reference/api/assets/delete-assets-id)

Soft-deletes the asset so it disappears from the API immediately, then asynchronously unpins its Sia objects and removes the record. A second DELETE answers 404.

Full spec: /openapi.json

## DELETE /api/v1/assets/{id}

```json
{
  "tags": [
    "Assets"
  ],
  "summary": "Delete an asset.",
  "description": "Soft-deletes the asset so it disappears from the API immediately, then asynchronously unpins its Sia objects and removes the record. A second DELETE answers 404.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "responses": {
    "200": {
      "description": "Deletion accepted; unpin runs in the background.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetDeleted"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Processing status for an asset. (/developers/reference/api/assets/get-assets-id-processing)



Full spec: /openapi.json

## GET /api/v1/assets/{id}/processing

```json
{
  "tags": [
    "Assets"
  ],
  "summary": "Processing status for an asset.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "responses": {
    "200": {
      "description": "Processing status.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProcessingStatus"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "description": "No such asset, or it has no processing job yet.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# HLS renditions of an asset, tallest first. (/developers/reference/api/assets/get-assets-id-renditions)



Full spec: /openapi.json

## GET /api/v1/assets/{id}/renditions

```json
{
  "tags": [
    "Assets"
  ],
  "summary": "HLS renditions of an asset, tallest first.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "responses": {
    "200": {
      "description": "Renditions.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Rendition"
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Retry a failed asset. (/developers/reference/api/assets/post-assets-id-retry)



Full spec: /openapi.json

## POST /api/v1/assets/{id}/retry

```json
{
  "tags": [
    "Assets"
  ],
  "summary": "Retry a failed asset.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "responses": {
    "200": {
      "description": "Retry enqueued.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RetryStarted"
          }
        }
      }
    },
    "400": {
      "description": "A malformed id, or the asset is not in the failed state.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "410": {
      "description": "The source file is gone; upload the video again.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Per-asset Sia storage breakdown. (/developers/reference/api/storage/get-assets-id-sia)

Objects the indexer cannot describe right now are listed in unavailable_object_ids rather than failing the request.

Full spec: /openapi.json

## GET /api/v1/assets/{id}/sia

```json
{
  "tags": [
    "Storage"
  ],
  "summary": "Per-asset Sia storage breakdown.",
  "description": "Objects the indexer cannot describe right now are listed in unavailable_object_ids rather than failing the request.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "responses": {
    "200": {
      "description": "Storage breakdown.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SiaStorageInfo"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# List playback IDs for an asset. (/developers/reference/api/playback/get-assets-id-playback-ids)



Full spec: /openapi.json

## GET /api/v1/assets/{id}/playback-ids

```json
{
  "tags": [
    "Playback"
  ],
  "summary": "List playback IDs for an asset.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "responses": {
    "200": {
      "description": "Playback IDs.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlaybackIdList"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Create a playback ID. (/developers/reference/api/playback/post-assets-id-playback-ids)



Full spec: /openapi.json

## POST /api/v1/assets/{id}/playback-ids

```json
{
  "tags": [
    "Playback"
  ],
  "summary": "Create a playback ID.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset id."
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "policy": {
              "type": "string",
              "enum": [
                "public",
                "signed"
              ],
              "default": "public"
            },
            "name": {
              "type": "string",
              "maxLength": 100,
              "description": "A label to tell playback IDs apart. Trimmed; no control characters."
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlaybackId"
          }
        }
      }
    },
    "400": {
      "description": "A malformed id, an unknown policy or a name over 100 characters.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Delete a playback ID. (/developers/reference/api/playback/delete-playback-ids-playbackid)



Full spec: /openapi.json

## DELETE /api/v1/playback-ids/{playbackId}

```json
{
  "tags": [
    "Playback"
  ],
  "summary": "Delete a playback ID.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "playbackId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Public pb_ handle."
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Playback info + URL for an asset or playback ID. (/developers/reference/api/playback/get-playback-id)



Full spec: /openapi.json

## GET /api/v1/playback/{id}

```json
{
  "tags": [
    "Playback"
  ],
  "summary": "Playback info + URL for an asset or playback ID.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset UUID or pb_ playback ID."
    }
  ],
  "responses": {
    "200": {
      "description": "Playback info.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlaybackInfo"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "The asset is not ready for playback.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Time-limited signed playback URL. (/developers/reference/api/playback/get-playback-id-signed)

Signs the master manifest (and the first thumbnail as a poster) for the asset. The signature covers the asset signing generation, so every url minted so far stops working when the asset tier changes or POST /api/v1/playback/{id}/signed/revoke is called. A url never lasts longer than six hours.

Full spec: /openapi.json

## GET /api/v1/playback/{id}/signed

```json
{
  "tags": [
    "Playback"
  ],
  "summary": "Time-limited signed playback URL.",
  "description": "Signs the master manifest (and the first thumbnail as a poster) for the asset. The signature covers the asset signing generation, so every url minted so far stops working when the asset tier changes or POST /api/v1/playback/{id}/signed/revoke is called. A url never lasts longer than six hours.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset UUID or pb_ playback ID."
    },
    {
      "name": "expires_in",
      "in": "query",
      "schema": {
        "type": "integer",
        "default": 3600,
        "minimum": 60,
        "maximum": 21600
      },
      "description": "Lifetime of the url in seconds. A whole number outside 60 to 21600 is brought to the nearest bound (the answer `expires_at` says what was minted); anything else is a 400."
    }
  ],
  "responses": {
    "200": {
      "description": "Signed URL.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SignedUrl"
          }
        }
      }
    },
    "400": {
      "description": "A malformed id, or an expires_in that is not a whole number.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "The asset is not ready for playback.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Revoke every signed URL of an asset. (/developers/reference/api/playback/post-playback-id-signed-revoke)

Raises the asset signing generation, so every signed url minted for it so far (and every child url signed from one) is refused from now on; new ones can be minted straight away. A pb_ id revokes for its whole asset. Copies of public objects a shared cache already holds are unaffected, and sia:// share maps run until their own expiry.

Full spec: /openapi.json

## POST /api/v1/playback/{id}/signed/revoke

```json
{
  "tags": [
    "Playback"
  ],
  "summary": "Revoke every signed URL of an asset.",
  "description": "Raises the asset signing generation, so every signed url minted for it so far (and every child url signed from one) is refused from now on; new ones can be minted straight away. A pb_ id revokes for its whole asset. Copies of public objects a shared cache already holds are unaffected, and sia:// share maps run until their own expiry.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset UUID or pb_ playback ID."
    }
  ],
  "responses": {
    "200": {
      "description": "Revoked.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SignedUrlsRevoked"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Per-object sia:// share URLs for direct-from-Sia playback. (/developers/reference/api/playback/get-playback-id-share)



Full spec: /openapi.json

## GET /api/v1/playback/{id}/share

```json
{
  "tags": [
    "Playback"
  ],
  "summary": "Per-object sia:// share URLs for direct-from-Sia playback.",
  "x-required-scope": "read",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset UUID or pb_ playback ID."
    },
    {
      "name": "expires_in",
      "in": "query",
      "schema": {
        "type": "integer",
        "default": 3600
      }
    },
    {
      "name": "renew",
      "in": "query",
      "schema": {
        "type": "string"
      },
      "description": "Set (any value) when replacing a map the player already holds during one watch, so it is not counted as another play. The SDK sets it."
    }
  ],
  "responses": {
    "200": {
      "description": "Share URL map.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SharePlaybackInfo"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "The asset is not ready for playback.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    },
    "502": {
      "description": "The Sia indexer did not answer while minting.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "The database did not answer while minting.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# Every member of the workspace, removed ones included. (/developers/reference/api/members/get-members)



Full spec: /openapi.json

## GET /api/v1/members

```json
{
  "tags": [
    "Members"
  ],
  "summary": "Every member of the workspace, removed ones included.",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "The members.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemberList"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Change a member's role. (/developers/reference/api/members/patch-members-id)

Applies to their sessions and keys on their next request. The last admin who can sign in stays an admin (409 `last_admin`).

Full spec: /openapi.json

## PATCH /api/v1/members/{id}

```json
{
  "tags": [
    "Members"
  ],
  "summary": "Change a member's role.",
  "description": "Applies to their sessions and keys on their next request. The last admin who can sign in stays an admin (409 `last_admin`).",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Member id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RoleRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The member with the new role.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Member"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "It would leave no admin who can sign in (`last_admin`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Remove a member. (/developers/reference/api/members/post-members-id-remove)

They cannot sign in, every session they have ends and their keys stop, until they are restored. Nobody removes themselves (409 `self`), and the last admin who can sign in stays (409 `last_admin`).

Full spec: /openapi.json

## POST /api/v1/members/{id}/remove

```json
{
  "tags": [
    "Members"
  ],
  "summary": "Remove a member.",
  "description": "They cannot sign in, every session they have ends and their keys stop, until they are restored. Nobody removes themselves (409 `self`), and the last admin who can sign in stays (409 `last_admin`).",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Member id."
    }
  ],
  "responses": {
    "200": {
      "description": "The removed member.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Member"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "`self` or `last_admin`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Let a removed member back in. (/developers/reference/api/members/post-members-id-restore)

They keep the role they had, and their keys work again.

Full spec: /openapi.json

## POST /api/v1/members/{id}/restore

```json
{
  "tags": [
    "Members"
  ],
  "summary": "Let a removed member back in.",
  "description": "They keep the role they had, and their keys work again.",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Member id."
    }
  ],
  "responses": {
    "200": {
      "description": "The restored member.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Member"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# A link where the member sets a new password. (/developers/reference/api/members/post-members-id-reset-link)

Single use, valid for 7 days. For a member who signs in with GitHub only it sets their first password, with an email they choose. Using it ends their other sessions.

Full spec: /openapi.json

## POST /api/v1/members/{id}/reset-link

```json
{
  "tags": [
    "Members"
  ],
  "summary": "A link where the member sets a new password.",
  "description": "Single use, valid for 7 days. For a member who signs in with GitHub only it sets their first password, with an email they choose. Using it ends their other sessions.",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Member id."
    }
  ],
  "responses": {
    "201": {
      "description": "The link, shown only here.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResetLink"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Pending invites, newest first. (/developers/reference/api/members/get-invites)

Invites that still let someone join, with how many people joined with each. Their links are not shown.

Full spec: /openapi.json

## GET /api/v1/invites

```json
{
  "tags": [
    "Members"
  ],
  "summary": "Pending invites, newest first.",
  "description": "Invites that still let someone join, with how many people joined with each. Their links are not shown.",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "The invites.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InviteList"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Invite new people with a role. (/developers/reference/api/members/post-invites)

By default the link lets one person join and works for 7 days. `max_uses` lets more people join with it (members only) and `expires_in_days` sets 1, 7 or 30 days. Sluby sends no email: pass the link on yourself.

Full spec: /openapi.json

## POST /api/v1/invites

```json
{
  "tags": [
    "Members"
  ],
  "summary": "Invite new people with a role.",
  "description": "By default the link lets one person join and works for 7 days. `max_uses` lets more people join with it (members only) and `expires_in_days` sets 1, 7 or 30 days. Sluby sends no email: pass the link on yourself.",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/InviteRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The invite, with its link shown only here.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InviteCreated"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Withdraw a pending invite. (/developers/reference/api/members/delete-invites-id)



Full spec: /openapi.json

## DELETE /api/v1/invites/{id}

```json
{
  "tags": [
    "Members"
  ],
  "summary": "Withdraw a pending invite.",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Invite id, from GET /api/v1/invites."
    }
  ],
  "responses": {
    "200": {
      "description": "Withdrawn; the link no longer works.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# List API keys. (/developers/reference/api/keys/get-keys)

Usable keys of the workspace, newest first, with who made each, including rotated-out keys still in their grace period. Pages hold up to 1000 keys; follow next_cursor while has_more is true.

Full spec: /openapi.json

## GET /api/v1/keys

```json
{
  "tags": [
    "Keys"
  ],
  "summary": "List API keys.",
  "description": "Usable keys of the workspace, newest first, with who made each, including rotated-out keys still in their grace period. Pages hold up to 1000 keys; follow next_cursor while has_more is true.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 1000,
        "default": 1000
      }
    },
    {
      "$ref": "#/components/parameters/cursor"
    }
  ],
  "responses": {
    "200": {
      "description": "A page of keys.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiKeyList"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Create an API key. (/developers/reference/api/keys/post-keys)

The key belongs to the workspace and is made by the calling member, whose role it acts with (`created_by`); a key with no creator makes keys with no creator. The answer has the shape of a listed key plus `key`, the secret, which is never shown again.

Full spec: /openapi.json

## POST /api/v1/keys

```json
{
  "tags": [
    "Keys"
  ],
  "summary": "Create an API key.",
  "description": "The key belongs to the workspace and is made by the calling member, whose role it acts with (`created_by`); a key with no creator makes keys with no creator. The answer has the shape of a listed key plus `key`, the secret, which is never shown again.",
  "x-required-scope": "manage",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "description": "Trimmed; no control characters."
            },
            "scopes": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "enum": [
                  "upload",
                  "read",
                  "manage"
                ]
              },
              "default": [
                "upload",
                "read"
              ],
              "description": "A scope listed twice counts once."
            },
            "rate_limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 100,
              "description": "Requests per minute, at most the server’s `API_KEY_RATE_LIMIT_MAX` (10000 by default)."
            }
          },
          "required": [
            "name"
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created (the secret is shown once).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiKeyCreated"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "description": "The workspace already holds the most usable keys allowed (`API_KEYS_PER_ACCOUNT_MAX`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Rotate an API key. (/developers/reference/api/keys/post-keys-id-rotate)

Issues a new secret with the same name, scopes and rate limit. The old key stops working now, or after grace_period_seconds (up to 604800) for a zero-downtime switch.

Full spec: /openapi.json

## POST /api/v1/keys/{id}/rotate

```json
{
  "tags": [
    "Keys"
  ],
  "summary": "Rotate an API key.",
  "description": "Issues a new secret with the same name, scopes and rate limit. The old key stops working now, or after grace_period_seconds (up to 604800) for a zero-downtime switch.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Key id."
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "grace_period_seconds": {
              "type": "integer",
              "minimum": 0,
              "maximum": 604800,
              "default": 0
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The replacement key, with its secret shown once.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiKeyRotated"
          }
        }
      }
    },
    "400": {
      "description": "A malformed id or grace period.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "The key was already rotated. Rotate its replacement instead.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Rename an API key. (/developers/reference/api/keys/patch-keys-id)

Changes only the name; the secret, scopes and rate limit stay. An unknown key, a revoked key and a key past its grace period answer 404.

Full spec: /openapi.json

## PATCH /api/v1/keys/{id}

```json
{
  "tags": [
    "Keys"
  ],
  "summary": "Rename an API key.",
  "description": "Changes only the name; the secret, scopes and rate limit stay. An unknown key, a revoked key and a key past its grace period answer 404.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Key id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "description": "Trimmed; no control characters."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The renamed key.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ApiKey"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Delete an API key. (/developers/reference/api/keys/delete-keys-id)



Full spec: /openapi.json

## DELETE /api/v1/keys/{id}

```json
{
  "tags": [
    "Keys"
  ],
  "summary": "Delete an API key.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Key id."
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# List webhook endpoints. (/developers/reference/api/webhooks/get-webhooks)

Every endpoint of the workspace, paused ones included, newest first. Needs `manage`, like creating them: receiver URLs often carry credentials.

Full spec: /openapi.json

## GET /api/v1/webhooks

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "List webhook endpoints.",
  "description": "Every endpoint of the workspace, paused ones included, newest first. Needs `manage`, like creating them: receiver URLs often carry credentials.",
  "x-required-scope": "manage",
  "responses": {
    "200": {
      "description": "Endpoints.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WebhookList"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Register a webhook endpoint for the workspace. (/developers/reference/api/webhooks/post-webhooks)

Events are delivered for the workspace’s assets. Each request carries X-Sluby-Event, X-Sluby-Delivery (the same on every retry of one delivery), X-Sluby-Timestamp (Unix seconds, per attempt) and X-Sluby-Signature-V1, the hex HMAC-SHA256 of `<timestamp>.<raw body>` with the endpoint secret; receivers should refuse a timestamp more than five minutes from their clock. X-Sluby-Signature (the HMAC of the body alone) is still sent but deprecated, since it does not bind a time. The body is `{ id, event, timestamp, data }`, where `id` identifies the event across retries. The URL must be http(s) and its host must resolve only to public addresses (or to the operator's WEBHOOK_ALLOWED_NETWORKS); this is checked again before every delivery, redirects are not followed and response bodies are not read or stored. The secret is returned once.

Full spec: /openapi.json

## POST /api/v1/webhooks

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "Register a webhook endpoint for the workspace.",
  "description": "Events are delivered for the workspace’s assets. Each request carries X-Sluby-Event, X-Sluby-Delivery (the same on every retry of one delivery), X-Sluby-Timestamp (Unix seconds, per attempt) and X-Sluby-Signature-V1, the hex HMAC-SHA256 of `<timestamp>.<raw body>` with the endpoint secret; receivers should refuse a timestamp more than five minutes from their clock. X-Sluby-Signature (the HMAC of the body alone) is still sent but deprecated, since it does not bind a time. The body is `{ id, event, timestamp, data }`, where `id` identifies the event across retries. The URL must be http(s) and its host must resolve only to public addresses (or to the operator's WEBHOOK_ALLOWED_NETWORKS); this is checked again before every delivery, redirects are not followed and response bodies are not read or stored. The secret is returned once.",
  "x-required-scope": "manage",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri",
              "maxLength": 2048,
              "description": "Absolute http(s) URL on a public address."
            },
            "events": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "enum": [
                  "upload.started",
                  "upload.completed",
                  "upload.failed",
                  "processing.started",
                  "asset.ready",
                  "asset.errored"
                ]
              }
            }
          },
          "required": [
            "url",
            "events"
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created; includes the signing secret once.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WebhookCreated"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Send a signed `webhook.test` event to the endpoint now. (/developers/reference/api/webhooks/post-webhooks-id-test)

Delivered once, signed like any event, and recorded with the deliveries. Answers how the receiver responded: `delivered`, `status_code` (null when no response came) and `error` (why it failed, in our words).

Full spec: /openapi.json

## POST /api/v1/webhooks/{id}/test

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "Send a signed `webhook.test` event to the endpoint now.",
  "description": "Delivered once, signed like any event, and recorded with the deliveries. Answers how the receiver responded: `delivered`, `status_code` (null when no response came) and `error` (why it failed, in our words).",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Endpoint id."
    }
  ],
  "responses": {
    "200": {
      "description": "The outcome.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "delivered": {
                "type": "boolean"
              },
              "status_code": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "error": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "delivered",
              "status_code",
              "error"
            ]
          }
        }
      }
    },
    "404": {
      "description": "Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# Replace the signing secret of a webhook endpoint. (/developers/reference/api/webhooks/post-webhooks-id-rotate-secret)

For a secret that leaked. The old secret stops at once: every request from now on, retries of earlier events included, is signed with the new one, which is returned only here.

Full spec: /openapi.json

## POST /api/v1/webhooks/{id}/rotate-secret

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "Replace the signing secret of a webhook endpoint.",
  "description": "For a secret that leaked. The old secret stops at once: every request from now on, retries of earlier events included, is signed with the new one, which is returned only here.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Endpoint id."
    }
  ],
  "responses": {
    "200": {
      "description": "The new secret.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "id",
              "secret"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "secret": {
                "type": "string",
                "description": "The new signing secret, shown once."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# The endpoint's latest delivery attempts, newest first. (/developers/reference/api/webhooks/get-webhooks-id-deliveries)

One entry per attempt: id, event_id, event, status_code, delivered, error, attempt (1 for the first try), created_at, the payload that was sent, and manual (true for a resend). Response bodies are never stored. Attempts are kept for 30 days.

Full spec: /openapi.json

## GET /api/v1/webhooks/{id}/deliveries

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "The endpoint's latest delivery attempts, newest first.",
  "description": "One entry per attempt: id, event_id, event, status_code, delivered, error, attempt (1 for the first try), created_at, the payload that was sent, and manual (true for a resend). Response bodies are never stored. Attempts are kept for 30 days.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Endpoint id."
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 50
      },
      "description": "How many attempts to return."
    }
  ],
  "responses": {
    "200": {
      "description": "Attempts.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "event",
                    "status_code",
                    "delivered",
                    "error",
                    "attempt",
                    "created_at",
                    "payload",
                    "manual"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "event_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "event": {
                      "type": "string"
                    },
                    "status_code": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "delivered": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "attempt": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "payload": {
                      "type": "object",
                      "description": "The JSON body that was sent: `{ id, event, timestamp, data }`."
                    },
                    "manual": {
                      "type": "boolean",
                      "description": "True for an attempt of a resend someone asked for."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "description": "Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Send a logged delivery again. (/developers/reference/api/webhooks/post-webhooks-id-deliveries-deliveryid-redeliver)

Queues the stored payload of the delivery again, with the same event `id` so a receiver that already handled it can drop the repeat. It is signed with the current secret, gets a new X-Sluby-Delivery id and the usual retries, and each attempt is logged with `manual: true`. A paused endpoint answers 409.

Full spec: /openapi.json

## POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "Send a logged delivery again.",
  "description": "Queues the stored payload of the delivery again, with the same event `id` so a receiver that already handled it can drop the repeat. It is signed with the current secret, gets a new X-Sluby-Delivery id and the usual retries, and each attempt is logged with `manual: true`. A paused endpoint answers 409.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Endpoint id."
    },
    {
      "name": "deliveryId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "The `id` of an entry in the delivery log."
    }
  ],
  "responses": {
    "202": {
      "description": "Queued.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "delivery_id"
            ],
            "properties": {
              "delivery_id": {
                "type": "string",
                "description": "The X-Sluby-Delivery header the resend carries."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "The endpoint is paused.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Get a webhook endpoint. (/developers/reference/api/webhooks/get-webhooks-id)



Full spec: /openapi.json

## GET /api/v1/webhooks/{id}

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "Get a webhook endpoint.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Endpoint id."
    }
  ],
  "responses": {
    "200": {
      "description": "The endpoint.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Webhook"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Edit, pause or resume a webhook endpoint. (/developers/reference/api/webhooks/patch-webhooks-id)

Send any of `url`, `events` and `is_active`. A new URL is checked like at registration. `is_active: false` pauses the endpoint: nothing is sent to it, and deliveries already queued for it are dropped. `is_active: true` resumes it for new events. The signing secret does not change.

Full spec: /openapi.json

## PATCH /api/v1/webhooks/{id}

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "Edit, pause or resume a webhook endpoint.",
  "description": "Send any of `url`, `events` and `is_active`. A new URL is checked like at registration. `is_active: false` pauses the endpoint: nothing is sent to it, and deliveries already queued for it are dropped. `is_active: true` resumes it for new events. The signing secret does not change.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Endpoint id."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "minProperties": 1,
          "properties": {
            "url": {
              "type": "string",
              "format": "uri",
              "maxLength": 2048,
              "description": "Absolute http(s) URL on a public address."
            },
            "events": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "enum": [
                  "upload.started",
                  "upload.completed",
                  "upload.failed",
                  "processing.started",
                  "asset.ready",
                  "asset.errored"
                ]
              },
              "description": "Replaces the subscribed events. An event listed twice counts once."
            },
            "is_active": {
              "type": "boolean",
              "description": "False pauses, true resumes."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The endpoint as it is now.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Webhook"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Delete a webhook endpoint. (/developers/reference/api/webhooks/delete-webhooks-id)



Full spec: /openapi.json

## DELETE /api/v1/webhooks/{id}

```json
{
  "tags": [
    "Webhooks"
  ],
  "summary": "Delete a webhook endpoint.",
  "x-required-scope": "manage",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Endpoint id."
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input, such as a malformed id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Latest reconciliation run. (/developers/reference/api/reconciliation/get-reconciliation)

Admins get the whole run, orphaned ids included; members get only the missing objects of the workspace’s assets (see ReconciliationRun).

Full spec: /openapi.json

## GET /api/v1/reconciliation

```json
{
  "tags": [
    "Reconciliation"
  ],
  "summary": "Latest reconciliation run.",
  "description": "Admins get the whole run, orphaned ids included; members get only the missing objects of the workspace’s assets (see ReconciliationRun).",
  "x-required-scope": "manage",
  "responses": {
    "200": {
      "description": "Latest run.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReconciliationRun"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "description": "No run has completed yet.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Trigger a reconciliation run. (/developers/reference/api/reconciliation/post-reconciliation-run)

A run scans the whole deployment, so only an admin may start one. It is queued unless one, manual or scheduled, is already waiting or running, so repeated calls never stack runs.

Full spec: /openapi.json

## POST /api/v1/reconciliation/run

```json
{
  "tags": [
    "Reconciliation"
  ],
  "summary": "Trigger a reconciliation run.",
  "description": "A run scans the whole deployment, so only an admin may start one. It is queued unless one, manual or scheduled, is already waiting or running, so repeated calls never stack runs.",
  "x-required-scope": "manage",
  "x-required-identity": "admin",
  "responses": {
    "202": {
      "description": "Queued, or a run was already pending.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReconciliationTrigger"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/TooManyRequests"
    }
  }
}
```

# Stream a Sia object, with byte-range support. (/developers/reference/api/delivery/get-objects-objectid)

An object of a public asset needs nothing. An object of a private asset needs the `expires` and `sig` of a signed url (GET /api/v1/playback/{id}/signed); a manifest served that way has the urls of its children signed with the same expiry. Access follows only the asset tier: a signed playback ID gates its own /v1/stream entry, not these objects. HEAD answers the same headers without a body. A public answer carries `ETag` (the object id) and `Cache-Control: public, no-cache`, and a conditional request (`If-None-Match`) is answered 304 only after access is checked again, so a cache never keeps serving an object after its asset turns private or is deleted; the shipped nginx keeps small public objects for at most 60 seconds between checks. Objects over 8 MB are streamed and never cached.

Full spec: /openapi.json

## GET /v1/objects/{objectId}

```json
{
  "tags": [
    "Delivery"
  ],
  "summary": "Stream a Sia object, with byte-range support.",
  "description": "An object of a public asset needs nothing. An object of a private asset needs the `expires` and `sig` of a signed url (GET /api/v1/playback/{id}/signed); a manifest served that way has the urls of its children signed with the same expiry. Access follows only the asset tier: a signed playback ID gates its own /v1/stream entry, not these objects. HEAD answers the same headers without a body. A public answer carries `ETag` (the object id) and `Cache-Control: public, no-cache`, and a conditional request (`If-None-Match`) is answered 304 only after access is checked again, so a cache never keeps serving an object after its asset turns private or is deleted; the shipped nginx keeps small public objects for at most 60 seconds between checks. Objects over 8 MB are streamed and never cached.",
  "security": [],
  "parameters": [
    {
      "name": "objectId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Sia object ID."
    },
    {
      "name": "type",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "manifest",
          "playlist",
          "thumbnail",
          "poster",
          "video",
          "segment",
          "data"
        ]
      },
      "description": "Content-type hint."
    },
    {
      "name": "expires",
      "in": "query",
      "schema": {
        "type": "integer"
      },
      "description": "Expiry (unix seconds) of a signed url. Required for a private object."
    },
    {
      "name": "sig",
      "in": "query",
      "schema": {
        "type": "string"
      },
      "description": "Signature of a signed url. Required for a private object."
    },
    {
      "name": "Range",
      "in": "header",
      "schema": {
        "type": "string"
      },
      "description": "Byte range, e.g. `bytes=0-1023`."
    }
  ],
  "responses": {
    "200": {
      "description": "Full object."
    },
    "206": {
      "description": "Partial content (range)."
    },
    "304": {
      "description": "Still public and unchanged (a conditional request)."
    },
    "400": {
      "description": "Not a Sia object id (64 lowercase hex characters).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "A private object without a valid, unexpired signature of the asset current signing generation; `reason` says why.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No asset holds the object, its asset is being deleted, or the indexer no longer has it.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "416": {
      "description": "Range not satisfiable."
    },
    "502": {
      "description": "The Sia network did not answer; try again.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "The database did not answer; try again.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# Master HLS manifest for an asset or playback ID. (/developers/reference/api/delivery/get-stream-videoassetid-master-m3u8)

A private asset or a signed-policy playback ID needs the `expires` and `sig` of the asset’s signed master url; the child urls in the answer are then signed too. A signed playback ID gates only this entry: on a public asset its objects stay public, so the bytes are not private (make the asset private for that), and other embeds of the asset keep playing. A public answer carries an ETag and `public, no-cache`, but no shared cache keeps it: each 200 GET counts as a play (see `play_count` on an asset); HEAD and 304 do not.

Full spec: /openapi.json

## GET /v1/stream/{videoAssetId}/master.m3u8

```json
{
  "tags": [
    "Delivery"
  ],
  "summary": "Master HLS manifest for an asset or playback ID.",
  "description": "A private asset or a signed-policy playback ID needs the `expires` and `sig` of the asset’s signed master url; the child urls in the answer are then signed too. A signed playback ID gates only this entry: on a public asset its objects stay public, so the bytes are not private (make the asset private for that), and other embeds of the asset keep playing. A public answer carries an ETag and `public, no-cache`, but no shared cache keeps it: each 200 GET counts as a play (see `play_count` on an asset); HEAD and 304 do not.",
  "security": [],
  "parameters": [
    {
      "name": "videoAssetId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset UUID or pb_ playback ID."
    },
    {
      "name": "expires",
      "in": "query",
      "schema": {
        "type": "integer"
      },
      "description": "Expiry (unix seconds) from the signed master URL. Required when gated."
    },
    {
      "name": "sig",
      "in": "query",
      "schema": {
        "type": "string"
      },
      "description": "Signature from the signed master URL. Required when gated."
    }
  ],
  "responses": {
    "200": {
      "description": "HLS manifest.",
      "content": {
        "application/vnd.apple.mpegurl": {}
      }
    },
    "304": {
      "description": "Still public and unchanged (a conditional request)."
    },
    "403": {
      "description": "Gated, and no valid, unexpired signature; `reason` says why.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "No such asset or playback ID, or the asset is not ready.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "502": {
      "description": "The Sia network did not answer; try again.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "The database did not answer; try again.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# Per-object sia:// share URLs for direct-from-Sia playback, without credentials. (/developers/reference/api/delivery/get-share-id)

Gated like /v1/stream: a public asset by its id or a public playback ID needs nothing. A private asset or a signed-policy playback ID needs the `expires` and `sig` of its signed master URL, and the shares then never outlive `expires`. Expiries are capped like the authenticated route (six hours, one hour when gated) and rounded to five-minute slots that the server caches, so repeated calls do not mint again. Every map is sent `no-store` (`private, no-store` when gated): minting one is how a direct-from-Sia play reaches the server, and each counts as a play (see `play_count` on an asset), unless `renew` is set. Share URLs already handed out keep working until they expire, whatever happens to the asset meanwhile.

Full spec: /openapi.json

## GET /v1/share/{id}

```json
{
  "tags": [
    "Delivery"
  ],
  "summary": "Per-object sia:// share URLs for direct-from-Sia playback, without credentials.",
  "description": "Gated like /v1/stream: a public asset by its id or a public playback ID needs nothing. A private asset or a signed-policy playback ID needs the `expires` and `sig` of its signed master URL, and the shares then never outlive `expires`. Expiries are capped like the authenticated route (six hours, one hour when gated) and rounded to five-minute slots that the server caches, so repeated calls do not mint again. Every map is sent `no-store` (`private, no-store` when gated): minting one is how a direct-from-Sia play reaches the server, and each counts as a play (see `play_count` on an asset), unless `renew` is set. Share URLs already handed out keep working until they expire, whatever happens to the asset meanwhile.",
  "security": [],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Asset UUID or pb_ playback ID."
    },
    {
      "name": "expires",
      "in": "query",
      "schema": {
        "type": "integer"
      },
      "description": "Expiry (unix seconds) from the signed master URL. Required when gated."
    },
    {
      "name": "sig",
      "in": "query",
      "schema": {
        "type": "string"
      },
      "description": "Signature from the signed master URL. Required when gated."
    },
    {
      "name": "expires_in",
      "in": "query",
      "schema": {
        "type": "integer",
        "default": 3600
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Share URL map.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SharePlaybackInfo"
          }
        }
      }
    },
    "403": {
      "description": "Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "502": {
      "description": "Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "The database did not answer; try again.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

# A video's public watch page, for a link or an iframe. (/developers/reference/api/delivery/get-watch-id)

An HTML page that plays the video by asset ID or pb_ playback ID through the gateway. A private video or a signed playback ID needs the `expires` and `sig` of a signed URL, which the page passes on to the stream and the poster. Any site may frame it (`frame-ancestors *`). Query `autoplay=1`, `muted=1` and `loop=1` change how it starts.

Full spec: /openapi.json

## GET /watch/{id}

```json
{
  "tags": [
    "Delivery"
  ],
  "summary": "A video's public watch page, for a link or an iframe.",
  "description": "An HTML page that plays the video by asset ID or pb_ playback ID through the gateway. A private video or a signed playback ID needs the `expires` and `sig` of a signed URL, which the page passes on to the stream and the poster. Any site may frame it (`frame-ancestors *`). Query `autoplay=1`, `muted=1` and `loop=1` change how it starts.",
  "security": [],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Asset ID or pb_ playback ID.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "expires",
      "in": "query",
      "required": false,
      "description": "From a signed URL, for a private video or a signed playback ID.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "sig",
      "in": "query",
      "required": false,
      "description": "From the same signed URL.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The page.",
      "content": {
        "text/html": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "403": {
      "description": "The video needs a signed link, or the link expired.",
      "content": {
        "text/html": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "404": {
      "description": "No such video, or it is not ready.",
      "content": {
        "text/html": {
          "schema": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

# The watch page's player script, hls.js build and stylesheet. (/developers/reference/api/delivery/get-watch-assets-file)



Full spec: /openapi.json

## GET /watch/assets/{file}

```json
{
  "tags": [
    "Delivery"
  ],
  "summary": "The watch page's player script, hls.js build and stylesheet.",
  "security": [],
  "parameters": [
    {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "hls.min.js",
          "watch.js",
          "watch.css"
        ]
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The file."
    },
    "404": {
      "description": "No such file."
    }
  }
}
```