Skip to main content

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

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:
HeaderValue
X-Api-KeyYour 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

OperationContent type
File uploadsmultipart/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:
ParameterTypeDescription
pageinteger1-indexed page number. Defaults to 1.
takeintegerPage size. Defaults to 10, max 50.
searchstringFree-text search across name/description.
orderBystringSort field (e.g. createdAt, name).
orderDirectionstringasc or desc. Defaults to desc.
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:
ParameterTypeDescription
filter[type]stringRestrict by orderType (cc, subtitle, document, aiDubbing, studioDubbing).
filter[name]stringSubstring 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"
}
FieldDescription
errorShort, human-readable summary.
messageDetailed explanation suitable for surfacing to the end user.
codeStable machine-readable identifier safe to switch on in client code.

​
Standard Status Codes

StatusMeaningRetryable?
200 OK / 201 CreatedSuccess—
400 Bad RequestInvalid parametersNo — fix the request
401 UnauthorizedMissing or invalid API keyNo — check X-Api-Key
403 ForbiddenAuthenticated but not permittedNo
404 Not FoundResource doesn’t exist or isn’t visible to your keyNo
408 Request TimeoutSlow requestYes, with backoff
413 Payload Too LargeFile exceeds size limitNo — split or use Direct Upload
429 Too Many RequestsRate-limitedYes, with backoff — slow down
5xxServer-side errorYes, 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

ResourceLimit
Video uploads (Direct Upload)30 GB
Audio / Document uploads100 MB
In-page API playground5 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.

​
See Also