Docs
API reference

Recordings

Download spec

List recordings

GET
/recordings

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from Settings → Developers → API keys.

Query Parameters

type?string
Value in"clip""memo"
q?string
Length0 <= length <= 200
deviceId?string
Match^[A-Za-z0-9][A-Za-z0-9._:-]*$
Length1 <= length <= 256
status?string
Value in"pending""transcribing""ready""no_speech""failed"
from?integer
Range0 <= value <= 9007199254740991
to?integer
Range0 <= value <= 9007199254740991
cursor?string
Length0 <= length <= 1024
limit?integer
Range1 <= value <= 100

Response Body

Success. Writes without read permission return an ID and revision only.

application/json
  1. response
recordings*array<>
nextCursor*string|null
Example Request
curl -X GET 'https://app.italic.com/api/v2/recordings'
Example Response
{
  "recordings": [
    {
      "id": "string",
      "type": "clip",
      "title": "string",
      "transcript": "string",
      "summary": "string",
      "recordedAt": 0,
      "updatedAt": 0,
      "revision": 0,
      "status": "pending",
      "pinned": true,
      "audio": [
        {
          "clientId": "string",
          "fileId": "string"
        }
      ],
      "deviceId": "string",
      "externalId": "string"
    }
  ],
  "nextCursor": "string"
}

Create a recording

POST
/recordings

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from Settings → Developers → API keys.

Header Parameters

Idempotency-Key*string

Reuse the same key and body when retrying a create request.

Length1 <= length <= 128

Request Body

application/json
  1. body
type*string
Value in"clip""memo"
title?string
Length0 <= length <= 200
transcript?string
Length0 <= length <= 1000000
summary?string
Length0 <= length <= 1000000
recordedAt?integer
Range0 <= value <= 9007199254740991
externalId?string
Match^[A-Za-z0-9][A-Za-z0-9._:-]*$
Length1 <= length <= 256
audio?array<>
Itemsitems <= 20
deviceId?string

A custom device of the account (POST /devices) that made the recording. The apps then show its name on the recording, as they do for a device Italic connects to. Omit it for a recording that came from no device.

Match^[A-Za-z0-9][A-Za-z0-9._:-]*$
Length1 <= length <= 256

Response Body

Success. Writes without read permission return an ID and revision only.

application/json
  1. response
recording*|
replayed?boolean
Example Request
curl -X POST 'https://app.italic.com/api/v2/recordings' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "clip"
}'
Example Response
{
  "recording": {
    "id": "string",
    "type": "clip",
    "title": "string",
    "transcript": "string",
    "summary": "string",
    "recordedAt": 0,
    "updatedAt": 0,
    "revision": 0,
    "status": "pending",
    "pinned": true,
    "audio": [
      {
        "clientId": "string",
        "fileId": "string"
      }
    ],
    "deviceId": "string",
    "externalId": "string"
  },
  "replayed": true
}

Get a recording

GET
/recordings/{id}

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from Settings → Developers → API keys.

Path Parameters

id*string
Match^[A-Za-z0-9][A-Za-z0-9._:-]*$
Length1 <= length <= 256

Response Body

Success. Writes without read permission return an ID and revision only.

application/json
  1. response
recording*|
replayed?boolean
Example Request
curl -X GET 'https://app.italic.com/api/v2/recordings/string'
Example Response
{
  "recording": {
    "id": "string",
    "type": "clip",
    "title": "string",
    "transcript": "string",
    "summary": "string",
    "recordedAt": 0,
    "updatedAt": 0,
    "revision": 0,
    "status": "pending",
    "pinned": true,
    "audio": [
      {
        "clientId": "string",
        "fileId": "string"
      }
    ],
    "deviceId": "string",
    "externalId": "string"
  },
  "replayed": true
}

Edit a recording

PATCH
/recordings/{id}

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from Settings → Developers → API keys.

Path Parameters

id*string
Match^[A-Za-z0-9][A-Za-z0-9._:-]*$
Length1 <= length <= 256

Header Parameters

If-Match*string

ETag from the last GET response. Prevents overwriting a newer edit.

Length0 <= length <= 100

Request Body

application/json
  1. body
title?string
Length0 <= length <= 200
transcript?string
Length0 <= length <= 1000000
summary?string
Length0 <= length <= 1000000
pinned?boolean

Response Body

Success. Writes without read permission return an ID and revision only.

application/json
  1. response
recording*|
replayed?boolean
Example Request
curl -X PATCH 'https://app.italic.com/api/v2/recordings/string' \
  -H 'If-Match: string' \
  -H 'Content-Type: application/json' \
  -d '{}'
Example Response
{
  "recording": {
    "id": "string",
    "type": "clip",
    "title": "string",
    "transcript": "string",
    "summary": "string",
    "recordedAt": 0,
    "updatedAt": 0,
    "revision": 0,
    "status": "pending",
    "pinned": true,
    "audio": [
      {
        "clientId": "string",
        "fileId": "string"
      }
    ],
    "deviceId": "string",
    "externalId": "string"
  },
  "replayed": true
}

Delete a recording

DELETE
/recordings/{id}

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from Settings → Developers → API keys.

Path Parameters

id*string
Match^[A-Za-z0-9][A-Za-z0-9._:-]*$
Length1 <= length <= 256

Header Parameters

If-Match*string

ETag from the last GET response. Prevents overwriting a newer edit.

Length0 <= length <= 100

Response Body

Success. Writes without read permission return an ID and revision only.

application/json
  1. response
id*string
Match^[A-Za-z0-9][A-Za-z0-9._:-]*$
Length1 <= length <= 256
deleted*boolean
Example Request
curl -X DELETE 'https://app.italic.com/api/v2/recordings/string' \
  -H 'If-Match: string'
Example Response
{
  "id": "string",
  "deleted": true
}

Italic MCP

Use Italic in ChatGPT, Claude, Codex, Cursor, or another MCP client.

Devices

Next Page