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.

​

Best Practices

​

API Key Hygiene

• Store keys in environment variables or a secrets manager. Never commit <your-api-key> values to source control or paste them in shared chats.
• Use a separate key per environment. Development, staging, and production should each have their own API key. Rotate when team members leave or a key is suspected leaked.
• Pass keys via X-Api-Key, not in the URL or request body. The header name is case-sensitive on some HTTP clients.
• Scope by Folder, not by key. Folders are how you isolate workflows and content (legal vs. marketing vs. internal training). All keys on an account can see all folders.

# Recommended
export OLLANG_API_KEY="<your-api-key>"
curl -H "X-Api-Key: $OLLANG_API_KEY" https://api-integration.ollang.com/health

​

Folder Structure

Marketing — Campaigns                 (folder workflow: aiDubbing overdub, Level 0)
Marketing — Brand Videos              (folder workflow: aiDubbing overdub, Level 1)
Product — Training Videos             (folder workflow: subtitle, Level 1)
Product — Help Center                 (folder workflow: document, Level 1)
Legal — Contracts                     (folder workflow: document, Level 1, formal tone)
Accessibility — Audio Description     (folder workflow: aiDubbing audioDescription)
API Uploads                           (default — for ad-hoc / dev usage)

• Folder-level workflows override Global workflows, so each team gets its preferred provider/review-gate setup without touching account defaults.
• Folder-level Custom Instructions / Guidelines apply automatically to every order created in that folder.
• Folder-level Memory keeps terminology consistent across multiple campaigns or product lines.

​

Callbacks vs. Polling

​

Callback handler checklist

• Idempotent. Use orderId (and optionally completedAt) as the deduplication key. The same callback may fire more than once on retry.
• Fast acknowledgment. Return 2xx within 10 seconds. Process asynchronously (queue, background job) if your handler does any real work.
• Confirm before acting. Don’t trust callback bodies alone. Pair with GET /integration/orders/<order-id> using your API key before performing irreversible actions (publishing content, billing customers).
• Public URLs only. Callback URLs must be reachable from the public internet. Internal hostnames and IPv6 destinations are blocked at the SSRF guard.

// Example: Express handler
app.post("/webhooks/ollang", async (req, res) => {
  // 1. Ack immediately
  res.sendStatus(200);

  // 2. Process asynchronously
  await queue.add("ollang-order-completed", {
    orderId: req.body.orderId,
    completedAt: req.body.completedAt,
  });
});

// Worker
async function handle(payload) {
  // 3. Re-fetch to verify
  const order = await ollang.orders.getById(payload.orderId);
  if (order.status !== "completed") return; // ignore false positives

  // 4. Use a transactional upsert keyed on orderId
  await db.deliveries.upsert({
    where: { orderId: order.orderId },
    create: { ... },
    update: { status: order.status },
  });
}

​

Polling pattern

while true; do
  STATUS=$(curl -s "https://api-integration.ollang.com/integration/orders/<order-id>" \
    -H "X-Api-Key: <your-api-key>" | jq -r '.status')
  case "$STATUS" in
    completed|revision) break ;;
    *) sleep 30 ;;
  esac
done

​

Retries and Backoff

• Retry on 408, 429, 500, 502, 503, 504.
• Use exponential backoff with jitter (e.g. 500ms → 1s → 2s → 4s → 8s, cap ~30s).
• Treat 429 (rate limit) seriously — slow your overall request rate, don’t just retry harder.
• Do not retry 400, 401, 403, 404 without changing the request — they indicate a client-side bug, not a transient failure.
• File uploads can have multi-minute response times. Set HTTP client read/write timeouts to 5–10 minutes for upload requests.

​

Choosing level: 0 vs level: 1

​

Memory and Custom Instructions

• Memory — approved translations for recurring terms (product names, trademarks, legal jargon). Reuse across projects.
• Custom Instructions — natural-language guidance to the AI (“Always use formal register in French,” “Translate ‘cookie’ as ‘cookie’ in cybersecurity contexts, not as the food”).
• Folder Guidelines override account-wide Custom Instructions for specific workflows.

1. Run a small Level 1 pilot batch.
2. Capture linguist edits into Memory.
3. Run subsequent Level 0 orders with the populated Memory — quality tends to converge quickly.

​

QC and Review Gates

• Enable autoQc: true on order creation to score every order immediately on completion. See Run QC Evaluation.
• Configure Review Gates in your Folder workflow to auto-route low-scoring orders to human review (Assignment mode) or to a review tag (Comment mode). See Workflows and Provider Architecture and the Review Gate entry in the glossary.
• Track QC progression in the Analytics dashboard — declining scores are usually a sign of a content/domain shift that needs Memory or Custom Instructions updates. See Analytics and QC Monitoring.

​

Bulk and Concurrent Operations

• Each targetLanguageConfigs entry creates one order. Issue them in a single createOrder request rather than looping, so you get consistent timestamps and a single response array.
• Parallelize uploads moderately (start at 3–5 concurrent). Watch for 429 and back off.
• Reuse projects across orders. One source video can drive multiple cc + subtitle + aiDubbing orders without re-uploading.

​

Error Handling

{
  "error": "Invalid file format",
  "message": "Only VTT files are supported",
  "code": "INVALID_FILE_FORMAT"
}

• 2xx → success
• 4xx → log and surface to the user; do not retry without changing the request
• 429 → backoff and retry
• 5xx → backoff and retry (up to N times)

​

Pagination

# Flat (folders, projects)
?page=1&take=20&search=sample&orderBy=createdAt&orderDirection=desc

# Nested pageOptions[...] (orders)
?pageOptions[page]=1
&pageOptions[take]=20
&pageOptions[search]=sample
&pageOptions[orderBy]=createdAt
&pageOptions[orderDirection]=desc

• take is the page size (default 10, max 50); the API returns a meta object with page, take, itemCount, pageCount, hasPreviousPage, and hasNextPage.
• Iterate until hasNextPage is false.
• Combine with filter[name], filter[type], or filter[createdAtRange] for more targeted queries.

​

Security

• Never log API keys, callback bodies containing tokens, or signed URLs.
• Treat vttUrl and orderDocs[].url as short-lived, sensitive URLs. Re-fetch via Get Order by ID before downloading rather than persisting them indefinitely.
• Restrict who has access to your API keys to the smallest team possible.
• If you suspect a key leak, rotate immediately in the Olabs Dashboard and update all consumers.

​

Versioning and Deprecations

​

When to Reach for Each Surface

• REST API — anything programmatic. Default choice.
• SDK — Node.js / TypeScript projects, plus when you want the Asset Management UI for i18n strings or CMS capture.
• MCP — non-developer team members operating Ollang through an AI assistant; ad-hoc / exploratory work; automated agents.
• Skills — coding agents (Cursor, Claude Code, Codex, Windsurf, Cline) when you want zero infra — just a file-based skill bundle.

​

See Also

• Use Cases — end-to-end workflow walkthroughs.
• API Conventions — pagination, errors, auth in one reference page.
• Troubleshooting — diagnostics for common issues.