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