canonical: https://jentic.com/apis/asciinema.org/asciinema

# asciinema Server API

Jentic publishes the only available OpenAPI specification for asciinema Server API, keeping it validated and agent-ready. asciinema is the open-source terminal session recorder and player, and the Server API exposes 7 endpoints for managing recordings and live streams on asciinema.org or a self-hosted instance. The spec covers create, update, and delete operations on recordings and streams, plus listing of a user's streams, secured with HTTP basic authentication.

## For AI agents

Upload, update, and delete terminal session recordings and live streams on an asciinema server.

## Scope

Does not handle screen video, webcam capture, or audio recording - use for terminal session recordings and live terminal streams only.

## Capabilities

- Upload a new terminal session recording to an asciinema server
- Update title and description metadata on an existing recording
- Delete recordings the authenticated user owns
- Create a new live terminal stream for real-time sharing
- Update metadata on an existing live stream
- Delete a live stream when the broadcast ends
- List all streams owned by the authenticated user

## Use cases

### CI Terminal Recording Capture

Capture interesting CI runs as terminal recordings and upload them to asciinema for later debugging or sharing. The POST `/api/v1/recordings` endpoint accepts the .cast file produced by the asciinema CLI, returning the public URL. Reduces the friction of sharing reproducible terminal output between engineers compared to copying scrollback.

Example prompt: Upload the recording.cast file produced by the deploy job to asciinema, set the title to 'Production deploy 2026-06-09', and return the recording URL

### Live Demo Streaming

Spin up an asciinema live stream for a developer demo or pair-programming session, so remote viewers can watch the terminal in real time. The POST `/api/v1/streams` endpoint creates the stream, and PATCH/DELETE manage its lifecycle. Suitable for distributed teams running interactive walkthroughs.

Example prompt: Create a new asciinema stream titled 'Pair debug session', return the stream URL and broadcast token, then list all current streams to confirm

### Recording Library Cleanup

Audit and prune a backlog of old asciinema recordings using PATCH for metadata fixes and DELETE for removal. Useful for self-hosted asciinema instances where storage and discoverability matter. Agents can reconcile the user's stream list against an external catalogue.

Example prompt: List the authenticated user's streams and delete any whose titles contain 'test-' to clean up draft broadcasts

### AI Agent for Terminal Knowledge Capture

An agent integrated through Jentic can listen for shell session events, automatically upload notable recordings to asciinema, and update titles based on what was demonstrated. Jentic stores the asciinema basic-auth credentials in its vault so the agent never sees the raw username and password.

Example prompt: Through Jentic, upload the latest .cast file from the demo session and set its description to a summary generated from the transcript

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/recordings` | Create a new recording |
| PATCH | `/api/v1/recordings/{id}` | Update recording metadata |
| DELETE | `/api/v1/recordings/{id}` | Delete a recording |
| POST | `/api/v1/streams` | Create a new live stream |
| PATCH | `/api/v1/streams/{id}` | Update stream metadata |
| DELETE | `/api/v1/streams/{id}` | Delete a stream |
| GET | `/api/v1/user/streams` | List user streams |

## Key resources

- **Recordings** — Upload, update, and delete terminal session recordings
- **Streams** — Create, update, delete, and list live terminal streams

## Why Jentic

- **Setup:** Wiring asciinema by hand means encoding its basic auth from an install ID and API token for every recording and stream call. Through Jentic you install once, import the asciinema Server API from the API Directory, store the credentials once, and your agent calls it while Jentic builds the Authorization header.
- **Permission scoping:** asciinema puts the recording and stream id in the URL path (`/api/v1/recordings/{id}`), so a rule can pin your agent to updates for one recording. You choose the operations it may call, so deletion is not included unless you add it.
- **Credential handling:** Your asciinema install ID and API token are stored once, encrypted, by your own Jentic One instance and used to build the basic-auth header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload a terminal recording', and Jentic returns the matching asciinema operation with its input schema so the agent calls POST `/api/v1/recordings` without reading the reference docs.

## Related APIs

- **Loom** — Loom captures full-screen video walkthroughs rather than terminal-only sessions, with a richer sharing UI.
- **GitHub API** — GitHub hosts source code; asciinema recordings often supplement README walkthroughs and PR demos.
- **Vimeo** — Vimeo hosts general video content; asciinema is purpose-built for lightweight terminal recordings.

## FAQ

### Why is there no official OpenAPI spec for asciinema Server API?

asciinema does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call asciinema Server API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the asciinema Server API use?

The API uses HTTP basic authentication. The username is your asciinema install ID and the password is the API token shown in the asciinema CLI 'auth' command output. Jentic stores both as a single basic-auth credential in its vault and injects them at execution time.

### Can I upload a terminal recording through the asciinema API?

Yes. POST `/api/v1/recordings` accepts a multipart upload of a .cast file produced by the asciinema CLI. The response returns the public URL of the recording on the server.

### Does the asciinema API support live streaming?

Yes. POST `/api/v1/streams` creates a new live stream, PATCH `/api/v1/streams/{id}` updates its metadata, and DELETE `/api/v1/streams/{id}` removes it. GET `/api/v1/user/streams` returns all streams owned by the authenticated user.

### What are the rate limits for the asciinema Server API?

The OpenAPI specification does not document explicit rate limits. asciinema.org is community-operated, so be conservative - implement backoff on HTTP 429 and avoid bulk uploads. For heavy use, run a self-hosted asciinema server.

### How do I upload a recording through Jentic?

Search Jentic for 'upload an asciinema terminal recording' - POST `/api/v1/recordings` will be returned. Load the operation schema, supply the .cast file, and execute. Jentic handles basic-auth credentials and returns the recording URL.

### Can I limit what my agent is allowed to do with the asciinema Server API?

Yes. Because you run Jentic One yourself, your own rules decide which asciinema operations the agent may call, so you can allow POST `/api/v1/recordings` for uploads while withholding DELETE `/api/v1/recordings/{id}` and DELETE `/api/v1/streams/{id}.` Since asciinema puts the recording or stream id in the URL path, a rule can pin the agent to updating a single recording or stream rather than any of them. The credentials you store are only ever applied to the operations you have permitted, so the agent cannot reach anything you have not scoped in.