API docs

Authentication

Every request needs your project's API key (shown once, when you created your project on the dashboard), sent as a bearer token:

Authorization: Bearer <your-api-key>

Translate a batch of segments

mode is "sync_or_queue" by default: a cached segment comes back immediately (status: "hit"); an uncached one is queued for translation and comes back with status: "queued", a job_id, and the source text as fallback — never a blocked request, never an empty string.

curl -X POST tapi.lotuspion.com/v1/translate \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_lang": "fa",
    "segments": [
      {"id": "s1", "text": "Add to cart"},
      {"id": "s2", "text": "<b>New</b> arrivals", "html": true}
    ]
  }'

{
  "results": [
    {"id": "s1", "text": "به سبد خرید اضافه کنید", "status": "hit", "cached_at": "2026-08-01T12:00:00Z"},
    {"id": "s2", "text": null, "status": "queued", "fallback": "<b>New</b> arrivals", "job_id": "b1f6..."}
  ],
  "stats": {"hits": 1, "queued": 1},
  "dir": "rtl",
  "lang": "fa"
}

Segments containing inline HTML markup that must survive translation intact (like s2 above) need "html": true — plain text segments don't set it.

Getting a queued translation once it's ready

Two ways, pick whichever fits your setup — poll, or ask an operator to set a webhook URL for your project:

curl tapi.lotuspion.com/v1/jobs/<job_id> \
  -H "Authorization: Bearer <your-api-key>"

Or, with a webhook configured, we POST this to your URL when the job finishes (HMAC-SHA256 signed with your webhook secret):

{
  "job_id": "b1f6...",
  "tenant_id": "...",
  "status": "done",
  "results": [{"id": "s2", "text": "<b>ورود جدید</b>"}]
}

Glossary — do-not-translate and fixed terms

curl -X PUT tapi.lotuspion.com/v1/glossary \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"terms": [{"term": "Acme", "target_lang": "fa"}]}'

An empty translation (or omitted entirely) means "never translate this term" — otherwise it's a fixed replacement, applied regardless of what the model would have produced.

Review queue

A segment that fails our quality gate (placeholder integrity, length ratio, target-script presence, glossary compliance) is never cached as done — it lands here instead, with the original source text served in the meantime.

curl tapi.lotuspion.com/v1/review \
  -H "Authorization: Bearer <your-api-key>"

Need something else?

Rate limits, a webhook URL, or changing your target languages — reach out to whoever set up your account.