# REST API overview

> Base URL, request and response format, versioning and the full list of Clipbeat REST endpoints.

Source: https://docs.clipbeat.app/api/

The Clipbeat REST API is a small JSON over HTTPS API. It is described by an OpenAPI 3.1 document that tools such as
n8n, Postman, Insomnia, ChatGPT actions and code generators can import:

```text
https://api.clipbeat.app/v1/openapi.json
```

The [API reference](https://docs.clipbeat.app/api/reference/) on this site is generated from that document at every build.

## Base URL

```text
https://api.clipbeat.app
```

All endpoints are under `/v1`. HTTPS only.

## Endpoints

| Method | Path | Scope | What it does |
| --- | --- | --- | --- |
| `POST` | `/v1/songs` | `songs:write` | Import a song from a link. |
| `GET` | `/v1/songs/{id}` | `videos:read` | Song status. Wait for `ready` before starting a video. |
| `POST` | `/v1/videos` | `videos:write` | Start a video. Credits are reserved. |
| `GET` | `/v1/videos/{id}` | `videos:read` | Status, progress, cost and the download link when done. |
| `GET` | `/v1/videos` | `videos:read` | The account's latest videos (`limit` 1 to 50, default 20). |
| `GET` | `/v1/pricing` | `account:read` | Price per tier. Add `song_id` for the price of a specific song. |
| `GET` | `/v1/balance` | `account:read` | Credit balance and the link to add credits. |
| `GET` | `/v1/openapi.json` | none | The OpenAPI document. No key needed. |

## Requests

- Authenticate every request with `Authorization: Bearer cb_live_...`. See [Authentication](https://docs.clipbeat.app/authentication/).
- Send bodies as JSON with `Content-Type: application/json`. The body must be a JSON object; anything else returns
  `400 invalid_body`.
- Unknown body fields are ignored.
- Text fields are trimmed, control characters are removed and long values are cut to the documented maximum.

## Responses

- Always JSON, with `Cache-Control: no-store`.
- Field names are `snake_case`. Ids are UUIDs. Timestamps are ISO 8601 strings in UTC.
- Success codes: `200 OK`, `201 Created` (new song), `202 Accepted` (video started).
- Errors share one shape, see [Errors](https://docs.clipbeat.app/errors/):

```json
{ "error": "insufficient_credits", "message": "Not enough credits. Ask the account owner to add credits in Clipbeat Studio, then retry." }
```

Branch on `error` (a stable machine code), show `message` to people.

## Versioning

- The version is in the path: `/v1`. Within `v1` changes are additive: new endpoints, new optional fields, new
  response fields, new `error` codes and new enum values. Write clients that ignore unknown fields and treat unknown
  statuses as "not final".
- Anything that would break a `v1` client ships as a new version, announced in the [Changelog](https://docs.clipbeat.app/changelog/) first.

## CORS and where to call from

Only `GET /v1/openapi.json` allows calls from any browser origin. Call the other endpoints from your server, never from
a browser or app where users could read your key.

## Limits

60 requests per minute per key, 10 song imports and 4 new videos per hour per account. See
[Rate limits](https://docs.clipbeat.app/rate-limits/).
