Review & QA¶

The Review API allows you to create review bundles from completed translation jobs, manage segment-level review workflows, and integrate with external review tools like Eurotext.

Plan Requirement

Review & QA features require an Enterprise plan.

Review Bundles¶

A review bundle groups translated segments for human review. Reviewers can approve, edit, or reject segments before final delivery.

Create Review Bundle¶

POST /v1/review/bundles

Create a review bundle from one or more completed translation jobs.

Authentication: X-API-Key header
Status: 201 Created

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/review/bundles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Marketing Review",
    "job_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "661f9511-f30c-52e5-b827-557766551111"
    ]
  }'

import requests

resp = requests.post(
    "https://app.falara.io/v1/review/bundles",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Q2 Marketing Review",
        "job_ids": [
            "550e8400-e29b-41d4-a716-446655440000",
            "661f9511-f30c-52e5-b827-557766551111",
        ],
    },
)
bundle = resp.json()

const resp = await fetch(
  "https://app.falara.io/v1/review/bundles",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Q2 Marketing Review",
      job_ids: [
        "550e8400-e29b-41d4-a716-446655440000",
        "661f9511-f30c-52e5-b827-557766551111",
      ],
    }),
  }
);
const bundle = await resp.json();

Request Body

Field	Type	Required	Description
`name`	string	yes	Human-readable bundle name
`job_ids`	list[string]	yes	Job IDs to include in the bundle
`reviewer_email`	string	no	Assign a reviewer by email

Response 201 Created

{
  "bundle_id": "bnd_abc123",
  "name": "Q2 Marketing Review",
  "status": "pending",
  "segment_count": 156,
  "created_at": "2026-04-16T10:00:00Z"
}

List Review Bundles¶

GET /v1/review/bundles

List all review bundles for your account.

Authentication: X-API-Key header

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `in_review`, `completed`, `archived`
`limit`	integer	Max results (default: 20)
`offset`	integer	Pagination offset

cURL

curl -X GET "https://app.falara.io/v1/review/bundles?status=pending" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200 OK

{
  "bundles": [
    {
      "bundle_id": "bnd_abc123",
      "name": "Q2 Marketing Review",
      "status": "in_review",
      "segment_count": 156,
      "reviewed_count": 45,
      "created_at": "2026-04-16T10:00:00Z"
    }
  ],
  "total": 1
}

Get Bundle Details¶

GET /v1/review/bundles/{bundle_id}

Get detailed information about a review bundle, including segments.

Authentication: X-API-Key header

cURL

curl -X GET https://app.falara.io/v1/review/bundles/bnd_abc123 \
  -H "X-API-Key: YOUR_API_KEY"

Response 200 OK

{
  "bundle_id": "bnd_abc123",
  "name": "Q2 Marketing Review",
  "status": "in_review",
  "segments": [
    {
      "segment_id": "seg_001",
      "source": "Hello, world!",
      "target": "Hallo, Welt!",
      "status": "pending",
      "source_lang": "en",
      "target_lang": "de"
    }
  ],
  "segment_count": 156,
  "reviewed_count": 45
}

Get Review Progress¶

GET /v1/review/bundles/{bundle_id}/progress

Get real-time progress statistics for a review bundle.

Authentication: X-API-Key header

cURL

curl -X GET https://app.falara.io/v1/review/bundles/bnd_abc123/progress \
  -H "X-API-Key: YOUR_API_KEY"

Response 200 OK

{
  "bundle_id": "bnd_abc123",
  "total_segments": 156,
  "approved": 45,
  "edited": 12,
  "rejected": 3,
  "pending": 96,
  "progress_percent": 38.5
}

Bulk Approve Segments¶

POST /v1/review/bundles/{bundle_id}/bulk-approve

Approve multiple segments at once.

Authentication: X-API-Key header

cURL

curl -X POST https://app.falara.io/v1/review/bundles/bnd_abc123/bulk-approve \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_ids": ["seg_001", "seg_002", "seg_003"]
  }'

Response 200 OK

{
  "approved_count": 3
}

Mark Review Complete¶

POST /v1/review/bundles/{bundle_id}/reviewer-done

Mark the bundle as reviewed by the current reviewer.

Authentication: X-API-Key header

cURL

curl -X POST https://app.falara.io/v1/review/bundles/bnd_abc123/reviewer-done \
  -H "X-API-Key: YOUR_API_KEY"

Response 200 OK

{
  "status": "completed"
}

Archive Bundle¶

POST /v1/review/bundles/{bundle_id}/archive

Archive a completed review bundle.

Authentication: X-API-Key header

cURL

curl -X POST https://app.falara.io/v1/review/bundles/bnd_abc123/archive \
  -H "X-API-Key: YOUR_API_KEY"

Response 200 OK

{
  "status": "archived"
}

Restore Bundle¶

POST /v1/review/bundles/{bundle_id}/restore

Restore an archived bundle.

Authentication: X-API-Key header

Response 200 OK

{
  "status": "completed"
}

Delete Bundle¶

DELETE /v1/review/bundles/{bundle_id}

Permanently delete a review bundle.

Authentication: X-API-Key header

Response 204 No Content

External Review Tools¶

List Review Integrations¶

GET /v1/integrations/review

List configured external review tool integrations.

Authentication: X-API-Key header

Response 200 OK

{
  "integrations": [
    {
      "integration_id": "int_eurotext",
      "provider": "eurotext",
      "status": "active",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Add Review Integration¶

POST /v1/integrations/review

Configure a new external review tool.

Authentication: X-API-Key header

cURL

curl -X POST https://app.falara.io/v1/integrations/review \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "eurotext",
    "api_key": "YOUR_EUROTEXT_API_KEY",
    "base_url": "https://api.eurotext.de"
  }'

Response 201 Created

{
  "integration_id": "int_eurotext",
  "provider": "eurotext",
  "status": "active"
}

Test Integration¶

POST /v1/integrations/review/{integration_id}/test

Test the connection to an external review tool.

Authentication: X-API-Key header

Response 200 OK

{
  "status": "ok",
  "message": "Connection successful"
}

Submit to Eurotext¶

POST /v1/review/bundles/{bundle_id}/submit-eurotext

Submit a review bundle to Eurotext for professional review.

Authentication: X-API-Key header

cURL

curl -X POST https://app.falara.io/v1/review/bundles/bnd_abc123/submit-eurotext \
  -H "X-API-Key: YOUR_API_KEY"

Response 202 Accepted

{
  "eurotext_project_id": "ET-2026-12345",
  "status": "submitted"
}

Errors¶

Status	Reason
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Plan doesn't include review features
`404 Not Found`	Bundle or integration not found
`409 Conflict`	Bundle already submitted or archived
`422 Unprocessable Entity`	Jobs not in completed status