# Soapbox

> Live audio rooms you can drop into your own app. Deliberately scarce and
> ephemeral: ten live casts per account and fifty people per room by default,
> four hours maximum, and nothing is ever recorded. The two caps are set by the
> operator, so read the numbers a response gives you rather than these.

Soapbox is an API for hosting live audio conversations. You create a cast, mint
join tokens for your own users, and they talk. When a cast ends, its audio,
chat and polls are deleted. There is no archive to fetch, no transcript
endpoint, and no recording flag: those absences are the product, not gaps.

## Read this before writing code

- The API key is a **server** credential. Your server calls Soapbox and mints a
  join token; the token goes to your client. A live key sent from a browser is
  rejected as compromised.
- **Test keys create real rooms and are never billed.** Build against
  `sk_test_...`. Iterating costs nothing, so there is no reason to be careful
  with calls while you work.
- Minutes are **participant-minutes**. One person for one minute is one. A fifty
  person room for an hour is three thousand.
- `endsAt` is absolute. Count down to it, never from four hours, or a client
  that slept will show time that does not exist.
- Errors carry a stable `code` and often a `fix`. Branch on `code`, show
  `message`, follow `fix`.

## Docs

- [OpenAPI contract](https://soapbox.3sb.io/openapi.yaml): every endpoint, shape and error code
- [Full reference](https://soapbox.3sb.io/llms-full.txt): the whole surface in one file
- [Developer portal](https://soapbox.3sb.io/developers): keys, usage, billing

## Endpoints

- `POST /v1/casts`: start a cast
- `GET /v1/casts`: list your live casts
- `GET /v1/casts/{id}`: inspect one
- `DELETE /v1/casts/{id}`: end one, deleting everything in it
- `POST /v1/casts/{id}/tokens`: mint a join token for one of your users
- `GET /v1/usage`: balance and recent usage