Skip to main content

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

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

Request and Response Format

JSON responses generally fall into three shapes: Single resource:
List endpoints (paginated):
  • 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 with one object per order the request created, each with its orderId and orderType:
The array is in no guaranteed order and can hold more entries than targetLanguageConfigs (some order types also create the prerequisite orders they build on). Pick orders by orderType and read each one’s targetLanguage from Get Order by ID instead of relying on position. See Create Order.

Pagination

List endpoints accept a common set of pagination parameters. Two query-string styles are used depending on the endpoint: The canonical example for each endpoint is in its API reference page.
Iteration pattern:

Filters

List endpoints also accept domain-specific filter parameters. Common filters across endpoints: See per-endpoint reference pages for the full filter list.

Error Format

Error responses are JSON objects. Which fields are present depends on where the request was rejected, so branch on the HTTP status code and treat the body as diagnostic detail for logs, users, and support. There is no stable string error code to switch on. Missing API key (401):
Request validation failure (400) — here a targetLanguageConfigs entry without isRush:
Error returned from the platform (for example 404 for an order your key cannot see):
Unknown route (404):
Server-side failure (5xx):

Request ID

Every response, including errors, carries a request-id header (a UUID). Log it with failed requests and include it when you contact support — it lets us find the exact request in our logs.

Standard Status Codes

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:
Rules:
  • One attempt with a 10-second response timeout. Failed callbacks are not retried, so keep polling as a safety net.
  • Callbacks are unsigned — confirm with Get Order by ID before acting.
  • callbackUrl must be an https URL on a public host. 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 order a request creates has its own orderId; a single create request can return several.

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, verified list — the API response is authoritative if a code isn’t listed there. Order and upload language fields (targetLanguageConfigs[].language and upload/project sourceLanguage) are validated as BCP-47 tags and matched exactly: a code from that list, or a standard language / language-REGION tag (for example fr-CH), is accepted, and anything else is rejected with 400. An accepted tag outside the list falls back to the closest supported match when a regional variant isn’t directly recognized; see BCP-47 support for how that resolves.

File Size Limits

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.

Service Status

Live availability, open incidents, and scheduled maintenance for the Ollang platform and its APIs are published at status.ollang.com. Check it first when requests start failing across the board — an incident there explains more than a retry loop will. The unauthenticated Health Check endpoint answers a narrower question — whether api-integration.ollang.com is reachable and healthy from your network. Use /health for readiness probes and connectivity checks, and the Status page for platform-wide incidents.

Security and Trust

Ollang’s security, privacy, and compliance documentation lives at the Trust Center — start there for vendor security reviews and questionnaires. For day-to-day integration hygiene (key rotation, handling signed orderDocs[].url links), see Best Practices — Security.

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