{"title":"XFTS API","version":"1.2.6","status":"OK","description":"The File Translation Service API facilitates end-to-end management of translation workflows.\nDevelopers can create, manage, and monitor jobs by specifying source and target language pairs.\nThe API allows uploading source files (with metadata) and attaching them to jobs.\nTranslations can be triggered asynchronously via a dedicated endpoint, which supports webhook registration for status notifications.\nClients can monitor job/file status, download source files, and retrieve the translated output when available.\n\n---\n\n## Quick Start\n\nA typical translation workflow follows these steps:\n\n<details>\n<summary><strong> 1. Acquire an OAuth2 token<strong></summary>\n\nRequest a client credentials token from the token endpoint:\n\n```http\nPOST /oauth2/token\nContent-Type: application/x-www-form-urlencoded\n\nclient_id=<your_client_id>&client_secret=<your_client_secret>&grant_type=client_credentials\n```\n\nAttach the returned `access_token` to all subsequent requests:\n\n```http\nAuthorization: Bearer <access_token>\n```\n\n> Tokens are short-lived (1 hour). Your client should handle 401 responses by re-acquiring a token and retrying the request.\n</details>\n\n<details>\n<summary><strong>2. Create a job<strong></summary>\n\nAll files within a job must share the same source language. Target languages are declared upfront.\n\n```http\nPOST /jobs\nContent-Type: application/json\nAuthorization: Bearer <access_token>\n\n{\n  \"name\": \"Spring Collection Landing Page\",\n  \"sourceLanguage\": \"en-US\",\n  \"targetLanguages\": [\"de-DE\", \"pt-PT\"],\n  \"dueDate\": \"2025-07-15T13:00:00.000Z\",\n  \"additionalInformation\": \"Please use formal tone.\",\n  \"mode\": \"HITL\"\n}\n```\n\nThe response contains the `jobId` required for all subsequent steps.\n</details>\n\n<details>\n<summary><strong>3. Upload and attach a source file<strong></summary>\n\nUpload the source file and attach it to the job in a single request.\nThe `language` form field must match the job's `sourceLanguage`.\n\n```http\nPOST /jobs/{jobId}/files\nContent-Type: multipart/form-data\nAuthorization: Bearer <access_token>\n\nfile=@source_file.json\nlanguage=en-US\nreferenceId=<optional_external_ref>\nmetadata=<optional_json_string>\n```\n\nRepeat this step for each source file. The response contains the `fileId` needed for download.\n</details>\n\n<details>\n<summary><strong>4. Submit the job for translation<strong></summary>\n\nLocks the job and initiates the asynchronous translation workflow.\nOptionally register a webhook to receive push notifications on completion or failure:\n\n```http\nPOST /jobs/{jobId}/translate\nContent-Type: application/json\nAuthorization: Bearer <access_token>\n\n{\n  \"webhook\": {\n    \"url\": \"https://your-app.com/hooks/xfts\",\n    \"secret\": \"your_webhook_secret\",\n    \"events\": [\"project.delivered\", \"project.failed\"]\n  }\n}\n```\n\n> The webhook body can be omitted entirely if polling is preferred.\n</details>\n\n<details>\n<summary><strong>5. Download the translated output<strong></summary>\n\nPoll `GET /jobs/{jobId}` for status, or wait for the webhook event, then download per file per target language:\n\n```http\nGET /jobs/{jobId}/files/{fileId}/{languageCode}/download\nAuthorization: Bearer <access_token>\n```\n\nFor example, to download the German translation: `GET /jobs/{jobId}/files/{fileId}/de-DE/download`\n\nSee individual endpoint docs below for full request/response schemas.\n</details>\n\n---\n"}