API Conventions
The conventions on this page apply to every endpoint underhttps://api-integration.ollang.com. Read this once and the
individual API reference pages should feel predictable.
Base URL
level: 0 flow against the same base URL to
experiment safely.
Authentication
The REST API authenticates with a single header:- The
/healthendpoint 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, notAuthorizationorX-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:pageis 1-indexed.takeis the page size that was applied.itemCountis the total number of items across all pages.pageCountis the total number of pages.- Iterate until
hasNextPageisfalse.
orderId and orderType:
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:- 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).
Filters
List endpoints also accept domain-specificfilter 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):
400) — here a targetLanguageConfigs entry
without isRush:
404 for an order your key
cannot see):
404):
5xx):
Request ID
Every response, including errors, carries arequest-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:
- 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.
callbackUrlmust be anhttpsURL on a public host. IPv6 destinations and internal hostnames are blocked at the SSRF guard.- Treat handlers as idempotent. Use
orderIdas the dedup key. - Re-confirm via Get Order by ID before acting on the body for irreversible operations.
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 receive429, 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 — whetherapi-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 signedorderDocs[].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
- Best Practices
- Troubleshooting
- Getting Started
- How It All Connects
- Service Status — live availability and incidents
- Trust Center — security, privacy, and compliance