> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.ollang.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Conventions

> Base URL, authentication, request/response format, pagination, errors, and callbacks for the Ollang Integration API.

# API Conventions

The conventions on this page apply to every endpoint under
`https://api-integration.ollang.com`. Read this once and the
individual API reference pages should feel predictable.

## Base URL

```
https://api-integration.ollang.com
```

All endpoints are HTTPS-only. There is no separate sandbox host — use
test data and the AI-only `level: 0` flow against the same base URL to
experiment safely.

## Authentication

The REST API authenticates with a single header:

| Header      | Value                                                           |
| ----------- | --------------------------------------------------------------- |
| `X-Api-Key` | Your API key from the [Olabs Dashboard](https://lab.ollang.com) |

```bash theme={null}
curl https://api-integration.ollang.com/integration/orders \
  -H "X-Api-Key: <your-api-key>"
```

* The `/health` endpoint does **not** require a key — it's the
  recommended connectivity sanity check. See
  [Health Check](/apis/ollang-api-reference/health-check).
* Header name is case-sensitive on some HTTP clients. Use `X-Api-Key`,
  not `Authorization` or `X-API-KEY`.
* API keys are account-scoped and can read every Folder, Project, and
  Order on that account.

## Content Types

| Operation                            | Content type          |
| ------------------------------------ | --------------------- |
| File uploads                         | `multipart/form-data` |
| Everything else (JSON in / JSON out) | `application/json`    |

## Request and Response Format

JSON responses generally fall into three shapes:

**Single resource:**

```json theme={null}
{
  "id": "<order-id>",
  "status": "completed",
  "...": "..."
}
```

**List endpoints (paginated):**

```json theme={null}
{
  "data": [ { "id": "<order-id>", "...": "..." } ],
  "meta": {
    "page": 1,
    "take": 10,
    "itemCount": 153,
    "pageCount": 16,
    "hasPreviousPage": false,
    "hasNextPage": true
  }
}
```

* `page` is 1-indexed.
* `take` is the page size that was applied.
* `itemCount` is the total number of items across all pages.
* `pageCount` is the total number of pages.
* Iterate until `hasNextPage` is `false`.

**Order creation:** an **array** of objects, one per
`targetLanguageConfigs` entry:

```json theme={null}
[
  { "orderId": "<order-id-fr>" },
  { "orderId": "<order-id-es>" }
]
```

See [Create Order](/apis/ollang-api-reference/create-order).

## Pagination

List endpoints accept a common set of pagination parameters. Two query-string styles are used depending on the endpoint:

| Parameter        | Type    | Description                               |
| ---------------- | ------- | ----------------------------------------- |
| `page`           | integer | 1-indexed page number. Defaults to `1`.   |
| `take`           | integer | Page size. Defaults to `10`, max `50`.    |
| `search`         | string  | Free-text search across name/description. |
| `orderBy`        | string  | Sort field (e.g. `createdAt`, `name`).    |
| `orderDirection` | string  | `asc` or `desc`. Defaults to `desc`.      |

* **Flat style** (`page=`, `take=`, ...) is used on [Retrieve All Folders](/apis/ollang-api-reference/retrieve-all-folders) and [Retrieve All Projects](/apis/ollang-api-reference/retrieve-all-projects).
* **Nested `pageOptions[...]` style** is used on [Get Orders](/apis/ollang-api-reference/get-orders) (e.g. `pageOptions[page]=1`, `pageOptions[take]=20`).

The canonical example for each endpoint is in its API reference page.

```bash theme={null}
# Flat style (folders, projects)
curl "https://api-integration.ollang.com/integration/folder?page=1&take=20&orderBy=createdAt&orderDirection=desc" \
  -H "X-Api-Key: <your-api-key>"

# pageOptions style (orders)
curl "https://api-integration.ollang.com/integration/orders?\
pageOptions[page]=1&\
pageOptions[take]=20&\
pageOptions[orderBy]=createdAt&\
pageOptions[orderDirection]=desc" \
  -H "X-Api-Key: <your-api-key>"
```

**Iteration pattern:**

```typescript theme={null}
let page = 1;
while (true) {
  const res = await fetch(
    `https://api-integration.ollang.com/integration/orders?pageOptions[page]=${page}&pageOptions[take]=50`,
    { headers: { "X-Api-Key": process.env.OLLANG_API_KEY! } }
  ).then(r => r.json());

  for (const order of res.data) handle(order);
  if (!res.meta.hasNextPage) break;
  page += 1;
}
```

## Filters

List endpoints also accept domain-specific `filter` parameters. Common
filters across endpoints:

| Parameter                | Type   | Description                                                                           |
| ------------------------ | ------ | ------------------------------------------------------------------------------------- |
| `filter[type]`           | string | Restrict by `orderType` (`cc`, `subtitle`, `document`, `aiDubbing`, `studioDubbing`). |
| `filter[name]`           | string | Substring match on entity name.                                                       |
| `filter[createdAtRange]` | object | `{ "from": "ISO-8601", "to": "ISO-8601" }`.                                           |

See per-endpoint reference pages for the full filter list.

## Error Format

All error responses share this shape:

```json theme={null}
{
  "error": "Invalid file format",
  "message": "Only VTT files are supported",
  "code": "INVALID_FILE_FORMAT"
}
```

| Field     | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| `error`   | Short, human-readable summary.                                       |
| `message` | Detailed explanation suitable for surfacing to the end user.         |
| `code`    | Stable machine-readable identifier safe to switch on in client code. |

### Standard Status Codes

| Status                   | Meaning                                             | Retryable?                      |
| ------------------------ | --------------------------------------------------- | ------------------------------- |
| `200 OK` / `201 Created` | Success                                             | —                               |
| `400 Bad Request`        | Invalid parameters                                  | No — fix the request            |
| `401 Unauthorized`       | Missing or invalid API key                          | No — check `X-Api-Key`          |
| `403 Forbidden`          | Authenticated but not permitted                     | No                              |
| `404 Not Found`          | Resource doesn't exist or isn't visible to your key | No                              |
| `408 Request Timeout`    | Slow request                                        | Yes, with backoff               |
| `413 Payload Too Large`  | File exceeds size limit                             | No — split or use Direct Upload |
| `429 Too Many Requests`  | Rate-limited                                        | Yes, with backoff — slow down   |
| `5xx`                    | Server-side error                                   | Yes, with backoff               |

See [Best Practices — Retries and Backoff](/concepts/best-practices#retries-and-backoff).

## Webhooks / Callbacks

Endpoints that kick off long-running work (`createOrder`, `rerunOrder`)
accept an optional `callbackUrl`. Ollang `POST`s a JSON payload to that
URL when the order completes:

```json theme={null}
{
  "orderId": "<order-id>",
  "status": "completed",
  "orderType": "subtitle",
  "targetLanguage": "fr",
  "completedAt": "2026-05-12T10:00:00Z",
  "orderDocs": [
    { "type": "created_subtitle", "name": "fr.srt", "url": "https://example.com/..." }
  ],
  "vttUrl": "https://example.com/<order-id>.vtt"
}
```

**Rules:**

* 10-second response timeout.
* IPv6 destinations and internal hostnames are blocked at the SSRF guard.
* Treat handlers as **idempotent**. Use `orderId` as the dedup key.
* Re-confirm via [Get Order by ID](/apis/ollang-api-reference/get-order-by-id) before acting on the body for irreversible operations.

See [Best Practices — Callbacks vs. Polling](/concepts/best-practices#callbacks-vs-polling).

## IDs

* All Ollang IDs are opaque strings — do not assume any particular
  format (length, prefix, or characters). Treat them as case-sensitive
  identifiers.
* IDs are stable for the lifetime of the resource.
* Each `targetLanguageConfigs` entry produces a distinct `orderId`.

## Timestamps

All timestamps are ISO-8601 UTC unless otherwise noted (e.g. `2026-05-12T10:00:00Z`).
Where a numeric epoch is returned (`/health`'s `time`), it is
milliseconds since the Unix epoch.

## Language Codes

Mostly ISO 639-1 two-letter codes (`en`, `fr`, `es`), with regional and
script variants where needed (`pt-PT`, `es-MX`, `zh-Hant`, `fr-CA`).
See [Supported Languages](/apis/ollang-api-reference/supported-languages)
for the canonical list — the API response is authoritative if a code
isn't listed there.

## File Size Limits

| Resource                      | Limit                              |
| ----------------------------- | ---------------------------------- |
| Video uploads (Direct Upload) | 30 GB                              |
| Audio / Document uploads      | 100 MB                             |
| In-page API playground        | 5 MB                               |
| Embedded callback payload     | \< 1 MB (URLs reference downloads) |

For very large videos, always use [Direct File Upload](/apis/ollang-api-reference/direct-file-upload)
rather than web/dashboard upload paths.

## Rate Limits

Ollang enforces per-account rate limits. If you receive `429`, back off
exponentially. For high-volume use cases, contact Ollang to discuss
limits before launch.

## Versioning

The Integration API is non-versioned at the URL level. We commit to:

* **Additive changes** (new optional fields, new endpoints) ship
  without notice.
* **Breaking changes** (parameter removal, response shape changes) are
  announced in the [Changelog](/changelog) in advance.

## See Also

* [Best Practices](/concepts/best-practices)
* [Troubleshooting](/troubleshooting)
* [Getting Started](/getting-started)
* [How It All Connects](/concepts/how-it-all-connects)