{"openapi":"3.1.0","info":{"title":"DocsRTL API","version":"1.0.0","description":"Translate Word documents (.docx, .doc, .odt, .rtf) between 40+ languages while preserving all formatting, fonts, styles, hyperlinks, and nested tables. Supports every direction: LTR-to-RTL, RTL-to-LTR, LTR-to-LTR, and RTL-to-RTL. RTL output (Hebrew, Arabic, Persian, Urdu) automatically applies right-to-left layout. Authenticate with X-API-Key.","contact":{"url":"https://docsrtl.com","email":"support@docsrtl.com"}},"servers":[{"url":"https://docsrtl.com/v1","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key issued from your account dashboard (Pro/Enterprise only)."}},"schemas":{"RtlFidelity":{"type":"object","properties":{"status":{"type":"string","enum":["full","partial","degraded"],"description":"RTL formatting preservation quality."},"warnings":{"type":"array","items":{"type":"string"},"description":"Human-readable warnings about RTL conversion issues."}},"required":["status","warnings"]},"JobStatus":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"source_lang":{"type":"string","nullable":true},"target_lang":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"download_url":{"type":"string","nullable":true,"description":"Path to download the translated file once completed."},"error":{"type":"string","nullable":true},"rtl_fidelity":{"$ref":"#/components/schemas/RtlFidelity","nullable":true}}}}},"paths":{"/health":{"get":{"operationId":"health","summary":"Liveness check","description":"Returns {ok: true}. No authentication required.","security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/languages":{"get":{"operationId":"list_languages","summary":"List supported target languages","description":"Returns the full list of language names accepted by /translate.","responses":{"200":{"description":"Language list","content":{"application/json":{"schema":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"string"}}}}}}}}}},"/usage":{"get":{"operationId":"get_usage","summary":"Get current-period quota usage","description":"Returns how many words you've used and how many remain this billing period.","responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"type":"object","properties":{"used_words":{"type":"integer"},"limit_words":{"type":"integer","nullable":true},"plan_name":{"type":"string"}}}}}}}}},"/translate":{"post":{"operationId":"translate_document","summary":"Submit a document for translation","description":"Upload a document and receive a job_id immediately. Poll GET /v1/jobs/{job_id} until status is 'completed', then download via GET /v1/jobs/{job_id}/download. Supported formats: .docx, .doc, .odt, .rtf (max 50 MB). Any direction is supported: LTR-to-RTL, RTL-to-LTR, LTR-to-LTR, and RTL-to-RTL. RTL targets (Hebrew, Arabic, Persian, Urdu) get full right-to-left layout.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Document to translate (.docx, .doc, .odt, .rtf)."},"target_lang":{"type":"string","default":"Arabic","description":"Target language name (see /v1/languages for valid values)."},"source_lang":{"type":"string","default":"auto","description":"Source language or 'auto' for auto-detection."},"translation_mode":{"type":"string","enum":["professional","full","literal"],"default":"professional","description":"Translation quality mode: 'professional' (preserves technical terms), 'full' (immersive, translates everything), 'literal' (word-for-word)."}}}}}},"responses":{"202":{"description":"Job accepted — poll poll_url for status","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"poll_url":{"type":"string"},"rtl_fidelity":{"$ref":"#/components/schemas/RtlFidelity"}}}}}},"402":{"description":"Monthly word quota exhausted — upgrade plan"},"429":{"description":"Per-minute rate limit exceeded — check Retry-After header"}}}},"/jobs/{job_id}":{"get":{"operationId":"get_job_status","summary":"Poll translation job status","description":"Returns the current state of a translation job. Poll until status is 'completed' or 'failed'.","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"404":{"description":"Job not found or expired"}}}},"/jobs/{job_id}/download":{"get":{"operationId":"download_translation","summary":"Download the translated document","description":"Returns the translated DOCX file. Only available when job status is 'completed'. Files expire 10 minutes after completion.","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Translated DOCX file","content":{"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Job not found, not complete, or file already expired"},"410":{"description":"Translated file has expired and been deleted"}}}},"/translate-url":{"post":{"operationId":"translate_document_url","summary":"Submit a document URL for translation","description":"Fetch a document from a URL and translate it. Use this when you cannot upload bytes directly (e.g. from a GPT Action). Returns a job_id - poll GET /v1/jobs/{job_id} until 'completed', then download via GET /v1/jobs/{job_id}/download. Supported formats: .docx, .doc, .odt, .rtf (max 50 MB). All translation directions are supported - see /v1/languages for the full list of accepted source and target languages.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL of the document to translate."},"target_lang":{"type":"string","default":"Arabic","description":"Target language name (see /v1/languages)."},"source_lang":{"type":"string","default":"auto"},"translation_mode":{"type":"string","enum":["professional","full","literal"],"default":"professional","description":"Translation quality mode: 'professional' (preserves technical terms), 'full' (immersive, translates everything), 'literal' (word-for-word)."}}}}}},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"poll_url":{"type":"string"}}}}}},"400":{"description":"Invalid URL or unsupported document format"},"402":{"description":"Monthly word quota exhausted"},"429":{"description":"Rate limit exceeded"}}}}}}