> ## 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.

# Available Tools

> Complete reference for the tools exposed by the Ollang MCP server.

# MCP Tools Reference

The Ollang MCP server exposes the following tools, grouped by category. Each tool maps to one or more endpoints in the [Ollang Integration API](/apis/ollang-api-reference/direct-file-upload) — MCP simply gives your AI assistant a natural-language interface to them.

## File Management

<AccordionGroup>
  <Accordion title="uploadFile" icon="upload">
    Upload files for processing and translation. Supports videos (MP4, AVI, MOV), documents (PDF, DOCX), images in JPEG, JPG, or PNG for Image to Image translation, audio files, subtitles, JSON, and DITA/XML content.

    **Parameters:**

    | Name             | Type   | Required | Description                                                                                                            |
    | ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
    | `name`           | string | Yes      | File name (e.g., `video.mp4`, `document.pdf`)                                                                          |
    | `sourceLanguage` | string | Yes      | Source language code (e.g., `en`, `es`, `fr`)                                                                          |
    | `url`            | string | No       | URL to download the file from (presigned URLs supported) — fetched server-side, so any file size the API accepts works |
    | `base64Content`  | string | No       | Base64-encoded binary file content (e.g., a local PDF or DOCX) — best for smaller files                                |
    | `expectedSize`   | number | No       | Expected decoded size in bytes of `base64Content`; the upload fails on mismatch                                        |
    | `sha256`         | string | No       | Expected SHA-256 hex digest of the decoded `base64Content`; the upload fails on mismatch                               |
    | `content`        | string | No       | JSON content as a string (not for binary files — use `base64Content`)                                                  |
    | `ditaContent`    | string | No       | DITA/XML content as a string                                                                                           |
    | `notes`          | array  | No       | Array of order notes with `details` and optional `timeStamp`                                                           |
    | `folderId`       | string | No       | Folder ID to place the project in (must belong to the same client)                                                     |

    <Note>Provide exactly one of `url`, `base64Content`, `content`, or `ditaContent` — one source per upload. Base64 payloads travel through the AI assistant's context, so prefer `url` for files larger than a few megabytes, and pass `expectedSize` and/or `sha256` with `base64Content` so uploads fail loudly if the data is corrupted in transit.</Note>
  </Accordion>

  <Accordion title="uploadVttFile" icon="closed-captioning">
    Upload a VTT subtitle file for a project, from WebVTT content or a URL.

    **Parameters:**

    | Name             | Type   | Required | Description                                                      |
    | ---------------- | ------ | -------- | ---------------------------------------------------------------- |
    | `projectId`      | string | Yes      | The project ID to upload the VTT file for                        |
    | `name`           | string | Yes      | Name of the VTT file (e.g., `subtitles.vtt`)                     |
    | `vttContent`     | string | No       | WebVTT content as a string (must start with the `WEBVTT` header) |
    | `url`            | string | No       | URL to download the VTT file from                                |
    | `sourceLanguage` | string | No       | Source language code of the subtitles                            |

    <Note>Provide exactly one of `vttContent` or `url`.</Note>
  </Accordion>

  <Accordion title="beginChunkedUpload" icon="layer-group">
    Start an upload session for binary files too large to send inline in one tool call. Returns an `uploadId` plus a direct PUT `uploadUrl` — the preferred path is to PUT the raw file bytes to that URL with any HTTP client, so the file never passes through the AI assistant's context.

    **Parameters:**

    | Name             | Type   | Required | Description                                                                                                               |
    | ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
    | `name`           | string | Yes      | Name of the file (e.g., `document.pdf`)                                                                                   |
    | `sourceLanguage` | string | Yes      | Source language code (e.g., `en`)                                                                                         |
    | `expectedSize`   | number | Yes      | Exact file size in bytes — verified before upload                                                                         |
    | `sha256`         | string | No       | SHA-256 hex digest of the file — verified before upload, strongly recommended                                             |
    | `totalChunks`    | number | No       | Only for the base64-chunk fallback: number of pieces to send via `appendUploadChunk`. Omit when using the PUT `uploadUrl` |
    | `notes`          | array  | No       | Array of order notes                                                                                                      |
    | `folderId`       | string | No       | Folder ID to place the project in                                                                                         |

    <Note>Sessions expire after 60 minutes. As a fallback when no HTTP client is available, send the file's base64 in pieces with `appendUploadChunk`, then call `finalizeChunkedUpload`.</Note>
  </Accordion>

  <Accordion title="appendUploadChunk" icon="puzzle-piece">
    Send one base64 piece of a chunked upload session (fallback path). Chunks are consecutive substrings of the file's full base64 string.

    **Parameters:**

    | Name          | Type   | Required | Description                                                                                    |
    | ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
    | `uploadId`    | string | Yes      | Session ID from `beginChunkedUpload`                                                           |
    | `chunkIndex`  | number | Yes      | 0-based position of this chunk                                                                 |
    | `base64Chunk` | string | Yes      | Consecutive piece of the file's base64 string, at most 4000 characters                         |
    | `chunkLength` | number | Yes      | Character count of `base64Chunk` — the call fails on mismatch, catching truncation immediately |
  </Accordion>

  <Accordion title="finalizeChunkedUpload" icon="circle-check">
    Assemble all chunks of an upload session, verify integrity (size and optional SHA-256), and upload the file to Ollang. Returns the new `projectId`.

    **Parameters:**

    | Name       | Type   | Required | Description                          |
    | ---------- | ------ | -------- | ------------------------------------ |
    | `uploadId` | string | Yes      | Session ID from `beginChunkedUpload` |
  </Accordion>

  <Accordion title="cancelChunkedUpload" icon="ban">
    Discard a chunked upload session and its stored chunks without uploading.

    **Parameters:**

    | Name       | Type   | Required | Description                          |
    | ---------- | ------ | -------- | ------------------------------------ |
    | `uploadId` | string | Yes      | Session ID from `beginChunkedUpload` |
  </Accordion>
</AccordionGroup>

## Order Management

<AccordionGroup>
  <Accordion title="createOrder" icon="plus">
    Create a new translation or transcription order.

    **Parameters:**

    | Name                    | Type   | Required | Description                                                        |
    | ----------------------- | ------ | -------- | ------------------------------------------------------------------ |
    | `projectId`             | string | Yes      | Project ID from a previous file upload                             |
    | `orderType`             | string | Yes      | One of: `cc`, `subtitle`, `aiDubbing`, `studioDubbing`, `document` |
    | `level`                 | number | Yes      | `0` = full AI, `1` = AI + human review                             |
    | `targetLanguageConfigs` | array  | Yes      | Array of `{ language: string, isRush?: boolean }`                  |
  </Accordion>

  <Accordion title="getOllangOrders" icon="list">
    Fetch orders with pagination, search, and sorting.

    **Parameters:**

    | Name             | Type   | Required | Description                        |
    | ---------------- | ------ | -------- | ---------------------------------- |
    | `page`           | number | No       | Page number (default: 1)           |
    | `take`           | number | No       | Items per page (1–50, default: 10) |
    | `search`         | string | No       | Search query                       |
    | `orderBy`        | string | No       | Sort field (default: `id`)         |
    | `orderDirection` | string | No       | `asc` or `desc` (default: `desc`)  |
  </Accordion>

  <Accordion title="getOrderById" icon="magnifying-glass">
    Get detailed information about a specific order including QC results.

    **Parameters:**

    | Name      | Type   | Required | Description  |
    | --------- | ------ | -------- | ------------ |
    | `orderId` | string | Yes      | The order ID |
  </Accordion>

  <Accordion title="cancelOrder" icon="xmark">
    Cancel an existing order.

    **Parameters:**

    | Name      | Type   | Required | Description            |
    | --------- | ------ | -------- | ---------------------- |
    | `orderId` | string | Yes      | The order ID to cancel |
  </Accordion>

  <Accordion title="rerunOrder" icon="rotate">
    Re-run an order to regenerate the translation with current AI models.

    **Parameters:**

    | Name      | Type   | Required | Description           |
    | --------- | ------ | -------- | --------------------- |
    | `orderId` | string | Yes      | The order ID to rerun |
  </Accordion>

  <Accordion title="requestSubtitleEmbedding" icon="film">
    Request subtitle embedding for an order to burn (hardcode) the translated subtitles directly into the video file.

    **Parameters:**

    | Name      | Type   | Required | Description                                    |
    | --------- | ------ | -------- | ---------------------------------------------- |
    | `orderId` | string | Yes      | The order ID to request subtitle embedding for |
  </Accordion>

  <Accordion title="exportOrderXlsx" icon="file-excel">
    Export video timestamps, transcriptions, and translations for an order as an XLSX spreadsheet. Returns a short-lived download URL (expires after 60 minutes) — the file bytes never pass through the AI assistant's context.

    **Parameters:**

    | Name      | Type   | Required | Description            |
    | --------- | ------ | -------- | ---------------------- |
    | `orderId` | string | Yes      | The order ID to export |
  </Accordion>
</AccordionGroup>

## Quality Control

<AccordionGroup>
  <Accordion title="runQcEvaluation" icon="check-double">
    Run an AI-powered quality control evaluation on an order.

    **Parameters:**

    | Name           | Type    | Required | Description                                         |
    | -------------- | ------- | -------- | --------------------------------------------------- |
    | `orderId`      | string  | Yes      | The order ID to evaluate                            |
    | `accuracy`     | boolean | No       | Evaluate translation accuracy (default: true)       |
    | `fluency`      | boolean | No       | Evaluate fluency in target language (default: true) |
    | `tone`         | boolean | No       | Evaluate tone and style (default: true)             |
    | `culturalFit`  | boolean | No       | Evaluate cultural appropriateness (default: true)   |
    | `customPrompt` | string  | No       | Custom evaluation instructions                      |
  </Accordion>

  <Accordion title="requestHumanReview" icon="user-check">
    Escalate an order for manual review by a human translator.

    **Parameters:**

    | Name      | Type   | Required | Description  |
    | --------- | ------ | -------- | ------------ |
    | `orderId` | string | Yes      | The order ID |
  </Accordion>

  <Accordion title="cancelHumanReview" icon="user-xmark">
    Cancel an active human review request. Reverts a Level 1 (Human Review) order back to Level 0 (AI-only), refunds the human review credits, and disconnects the assigned translator. Only Level 1 orders with status `ongoing` can be cancelled.

    **Parameters:**

    | Name      | Type   | Required | Description                             |
    | --------- | ------ | -------- | --------------------------------------- |
    | `orderId` | string | Yes      | The order ID to cancel human review for |
  </Accordion>
</AccordionGroup>

## Revisions

<AccordionGroup>
  <Accordion title="createRevision" icon="pen-to-square">
    Report issues or request changes to delivered content.

    **Parameters:**

    | Name          | Type   | Required | Description                                                                         |
    | ------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
    | `orderId`     | string | Yes      | The order ID                                                                        |
    | `type`        | string | Yes      | Issue type: `missingSubtitle`, `wrongSubtitle`, `syncError`, `formatError`, `other` |
    | `description` | string | No       | Detailed description of what needs correction                                       |
    | `time`        | string | No       | Timestamp where the issue occurs (format: `HH:MM:SS`)                               |
  </Accordion>

  <Accordion title="getOrderRevisions" icon="clock-rotate-left">
    Retrieve all revision requests for an order.

    **Parameters:**

    | Name      | Type   | Required | Description  |
    | --------- | ------ | -------- | ------------ |
    | `orderId` | string | Yes      | The order ID |
  </Accordion>

  <Accordion title="deleteRevision" icon="trash">
    Delete a specific revision request.

    **Parameters:**

    | Name         | Type   | Required | Description               |
    | ------------ | ------ | -------- | ------------------------- |
    | `orderId`    | string | Yes      | The order ID              |
    | `revisionId` | string | Yes      | The revision ID to delete |
  </Accordion>
</AccordionGroup>

## Projects

<AccordionGroup>
  <Accordion title="getAllProjects" icon="folder-open">
    Retrieve all projects with pagination, search, and sorting.

    **Parameters:**

    | Name             | Type   | Required | Description                        |
    | ---------------- | ------ | -------- | ---------------------------------- |
    | `page`           | number | No       | Page number (default: 1)           |
    | `take`           | number | No       | Items per page (1–50, default: 10) |
    | `search`         | string | No       | Search query                       |
    | `orderBy`        | string | No       | Sort field (default: `id`)         |
    | `orderDirection` | string | No       | `asc` or `desc` (default: `desc`)  |
  </Accordion>

  <Accordion title="getProjectById" icon="folder">
    Get detailed information about a specific project.

    **Parameters:**

    | Name        | Type   | Required | Description    |
    | ----------- | ------ | -------- | -------------- |
    | `projectId` | string | Yes      | The project ID |
  </Accordion>
</AccordionGroup>

## Custom Instructions

<AccordionGroup>
  <Accordion title="getAllCustomInstructions" icon="scroll">
    Retrieve all custom translation instructions for your account.

    **Parameters:** None
  </Accordion>

  <Accordion title="createCustomInstruction" icon="plus">
    Create a new reusable translation guideline.

    **Parameters:**

    | Name      | Type   | Required | Description              |
    | --------- | ------ | -------- | ------------------------ |
    | `title`   | string | Yes      | Title of the instruction |
    | `content` | string | Yes      | The guideline content    |
  </Accordion>

  <Accordion title="updateCustomInstruction" icon="pen">
    Update an existing custom instruction.

    **Parameters:**

    | Name            | Type   | Required | Description        |
    | --------------- | ------ | -------- | ------------------ |
    | `instructionId` | string | Yes      | The instruction ID |
    | `title`         | string | No       | New title          |
    | `content`       | string | No       | New content        |
  </Accordion>

  <Accordion title="deleteCustomInstruction" icon="trash">
    Delete a custom instruction permanently.

    **Parameters:**

    | Name            | Type   | Required | Description        |
    | --------------- | ------ | -------- | ------------------ |
    | `instructionId` | string | Yes      | The instruction ID |
  </Accordion>

  <Accordion title="getCustomInstructionSuggestions" icon="lightbulb">
    Retrieve suggested preset custom instructions (templates) to adopt or adapt as starting points for your own.

    **Parameters:** None
  </Accordion>
</AccordionGroup>

## Folders

<AccordionGroup>
  <Accordion title="getAllFolders" icon="folder-tree">
    Retrieve all folders with pagination, search, and sorting. Folders organize projects — use a folder's ID as the `folderId` parameter of `uploadFile` or `beginChunkedUpload` to place new projects in it.

    **Parameters:**

    | Name             | Type   | Required | Description                        |
    | ---------------- | ------ | -------- | ---------------------------------- |
    | `page`           | number | No       | Page number (default: 1)           |
    | `take`           | number | No       | Items per page (1–50, default: 10) |
    | `search`         | string | No       | Search query                       |
    | `orderBy`        | string | No       | Sort field (default: `id`)         |
    | `orderDirection` | string | No       | `asc` or `desc` (default: `desc`)  |
  </Accordion>

  <Accordion title="getFolderOrderLanguagePairs" icon="language">
    Get the distinct source/target language pairs from eligible orders in a folder. Use `status=unassigned` (default) for pairs available to assign to a translator, or `status=assigned` for pairs available to unassign.

    **Parameters:**

    | Name       | Type   | Required | Description                          |
    | ---------- | ------ | -------- | ------------------------------------ |
    | `folderId` | string | Yes      | The folder ID to inspect             |
    | `status`   | string | No       | `unassigned` (default) or `assigned` |
  </Accordion>

  <Accordion title="assignTranslatorToFolderOrders" icon="user-plus">
    Batch assign a translator to all eligible (unassigned, completed) orders in a folder, optionally filtered by language pair. Returns the number of orders assigned.

    **Parameters:**

    | Name             | Type   | Required | Description                                  |
    | ---------------- | ------ | -------- | -------------------------------------------- |
    | `folderId`       | string | Yes      | The folder ID whose orders to assign         |
    | `translatorId`   | string | Yes      | The translator ID to assign                  |
    | `deadline`       | string | No       | Deadline in ISO 8601 format                  |
    | `sourceLanguage` | string | No       | Only assign orders with this source language |
    | `targetLanguage` | string | No       | Only assign orders with this target language |
  </Accordion>

  <Accordion title="unassignTranslatorFromFolderOrders" icon="user-minus">
    Batch unassign the translator from all eligible (assigned, ongoing) orders in a folder, optionally filtered by language pair. Returns the number of orders unassigned.

    **Parameters:**

    | Name             | Type   | Required | Description                                    |
    | ---------------- | ------ | -------- | ---------------------------------------------- |
    | `folderId`       | string | Yes      | The folder ID whose orders to unassign         |
    | `sourceLanguage` | string | No       | Only unassign orders with this source language |
    | `targetLanguage` | string | No       | Only unassign orders with this target language |
  </Accordion>

  <Accordion title="bulkExportFoldersXlsx" icon="file-zipper">
    Bulk export orders in folders as a single XLSX file with one sheet per order/language combination. Returns a short-lived download URL (expires after 60 minutes) — the file bytes never pass through the AI assistant's context.

    **Parameters:**

    | Name              | Type  | Required | Description                                             |
    | ----------------- | ----- | -------- | ------------------------------------------------------- |
    | `folderIds`       | array | Yes      | Folder IDs containing the orders to export              |
    | `targetLanguages` | array | Yes      | Target language codes to include (e.g., `["tr", "en"]`) |
  </Accordion>
</AccordionGroup>

## Content Management

<AccordionGroup>
  <Accordion title="exportContent" icon="file-export">
    Export content translations as JSON, filtered by target language(s), tag(s), and order ID(s). Single-language exports return a flat key-value map; multi-language exports return a map grouped by language code.

    **Parameters:**

    | Name              | Type   | Required | Description                                          |
    | ----------------- | ------ | -------- | ---------------------------------------------------- |
    | `targetLanguage`  | string | No       | Filter by a single target language code (e.g., `tr`) |
    | `targetLanguages` | array  | No       | Filter by multiple target language codes             |
    | `tag`             | string | No       | Filter by a single tag                               |
    | `tags`            | array  | No       | Filter by multiple tags                              |
    | `orderIds`        | array  | No       | Filter by one or more order IDs                      |
  </Accordion>

  <Accordion title="importContent" icon="file-import">
    Import translation units (source + target text pairs) into your content database. Useful for bulk-loading translations from external systems or TMS exports.

    **Parameters:**

    | Name             | Type   | Required | Description                                              |
    | ---------------- | ------ | -------- | -------------------------------------------------------- |
    | `targetLanguage` | string | Yes      | Target language code (e.g., `tr`, `en`, `de`)            |
    | `translations`   | array  | Yes      | Array of `{ sourceText, targetText, elementId?, type? }` |
  </Accordion>
</AccordionGroup>

## Utilities

<AccordionGroup>
  <Accordion title="healthCheck" icon="heart-pulse">
    Check the health status of the Ollang API.

    **Parameters:** None
  </Accordion>

  <Accordion title="downloadAndReadSubtitle" icon="file-lines">
    Download and parse subtitle files from URLs. Supports SRT, VTT, ASS, and SSA formats.

    **Parameters:**

    | Name     | Type   | Required | Description                                                       |
    | -------- | ------ | -------- | ----------------------------------------------------------------- |
    | `url`    | string | Yes      | URL of the subtitle file                                          |
    | `format` | string | No       | Format hint: `auto`, `srt`, `vtt`, `ass`, `ssa` (default: `auto`) |
  </Accordion>

  <Accordion title="downloadAndReadJSON" icon="braces">
    Download and parse JSON files from URLs.

    **Parameters:**

    | Name  | Type   | Required | Description          |
    | ----- | ------ | -------- | -------------------- |
    | `url` | string | Yes      | URL of the JSON file |
  </Accordion>

  <Accordion title="downloadAndReadDITA" icon="code">
    Download and parse DITA/XML documentation files from URLs.

    **Parameters:**

    | Name  | Type   | Required | Description                                         |
    | ----- | ------ | -------- | --------------------------------------------------- |
    | `url` | string | Yes      | URL of the DITA file (.dita, .ditamap, or .ditaval) |
  </Accordion>
</AccordionGroup>