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

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.
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:

{
  "id": "<order-id>",
  "status": "completed",
  "...": "..."
}

List endpoints (paginated):

{
  "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:

[
  { "orderId": "<order-id-fr>" },
  { "orderId": "<order-id-es>" }
]

See 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 and Retrieve All Projects.
Nested pageOptions[...] style is used on Get Orders (e.g. pageOptions[page]=1, pageOptions[take]=20).

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

# 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:

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:

{
  "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.

Webhooks / Callbacks

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

{
  "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 before acting on the body for irreversible operations.

See 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 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 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 in advance.

​API Conventions

​Base URL

​Authentication

​Content Types

​Request and Response Format

​Pagination

​Filters

​Error Format

​Standard Status Codes

​Webhooks / Callbacks

​IDs

​Timestamps

​Language Codes

​File Size Limits

​Rate Limits

​Versioning

​See Also