Skip to content

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