# API reference

Every route, parameter and field, with request and response examples.

## Basics

- **Base URL:** `https://api.cleanscript.ai`. JSON in and out, snake_case, times in seconds.
- **Auth:** `Authorization: Bearer <key>` on every request. Keys are in the [dashboard](https://cleanscript.ai/dashboard/api-keys).
- **Headers on every response:** `X-Request-Id`, `X-Credits-Used`, and `X-Credits-Remaining` once the key is accepted; `Retry-After` on `202`, `409`, `429`, `503` and `504`.
- **Retries:** send an optional `Idempotency-Key` (1 to 128 letters, digits, `.`, `_`, `:` or `-`) on `/v1/transcript` and `/v1/extract`. The same key and request within 6 hours returns the first successful result, free, waiting while it runs; after an error, it runs again.
- **Long posts:** a transcript or extraction still running after 85 seconds answers `504` `processing` naming its [operation](#get-v1operationsid), or `202` with `Prefer: respond-async` or `wait=N` (up to 85). The same request again returns the result once ready, free.
- **Errors:** `{"error": {"code", "message", "param", "details"}, "request_id"}`, `param` and `details` `null` when they don't apply. Codes and what to do: [Credits & limits](https://cleanscript.ai/docs/credits.md#errors).
- **OpenAPI:** [`/openapi.json`](https://cleanscript.ai/openapi.json).

## GET /v1/transcript

A post's words as clean text, paragraphs and sections. `POST /v1/transcript` takes the same parameters as a JSON body. Costs 1 credit per started 10 minutes, or 1 per started minute without captions; see [Credits & limits](https://cleanscript.ai/docs/credits.md).

### Parameters

| Field | Type | Description |
| --- | --- | --- |
| `url` | string, required | A YouTube, TikTok or Instagram post link in any common form, or a bare YouTube video ID. |
| `language` | string | The language to read in, such as `en` or `pt-BR`. Default: the language spoken in the post. Without captions in it, the transcript is translated and labelled. |
| `include` | array of strings | Extra detail: `text` (the whole transcript as one string), `lines` (short timed lines), `on_screen_text` (text shown in the video). In a query, repeat it: `include=text&include=lines`. |

```bash
curl -G https://api.cleanscript.ai/v1/transcript \
  -H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
  --data-urlencode "url=https://youtu.be/jwnez8HdN7E"
```

```python
result = client.transcript("https://youtu.be/jwnez8HdN7E")
```

```typescript
const result = await client.transcript("https://youtu.be/jwnez8HdN7E")
```

```json Response
{
  "post": {
    "platform": "youtube",
    "type": "video",
    "id": "jwnez8HdN7E",
    "url": "https://www.youtube.com/watch?v=jwnez8HdN7E",
    "title": "Microsoft’s new chip looks like science fiction…",
    "description": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm …",
    "author": {
      "name": "Fireship",
      "handle": "@Fireship",
      "url": "https://www.youtube.com/@Fireship"
    },
    "published_at": "2025-02-21",
    "duration": 259,
    "thumbnail_url": "https://i.ytimg.com/vi_webp/jwnez8HdN7E/maxresdefault.webp",
    "sponsored": null,
    "sound": null,
    "stats": {
      "views": 2331993,
      "likes": 71026,
      "comments": 3300,
      "shares": null,
      "saves": null
    }
  },
  "language": "en",
  "source": "auto",
  "text": null,
  "sections": [
    {
      "title": "Microsoft's quantum breakthrough",
      "start": 2.19,
      "end": 58.11,
      "url": "https://youtu.be/jwnez8HdN7E?t=2",
      "paragraphs": [
        {
          "start": 2.19,
          "end": 58.11,
          "text": "Out of nowhere, Microsoft just announced an impossible new quantum computing chip named Majorana 1, but it's not your average quantum chip. They claim to have created an entirely new state of matter. …"
        }
      ]
    }
  ],
  "lines": null,
  "on_screen_text": null,
  "warnings": []
}
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `post` | object | The post. See [the post object](#the-post-object). |
| `language` | string or null | The transcript's language; `null` when there is no speech. |
| `source` | string | `creator`, `auto`, `transcribed`, `translated` or `none`; see [Transcripts](https://cleanscript.ai/docs/transcripts.md#where-the-words-come-from). |
| `text` | string or null | The paragraphs as one string, separated by blank lines; only with `include: ["text"]`. |
| `sections` | array | `{title, start, end, url, paragraphs}`; each paragraph is `{start, end, text}`. `title` is `null` for a short TikTok or Instagram post. |
| `lines` | array or null | `{start, end, text}` lines of up to about 5 seconds; only with `include: ["lines"]`. |
| `on_screen_text` | array or null | `{start, end, slide, text}`. Filled when there is no speech, otherwise with `include: ["on_screen_text"]`. |
| `warnings` | array | `{code, message}`; `code` is `translated`, `no_speech` or `incomplete` (part of the post couldn't be read; retry for all of it). |

## POST /v1/extract

The fields you ask for, each with the quotes that support it. Costs 3 credits per started 10 minutes, the transcript included; see [Extract fields](https://cleanscript.ai/docs/extract.md). Send `prompt`, `preset` or `schema`; a `prompt` can go with either of the other two.

### Body (JSON)

| Field | Type | Description |
| --- | --- | --- |
| `url` | string, required | A YouTube, TikTok or Instagram post link, or a bare YouTube video ID. |
| `prompt` | string | A question or instruction in plain words, up to 4,000 characters. Alone, it returns `{answer, points}`; with a schema or preset it adds guidance. |
| `preset` | string | A published schema: `summary`, `mentions`, `ad-breakdown`, `claims`. |
| `schema` | object | Your own JSON Schema, object at the root, up to 32 KB. |
| `language` | string | The language to write values in. Default: the transcript's. Quotes stay word for word. |
| `include` | array of strings | `transcript`: add the transcript the values come from. |

```bash
curl https://api.cleanscript.ai/v1/extract \
  -H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/jwnez8HdN7E", "preset": "mentions"}'
```

```python
result = client.extract("https://youtu.be/jwnez8HdN7E", preset="mentions")
```

```typescript
const result = await client.extract("https://youtu.be/jwnez8HdN7E", { preset: "mentions" })
```

```json Response
{
  "post": {
    "platform": "youtube",
    "type": "video",
    "id": "jwnez8HdN7E",
    "url": "https://www.youtube.com/watch?v=jwnez8HdN7E",
    "title": "Microsoft’s new chip looks like science fiction…",
    "description": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm …",
    "author": {
      "name": "Fireship",
      "handle": "@Fireship",
      "url": "https://www.youtube.com/@Fireship"
    },
    "published_at": "2025-02-21",
    "duration": 259,
    "thumbnail_url": "https://i.ytimg.com/vi_webp/jwnez8HdN7E/maxresdefault.webp",
    "sponsored": null,
    "sound": null,
    "stats": {
      "views": 2331993,
      "likes": 71026,
      "comments": 3300,
      "shares": null,
      "saves": null
    }
  },
  "data": {
    "mentions": [
      {
        "name": "Microsoft",
        "sentiment": "mixed",
        "type": "company"
      }
    ],
    "recommendations": [],
    "sponsors": [
      {
        "brand": "CodeRabbit",
        "code": "FIRESHIP",
        "link": "https://bit.ly/41rLUxm",
        "offer": "One month free for teams",
        "product": "AI code reviews"
      }
    ]
  },
  "citations": {
    "mentions[0]": [
      {
        "quote": "If it turns out not to be your typical Microsoft BS—and that's a big if—it could be a breakthrough on par with the transistor.",
        "source": "speech",
        "start": 20.5,
        "end": 27.9,
        "url": "https://youtu.be/jwnez8HdN7E?t=20"
      }
    ],
    "sponsors[0]": [
      {
        "quote": "It's 100% free for open source projects, but you can get one month free for your team using the code FIRESHIP with the link below.",
        "source": "speech",
        "start": 249.7,
        "end": 258.6,
        "url": "https://youtu.be/jwnez8HdN7E?t=249"
      },
      {
        "quote": "Sign up for CodeRabbit using FIRESHIP code, and get free CodeRabbit for 1-month https://bit.ly/41rLUxm",
        "source": "description",
        "start": null,
        "end": null,
        "url": null
      }
    ]
  },
  "removed": [],
  "warnings": [],
  "transcript": null
}
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `post` | object | The post. |
| `data` | object | Your fields, matching the schema. Any value may be `null` when the post doesn't support it. |
| `citations` | object | Quotes for each value by path (`offer`, `sponsors[0]`): `{quote, source, start, end, url}`, `source` being `speech`, `title`, `description` or `on_screen`. |
| `removed` | array of strings | Paths of values dropped because no quote in the post supports them. |
| `warnings` | array | `{code, message}`: `no_speech` or `incomplete`. |
| `transcript` | object or null | The transcript the values come from, as `/v1/transcript` returns it with `text` and `lines` set to `null` (the text is in `sections`); only with `include: ["transcript"]`. |

## GET /v1/posts

A creator's recent posts, newest first. Costs 1 credit; see [Creator posts](https://cleanscript.ai/docs/posts.md).

### Parameters

| Field | Type | Description |
| --- | --- | --- |
| `author` | string, required | A profile or channel link in any form, or a handle such as `@Fireship` with `platform`. |
| `platform` | string | `youtube`, `tiktok` or `instagram`; needed only when `author` is a handle. |
| `limit` | integer | How many posts: by default 12, or all of them since `since`. At most 30 on YouTube, 35 on TikTok, 12 on Instagram. |
| `since` | string | Only posts published on or after this date, `YYYY-MM-DD`. |

```bash
curl -G https://api.cleanscript.ai/v1/posts \
  -H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
  --data-urlencode "author=https://www.youtube.com/@Fireship"
```

```python
listing = client.posts("https://www.youtube.com/@Fireship")
```

```typescript
const listing = await client.posts("https://www.youtube.com/@Fireship")
```

```json Response
{
  "author": {
    "platform": "youtube",
    "name": "Fireship",
    "handle": "@Fireship",
    "url": "https://www.youtube.com/@Fireship",
    "followers": 4290000
  },
  "posts": [
    {
      "platform": "youtube",
      "type": "video",
      "id": "_5p1_TNSWqQ",
      "url": "https://www.youtube.com/watch?v=_5p1_TNSWqQ",
      "title": "PewDiePie is setting AI free... and OpenAI is furious",
      "description": null,
      "author": {
        "name": "Fireship",
        "handle": "@Fireship",
        "url": "https://www.youtube.com/@Fireship"
      },
      "published_at": "2026-10-05",
      "duration": 346,
      "thumbnail_url": "https://i.ytimg.com/vi/_5p1_TNSWqQ/hq720_custom_2.jpg?sqp=CMjykdYG-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBewv6zstbI10M8d0myK-Ia1GS9sQ",
      "sponsored": null,
      "sound": null,
      "stats": {
        "views": 489000,
        "likes": null,
        "comments": null,
        "shares": null,
        "saves": null
      }
    }
  ]
}
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `author` | object | `{platform, name, handle, url, followers}`; `followers` is `null` when the platform doesn't show it. |
| `posts` | array | [Post objects](#the-post-object), newest first. |

## GET /v1/account

Your balance and rate limit. Free.

```bash
curl https://api.cleanscript.ai/v1/account \
  -H "Authorization: Bearer $CLEANSCRIPT_API_KEY"
```

```python
account = client.account()
```

```typescript
const account = await client.account()
```

```json Response
{
  "email": "you@example.com",
  "credits_remaining": 940,
  "rate_limit_per_minute": 10
}
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `email` | string or null | The account's email. |
| `credits_remaining` | integer | Credits left. |
| `rate_limit_per_minute` | integer | Requests a minute this account may send. |

## GET /v1/operations/{id}

A transcript or extraction that outlived its request. Free. `status` is `running` (read again after `Retry-After`), `succeeded` with `result`, or `failed` with `error`. Kept 6 hours.

## The post object

The same object in every response and in every item of a post list. Every field is always present; unknown values are `null`, never `0`.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | string | `youtube`, `tiktok` or `instagram`. |
| `type` | string | `video`, `photo` or `carousel`. |
| `id` | string | The platform's ID for the post. |
| `url` | string | Link to the post. |
| `title` | string or null | The YouTube title; `null` on TikTok and Instagram. |
| `description` | string or null | The post's own text: the YouTube description, or the TikTok or Instagram caption. |
| `author` | object | `{name, handle, url}`. |
| `published_at` | string or null | Publication date, `YYYY-MM-DD`. |
| `duration` | number or null | Length in seconds; `null` for photos. |
| `thumbnail_url` | string or null | The YouTube thumbnail; `null` on TikTok and Instagram, whose image links expire. |
| `sponsored` | boolean or null | The platform's paid-partnership or ad flag. |
| `sound` | object or null | TikTok and Instagram audio: `{title, author, original}`, where `original` is true for the creator's own audio. `null` on YouTube. |
| `stats` | object | `{views, likes, comments, shares, saves}` as the platform shows them. On Instagram, views come only in `/v1/posts` listings, for Reels; a single post's are `null`. |
