asciinema Server API
Agent-ready OpenAPI document · curated by JenticDeveloper ToolsMonitoring Observabilitybasic7 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Upload, update, and delete terminal session recordings and live streams on an asciinema server.
Use for: I need to upload a terminal session recording from CI, Update the title of an existing asciinema recording, Delete an old terminal recording from my asciinema account, Create a new live terminal stream for a demo
Not supported: Does not handle screen video, webcam capture, or audio recording - use for terminal session recordings and live terminal streams only.
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.
Install Jentic One Beta
Connect the asciinema Server API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the asciinema Server API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fasciinema.org%2Fasciinema" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fasciinema.org%2Fasciinema" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with asciinema Server API.
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
Patterns agents use asciinema Server API for, with concrete tasks.
★ 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.
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.
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.
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.
Through Jentic, upload the latest .cast file from the demo session and set its description to a summary generated from the transcript
Key Endpoints
7 endpoints — jentic publishes the only available openapi specification for asciinema server api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using asciinema Server API through Jentic.
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.
GET STARTED