Overview and auth
Base URL, the two credential shapes, and what a key can never do.
The HTTP surface lives under https://vos.so/api. It is the same contract
the vos CLI speaks; anything the CLI can do to hosted content, you can do
with plain requests.
Auth
Bearer tokens, two shapes:
Authorization: Bearer vos_sk_... a durable content key (vos.so/app/api)
Authorization: Bearer vos_rg_... an ephemeral remix grant (24h, one source vos)Public reads need no auth at all: a public vos's metadata, config and
compiled output are open, which is what makes the gallery remixable by
anyone's agent. The full credential ladder, including vos login and the
credential-free claimable push, is in
Credentials.
What a key can never do
The clamps are the contract's spine, worth knowing before you design around it:
- Publish.
visibility: "public"is clamped or rejected on every key-authed write; publishing stays a human act on vos.so. - Reshape the shelf. Folder rename, move, delete and reorder are
session-only. Keys read folders, create them, and file work into them
(
POST /folders,folderIdon vos and asset PATCH): add-only, never reshaping what the human made. An asset is work, not shelf structure, so keys may rename their owner's assets in place (filenameon the asset PATCH; the extension keeps matching the asset's kind). - Mint credentials. No endpoint issues a key to a key.
Durable-key creates are quota'd (50 per 24 hours), version pushes at 200 per 24 hours across every vos, grant pushes at 5 per grant, claimable pushes at 5 per day per network. The rest of the free plan's numbers are under Limits.
Errors you will actually see
| Status | Meaning |
|---|---|
400 | Invalid input, or the config failed to compile; the body carries the compile error |
401 | Invalid or revoked key |
403 | Missing scope, or an act a key can never do (publish, official status) |
409 stale_base | The head moved; the body carries the changelog. Follow the ritual |
409 protected_conflict | A human touched those nodes; keep their values unless the user asked |
409 (storage, folders) | The account's 5 GB of assets is full ("Delete a recording to make room"), or a folder holds its 500 items or 50 subfolders. Delete or move; retrying changes nothing |
410 | A file that was taken down (kind: removed). The body's reason says why. It cannot be stored again; do not retry |
413 | A file over its kind's cap: a recording over 30 minutes or 1.5 GB, a picture declaring more than 64 megapixels. The body's kind says which (size, duration, bomb). Trim or scale it, or keep it local with vos render |
415 | A file vosso has no use for, or a name on contents that are something else (kind: type), or a container with nothing playable in it (kind: codec) |
429 | A quota (daily creates, version pushes, upload caps, claim limits). The body names the number and the window; a hint names the way out |
Limits
Every account is on the free plan; there is no paid one. The numbers come
from one table, so a refusal always prints the same figure the settings page
shows. GET /user/usage (session only) returns { plan, usage, limits }.
| Limit | Free |
|---|---|
| Recording length | 30 minutes. The recorders say so before a take and stop there. The server measures what it stores, so a longer clip is refused with 413 whatever it was declared as |
| Single recording | 1.5 GB. Every upload is sent in parts (POST /assets/uploads, one PUT per part, then /complete): a single request body is capped at 100 MiB by the edge, well below any real screen recording |
| Storage | 5 GB of assets per account (recordings and uploaded files; versions never count). A write past it is 409. Nothing already saved is ever deleted |
| Uploads | Each kind of file has its own size cap and daily rate: 20 recordings, 40 sounds, 100 pictures, 40 SVGs, 20 models, 20 fonts, 10 HDR maps per 24 hours, session or content key. GET /limits serves the table (limits.uploadKinds) and the formats each kind takes (kinds). Sending the same bytes again (sha256) never counts |
| Creates | 50 per 24 hours per key |
| Claimable pushes | No credential: 5 claims and 5 upload sessions per 24 hours per network. A claim carries at most 12 files and 50 MB, sound up to 5 minutes, video up to 60 seconds, pictures, SVG, video, sound, models, fonts and HDR only |
| Versions | Sessions: 100 per vos per 24 hours. Keys: 200 pushes per 24 hours across every vos (429; iterate locally with vos render and vos frames, push when a round is done) |
| Folders | 50 per account, 5 levels deep, 50 subfolders and 500 items (voses, assets, recipes) per folder (409) |
| Previews and thumbnails | Free and unmetered, rate-limited to 20 per vos per hour and 300 per account per day. Past the rate the version still lands and its media renders on the next watchdog pass, within about 20 minutes. Never refused |
| Cleanup | An uploaded recording attached to no vos and filed in no folder is deleted after 7 days; that is the only deletion. The render cache is swept at 30 days. Saved content never expires |
Related
- Voses and versions for the content endpoints.
- The agent contract for the rules above the wire.