MQM Tool API // Batch Evaluation Workflow Example

All API endpoints are relative to the Base URL of your installation.

If you are using a self-hosted version or a different environment, your Base URL will correspond to your specific domain or IP address.

Authentication

API tokens are required only for creating projects (importing data). Read operations (monitoring progress, exporting results) are public for anyone with a valid project UUID.

Authorization: Bearer YOUR_API_TOKEN

Testing Authentication

To verify your token is valid, you can send an empty POST request to the import endpoint. A 400 Bad Request (missing segments) means your token was accepted, while a 401 Unauthorized means your token is invalid or missing.

curl -X POST "{{BASE_URL}}/api/import" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

1. Batch Project Creation

Instead of creating projects one by one in the UI, you can script the creation of dozens of projects instantly.

Important: When you create a project via the API, the response will contain the id of the new project. You must save this ID to construct the link for your linguists.

Option A: Importing JSON Payload

# Create a project with extra metadata (context, IDs)
curl -X POST "{{BASE_URL}}/api/import" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project_DE_Wave_01",
    "segments": [
      {
        "segment_id": "1001",
        "source": "High-throughput engineering",
        "target": "Hochdurchsatz-Engineering",
        "context": "Marketing headline",
        "system_id": "GPT-4o"
      },
      {
        "segment_id": "1002",
        "source": "Linguistic data lifecycle",
        "target": "Linguistischer Datenlebenszyklus",
        "context": "App description",
        "system_id": "DeepL"
      }
    ]
  }'

Option B: Importing TSV/CSV/JSONL

curl -X POST "{{BASE_URL}}/api/import" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@/path/to/batch_job.tsv"

Response Example

The API will return a JSON object containing the new project's ID:

{
  "success": true,
  "id": "8bd96d5a-5fc7-4581-9b93-516999908cf2",
  "name": "Batch_Job_01",
  "count": 150
}

2. Distributing Work to Linguists

Linguists access their projects via unique URLs constructed using the project id returned from the import step.

For example, if the API returned ID 8bd96d5a-5fc7-4581-9b93-516999908cf2, the link for your linguist is:

https://alconost.mt/mqm-tool/project/8bd96d5a-5fc7-4581-9b93-516999908cf2

3. Monitoring Progress

To check the progress of a project, you retrieve its currently annotated segments using its ID.

Step 1: Get the current data

curl "{{BASE_URL}}/api/projects/8bd96d5a-5fc7-4581-9b93-516999908cf2/export?format=jsonl" \
  -o "status_check.jsonl"

Step 2: Compare count of completed segments vs total

To calculate progress, use a script to parse the export file (JSONL/TSV). A segment is complete if the annotations array is not empty (contains either error tags or the "no-error" category).

4. Bulk Export & Analysis

Once the wave is complete, download all data for analysis using the same export endpoint.

Export Formats

Supported formats: jsonl, tsv, csv. Pass the format as a query parameter:

curl "{{BASE_URL}}/api/projects/{id}/export?format=jsonl"

JSONL Response Structure

{
  "segment_id": "1001",
  "system_id": "GPT-4o",
  "doc_id": "batch-01",
  "context": "Marketing headline",
  "src_lang": "en",
  "tgt_lang": "de",
  "source": "High-throughput engineering",
  "target": "Hochdurchsatz-Engineering",
  "correction": "",
  "annotator_id": "A-5BFF0F0F",
  "timestamp": "2026-01-28T08:25:41.637Z",
  "annotations": [
    {
      "start": 13,
      "end": 24,
      "category": "Terminology",
      "severity": "Major",
      "comment": "Incorrect technical term",
      "timestamp": "2026-01-28T08:20:49.726Z"
    }
  ]
}
{
  "segment_id": "1002",
  "system_id": "DeepL",
  "doc_id": "batch-01",
  "context": "App description",
  "src_lang": "en",
  "tgt_lang": "de",
  "source": "Linguistic data lifecycle",
  "target": "Linguistischer Datenlebenszyklus",
  "correction": "",
  "annotator_id": "A-5BFF0F0F",
  "annotations": [
    {
      "start": 0,
      "end": 0,
      "category": "no-error",
      "severity": "",
      "comment": "",
      "timestamp": "2026-01-28T08:25:41.637Z"
    }
  ]
}

Aggregating Results

You can aggregate results across multiple projects by merging the exported JSONL/TSV files into a master dataset for wave-level analysis.