API¶
asciinema server provides an HTTP API for interacting with the server programmatically.
The latest version of the API is v1, and is available at /api/v1/
.
Authentication¶
All API endpoints require authentication using HTTP Basic
Authentication
with your CLI install ID. The install ID uniquely identifies your CLI, and is
generated in ~/.config/asciinema/install-id
when running asciinema auth
for
the first time on a given system.
Most endpoints require the CLI to be registered with the server by completing
the steps displayed by the asciinema auth
command.
The exception is the upload endpoint (POST /api/v1/recordings
). Unless the
server uses UPLOAD_AUTH_REQUIRED=1
configuration
option, this endpoint allows
requests from unregistered CLIs. In such cases, created recordings are
temporary and subject to automatic removal, unless the asciinema auth
flow is
completed on the same system within server-configured grace
period.
See asciinema auth documentation for more
details.
Note
The above is rather CLI-centric, and that's because the API evolved to support the needs of the asciinema CLI over the years. In the future, the server will provide other authentication methods, such as pre-authorized access tokens or OAuth2, to make the API easier to use in non-interactive contexts.
Authentication header¶
Use the install ID as the password field in Basic Authentication. The username field can be an empty string.
Authorization: Basic <base64(:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)>
For brevity, this header is omitted in request examples of endpoint descriptions.
Example request using cURL¶
INSTALL_ID=$(cat ~/.config/asciinema/install-id)
curl -X PATCH \
-u ":${INSTALL_ID}" \
-H "Content-Type: application/json" \
-d '{"title":"Updated Title","visibility":"public"}' \
https://asciinema.org/api/v1/recordings/123
Request and response format¶
Most API endpoints expect request bodies to be JSON encoded (Content-Type:
application/json
). Exceptions to this are noted in endpoint descriptions.
The only supported response format is also JSON, and requests must include
either Accept: application/json
or Accept: */*
header.
Successful responses (2xx status) return resource attributes directly (no
envelopes). Error responses (4xx status) typically return error details in the
error
field.
Errors¶
Common HTTP status codes used by the API for error cases:
Status Code | Description |
---|---|
401 | Unauthorized - Missing or invalid auth header |
403 | Forbidden - Access denied (e.g., streaming disabled) |
404 | Not Found - Resource not found |
422 | Unprocessable Entity - Validation errors |
Resources¶
Recordings¶
Recording
resources represent terminal session recordings.
Recording attributes:
Attribute | Type | Description | Modifiable |
---|---|---|---|
id |
Integer | Recording ID | No |
url |
String (URL) | Web URL | No |
file_url |
String (URL) | asciicast file URL | No |
audio_url |
String (URL) | Audio file URL, e.g., mp3 | Yes |
title |
String | A title | Yes |
description |
String (Markdown) | A description | Yes |
visibility |
Enum: public , unlisted , private |
Visibility | Yes |
Note
The :id
path parameter in recording endpoints accepts either a recording's
numerical ID (id
in the table above) or a URL token.
A URL token is a unique token assigned to unlisted and private recordings,
and used in place of the numerical ID in web URLs of those recordings. For
example, for a recording with the web URL
https://asciinema.org/a/iUagQ1fL8tBvSZYiQGfPFCWIP
the URL token is
iUagQ1fL8tBvSZYiQGfPFCWIP
.
POST /api/v1/recordings¶
Create a new recording from an asciicast file.
Note
In contrast to other endpoints, this one expects the request body to be
encoded as multipart/form-data
.
The only required attribute is file
.
Request:
POST /api/v1/recordings HTTP/1.1
Content-Type: multipart/form-data; boundary=----FormBoundary123
Accept: application/json
------FormBoundary123
Content-Disposition: form-data; name="file"; filename="demo.cast"
Content-Type: application/octet-stream
[recording file content]
------FormBoundary123--
Response:
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://asciinema.org/a/eST2byL7IZkbGOBaMqE4Jhrqp
{
"id": 123,
"url": "https://asciinema.org/a/eST2byL7IZkbGOBaMqE4Jhrqp",
"file_url": "https://asciinema.org/a/eST2byL7IZkbGOBaMqE4Jhrqp.cast",
"audio_url": null,
"title": null,
"description": null,
"visibility": "unlisted"
}
cURL example:
INSTALL_ID=$(cat ~/.config/asciinema/install-id)
curl -X POST \
-u ":${INSTALL_ID}" \
-F "file=@demo.cast" \
https://asciinema.org/api/v1/recordings
PATCH /api/v1/recordings/:id¶
Update metadata and settings for an existing recording.
Request:
PATCH /api/v1/recordings/123 HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"title": "Updated Recording Title",
"description": "Updated description",
"visibility": "public"
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 123,
"url": "https://asciinema.org/a/eST2byL7IZkbGOBaMqE4Jhrqp",
"file_url": "https://asciinema.org/a/eST2byL7IZkbGOBaMqE4Jhrqp.cast",
"audio_url": null,
"title": "Updated Recording Title",
"description": "Updated description",
"visibility": "public"
}
cURL example:
INSTALL_ID=$(cat ~/.config/asciinema/install-id)
curl -X PATCH \
-u ":${INSTALL_ID}" \
-H "Content-Type: application/json" \
-d '{"title":"Updated Title","visibility":"public"}' \
https://asciinema.org/api/v1/recordings/123
DELETE /api/v1/recordings/:id¶
Permanently delete a recording.
Request:
DELETE /api/v1/recordings/123 HTTP/1.1
Accept: application/json
Response:
HTTP/1.1 204 No Content
cURL example:
INSTALL_ID=$(cat ~/.config/asciinema/install-id)
curl -X DELETE -u ":${INSTALL_ID}" https://asciinema.org/api/v1/recordings/123
Streams¶
Stream
resources represent endpoint configurations for live terminal session broadcasts.
Stream attributes:
Attribute | Type | Description | Modifiable |
---|---|---|---|
id |
Integer | Stream ID | No |
url |
String (URL) | Web URL | No |
ws_producer_url |
String (URL) | Producer WebSocket endpoint | No |
audio_url |
String (URL) | Audio URL, e.g., Icecast stream endpoint | Yes |
title |
String | A title | Yes |
description |
String (Markdown) | A description | Yes |
visibility |
Enum: public , unlisted , private |
Visibility | Yes |
Note
The :id
path parameter in stream endpoints accepts either a stream's
numerical ID (id
in the table above) or a URL token.
A URL token is a unique token assigned to unlisted and private streams, and
used in place of the numerical ID in web URLs of those streams. For example, for a
stream with the web URL https://asciinema.org/s/iUagQ1fL8tBvSZYi
the URL token
is iUagQ1fL8tBvSZYi
.
POST /api/v1/streams¶
Create a new live stream endpoint.
This doesn't start the broadcast automatically. A live stream can be started by
connecting to the producer WebSocket endpoint (ws_producer_url
) and feeding
session events into it.
This endpoint doesn't require any attributes, but some may be provided.
Request:
POST /api/v1/streams HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"title": "Stream Title",
"visibility": "public"
}
Response:
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://asciinema.org/s/En81VpLKVaA7U2NR
{
"id": 123,
"url": "https://asciinema.org/s/En81VpLKVaA7U2NR",
"ws_producer_url": "wss://asciinema.org/ws/S/9pJm0ppDDtuyBHWQ",
"audio_url": null,
"title": "Stream Title",
"description": null,
"visibility": "public"
}
cURL example:
INSTALL_ID=$(cat ~/.config/asciinema/install-id)
curl -X POST \
-u ":${INSTALL_ID}" \
-H "Content-Type: application/json" \
-d '{}' \
https://asciinema.org/api/v1/streams
PATCH /api/v1/streams/:id¶
Update metadata and settings for an existing stream.
Request:
PATCH /api/v1/streams/123 HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"title": "Updated Stream Title",
"description": "Updated stream description",
}
Response:
{
"id": 123,
"url": "https://asciinema.org/s/En81VpLKVaA7U2NR",
"ws_producer_url": "wss://asciinema.org/ws/S/9pJm0ppDDtuyBHWQ",
"audio_url": null,
"title": "Updated Stream Title",
"description": "Updated stream description",
"visibility": "unlisted"
}
cURL example:
INSTALL_ID=$(cat ~/.config/asciinema/install-id)
curl -X PATCH \
-u ":${INSTALL_ID}" \
-H "Content-Type: application/json" \
-d '{"title":"Updated Stream Title","visibility":"public"}' \
https://asciinema.org/api/v1/streams/123
DELETE /api/v1/streams/:id¶
Permanently delete a stream.
Request:
DELETE /api/v1/streams/123 HTTP/1.1
Accept: application/json
Response:
HTTP/1.1 204 No Content
cURL example:
INSTALL_ID=$(cat ~/.config/asciinema/install-id)
curl -X DELETE -u ":${INSTALL_ID}" https://asciinema.org/api/v1/streams/123