# API reference

> Base URL, authentication and conventions of every endpoint.

Every endpoint page has an interactive playground: paste a token under **Authorization** and send
real requests. They act on your account for real.

## Base URL

```
https://api-vod-express.syncwords.com/v1
```

[Environments](/vod-express/environments) says how to keep the URL in one place.

## Authentication

```http
Authorization: Bearer <token>
```

A token from `POST /token/create`, made with your API key pair; see
[Authentication](/vod-express/authentication). Every call needs one except the output feeds under
*Feeds* (`GET /feeds/{projectId}/{language}/…`), which are public so that players can read them.

## Conventions

| | |
|---|---|
| Request bodies | JSON, or YAML (`Content-Type: application/yaml`), up to 2 MB. Any other type is a `415`. See [Request bodies](/vod-express/guides/limits#request-bodies). |
| Responses | JSON, wrapped in `data`. An `Accept` that prefers YAML (`application/yaml`) gets YAML from `GET /projects/{id}/config`, `GET /schema` and error answers. |
| Lists | `GET /projects` is paginated: `page`, `perPage`, and `links` / `meta` in the answer. `links` keep your filters: follow `links.next` until it is `null`. The other lists are complete. |
| Names in paths | A file name is one path segment: URL-encode it, slashes included. See [Subfolders](/vod-express/concepts/files#subfolders). |
| Errors | `{"message", "code"}`, plus `errors` on a `422`. Branch on `code`. See [Errors](/vod-express/guides/errors). |
| Unknown fields | Refused with a `422`. A typo never passes silently. |
| Rate limit | 1000 requests a minute per account; `X-RateLimit-*` headers, and `Retry-After` on a `429`. See [Limits](/vod-express/guides/limits#rate-limit). |
| Browsers | Every origin may call the API, and read `Retry-After`, `X-RateLimit-*` and `Idempotency-Replayed`. See [Browsers](/vod-express/guides/limits#browsers). |
| Timestamps | ISO 8601, in UTC: `2026-09-28T05:42:35.534Z`. |
| Webhooks | Signed POSTs to your server when a file is done or failed and when a project stops; the payloads are under *Webhooks* in `openapi.json`. See [Webhooks](/vod-express/guides/webhooks). |

Each operation's page links to the guide that explains it.

## The machine-readable description

These pages are generated from the API's OpenAPI 3.1 document. Two copies, both public:

- [`/openapi.json`](/vod-express/openapi.json) on this site types `config` field by field, for the build the
  [Config reference](/vod-express/configuration/reference) documents: the one to generate a client from. See
  [Generate a client](/vod-express/guides/clients), which also has a Postman collection.
- `GET https://api-vod-express.syncwords.com/v1/openapi.json` is what the API serves, with
  `config` as an object that [`GET /schema`](/vod-express/api-reference/get-schema) describes for any build.
  A Swagger UI over it is at [`/v1/docs`](https://api-vod-express.syncwords.com/v1/docs).