Integration API

Describe the calling token: its project, the project's source language, the base branch, branch scope, role and non-secret settings. Any valid token may introspect itself. Secrets (the token itself, its IP allowlist, webhook ids) are never returned.

{
  "project": {
    "id": "6659f0c3a1b2c3d4e5f60718",
    "name": "Acme Web",
    "langs": ["en", "lv", "ru"]
  },
  "branch": "main",
  "branchScope": "fixed",
  "sourceLanguage": "en",
  "role": "developer",
  "token": {
    "name": "ci-token",
    "autoPublish": false,
    "expiresAt": null
  }
}

List labels on a branch, sorted by key ascending. Translator role or higher.

{
  "branch": "main",
  "total": 2,
  "labels": [
    {
      "key": "app.title",
      "values": { "en": "My App" },
      "status": "draft",
      "tags": [],
      "updatedAt": "2026-07-19T09:12:04.771Z"
    },
    {
      "key": "greeting.hello",
      "values": { "en": "Hello", "lv": "Sveiki" },
      "status": "approved",
      "tags": ["ui"],
      "updatedAt": "2026-07-19T09:12:05.133Z"
    }
  ]
}

Download labels as a translation file. The JSON format is a flat, language-keyed object; every configured language is a top-level key. Translator role or higher.

The response is served as a file download (for JSON, Content-Type: application/json with a Content-Disposition attachment). A key appears under a language only when it has a value there.

{
  "en": {
    "app.title": "My App",
    "greeting.hello": "Hello"
  },
  "lv": {
    "greeting.hello": "Sveiki"
  }
}

Create or update a single label (upsert by key) on a branch. Translator role or higher; context and tags need the developer role.

At least one of values, status, tags or context is required. created is true when the key did not exist on the branch before. context is returned when the request sent one.

A request that only sets context or tags for a key that does not exist fails with label_not_found and creates nothing. A value over the label's character limit fails with character_limit_exceeded (a charLimit sent in the same request applies to its values). A new key beyond your plan's source-key limit fails with source_key_limit_reached.

{
  "key": "brand.name",
  "branch": "main",
  "created": true,
  "values": { "en": "Translatize" },
  "status": "draft",
  "tags": [],
  "context": {
    "description": "Product name in the page header",
    "doNotTranslate": true
  }
}

Upsert up to 500 labels in one call. Each item is upserted on its own – a rejected item lands in failed[] instead of aborting the batch. Translator role or higher; any item with context or tags needs the developer role.

Failures are collected per key: unknown_languages, character_limit_exceeded, label_not_found (a context- or tags-only item for a missing key), or invalid_input for an item that is malformed. The rest of the batch still applies. If the new keys in the batch would go over your plan's source-key limit, the whole request is refused up front with source_key_limit_reached (carrying limit, current and attempted).

{
  "updated": 1,
  "created": 2,
  "failed": [
    { "key": "checkout.old_title", "error": "label_not_found" }
  ]
}

List every branch in the project, each flagged with this token's access. main is always listed. Any valid token.

{
  "baseBranch": "main",
  "branchScope": "create-own",
  "branches": [
    {
      "name": "main",
      "description": "Main production branch",
      "basedOn": null,
      "createdAt": "2026-07-10T08:00:00.000Z",
      "createdByThisToken": false,
      "writable": true
    },
    {
      "name": "feat-checkout",
      "description": "checkout copy",
      "basedOn": "main",
      "createdAt": "2026-07-19T09:20:11.402Z",
      "createdByThisToken": true,
      "writable": true
    }
  ]
}

Create a branch forked from the token's base branch. Needs a create-own token and the developer role; a fixed-scope token is rejected with branch_scope_fixed.

Creating a branch copies the base branch's labels into it. The plan's branch limit is enforced (branch_limit_reached, with limit and current).

{
  "branch": {
    "name": "feat-checkout",
    "description": "checkout copy",
    "isDefault": false,
    "basedOn": "main",
    "createdBy": "6650aa11bb22cc33dd44ee55",
    "createdAt": "2026-07-19T09:20:11.402Z",
    "lastModified": "2026-07-19T09:20:11.402Z",
    "createdByName": "Alex Rivera"
  }
}

Diff a branch (source) against the token's base branch (target): changed, added and deleted keys, each with the differing per-language source/target values. Any valid token; the branch must be in the allowed set.

{
  "source": "feat-checkout",
  "target": "main",
  "differences": {
    "changed": [],
    "added": [
      {
        "key": "checkout.pay_button",
        "languages": {
          "en": { "sourceValue": "Pay now", "targetValue": null }
        }
      }
    ],
    "deleted": []
  },
  "summary": { "changed": 0, "added": 1, "deleted": 0, "total": 1 }
}

Flat per-key/per-language conflicts of a branch (source) against the base (target) – cases where both sides hold a different non-empty value. An empty conflicts array means the branch is safe to merge with the default strategy. Any valid token.

{
  "source": "feat-checkout",
  "target": "main",
  "conflicts": [
    {
      "key": "app.title",
      "lang": "lv",
      "sourceValue": "Veikals",
      "targetValue": "Sākums"
    }
  ],
  "hasConflicts": true,
  "conflictCount": 1
}

Merge a branch this token created into the token's base branch. Developer role, and the admin role when the base is main. The target is always the base, and the source branch is kept.

curl -X POST https://api.translatize.com/v1/integrations/projects/$PROJECT_ID/branches/feat-checkout/merge \
  -H "Authorization: Bearer $TRANSLATIZE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"strategy":"branch-changes"}'

The checks run in this order. The branch must be one this token created (not_token_branch). Merging into main needs an admin token: any other role gets admin_token_required_for_main – create an admin token for that job, or merge in the app. Then the project's QA merge gate checks what the merge would write. A blocking gate answers qa_gate_blocked with the gate and its issues. A token can never override it: fix the errors and merge again, or an admin or owner merges in the app with a written reason.

If the gate can't be checked while the project's mode is block, nothing is merged and you get qa_gate_unavailable (HTTP 503); in warn mode the merge goes ahead and the response's gate carries "error": "gate_unavailable". If someone writes to the branch between the gate check and the merge, nothing is merged and you get branch_changed_retry (HTTP 409) – run the merge again. overlappingKeys and overlappingCount come only with branch-changes: merged keys the base had also changed in the meantime, worth a second look.

{
  "message": "Branch merged successfully",
  "source": "feat-checkout",
  "target": "main",
  "strategy": "branch-changes",
  "gate": {
    "mode": "warn",
    "applies": true,
    "blocked": false,
    "errors": 0,
    "warnings": 2,
    "pairsChecked": 36,
    "overridden": false
  },
  "overlappingKeys": ["checkout.title"],
  "overlappingCount": 1
}

Mark the current values of some keys as the branch's new starting point, without changing them. Use it after you set a key on your branch back to the base's text, so a later branch-changes merge does not carry that key over a newer change on the base. Developer role; only branches this token created.

rebased counts the labels updated. Keys that don't exist on the branch are listed in notFound instead of failing the request.

{
  "rebased": 2,
  "notFound": ["checkout.old_title"]
}

Delete a branch this token created, with its labels – cleanup after a merge. Developer role. The base branch, main and branches created by anyone else cannot be deleted (not_token_branch).

Other tokens bound to the deleted branch stop working with token_inactive until someone points them at an existing branch in the app.

{
  "message": "Branch deleted successfully"
}

Start a background AI job that fills in missing translations on a branch. Returns HTTP 202 with the started job, or HTTP 200 with a no-op when nothing needs work. Any valid token, translator role included, on a plan with AI translation.

When nothing is eligible, the response is HTTP 200 with { "started": false, "nothingToTranslate": true, "reason": "already_translated", ... } (or no_source when the labels have no source text). An exhausted monthly allowance returns ai_quota_exceeded (with used, limit, remaining and estimated), and a project that already has a job running returns translation_already_running. Follow progress with the status endpoint below.

{
  "started": true,
  "branch": "main",
  "job": {
    "id": "6659f1a2b3c4d5e6f7081920",
    "status": "queued",
    "targetLangs": ["lv", "ru"],
    "counts": {
      "requestedLabels": 12,
      "translatedValues": 0,
      "failedValues": 0,
      "skippedValues": 0,
      "fromMemory": 0,
      "keptValues": 0
    },
    "chars": { "estimated": 840, "actual": 0 }
  }
}

The project's live translation job (or null), its most recent job, and the AI allowance of the subscription the project bills to. Any valid token.

fromMemory counts values filled from translation memory and keptValues the source text copied into "do not translate" labels; neither is part of translatedValues or billed. While a job waits to start, activeJob carries its position in line; once running, its requestedLabels and startedAt.

{
  "activeJob": null,
  "lastJob": {
    "id": "6659f1a2b3c4d5e6f7081920",
    "status": "completed",
    "branch": "main",
    "sourceLang": "en",
    "targetLangs": ["lv", "ru"],
    "counts": {
      "requestedLabels": 12,
      "translatedValues": 21,
      "failedValues": 0,
      "skippedValues": 0,
      "fromMemory": 3,
      "keptValues": 0
    },
    "chars": { "estimated": 840, "actual": 734 },
    "error": null,
    "startedAt": "2026-07-19T09:25:00.000Z",
    "finishedAt": "2026-07-19T09:25:48.311Z"
  },
  "aiQuota": { "used": 734, "limit": 2000000, "remaining": 1999266 }
}

The project's glossary terms plus those shared in its workspace: required translations per language, case sensitivity and prohibited terms. A project term wins over a workspace term with the same text. Translator role or higher.

{
  "terms": [
    {
      "id": "6659f0c3a1b2c3d4e5f60801",
      "term": "workspace",
      "translations": { "lv": "darbvieta" },
      "description": "A team's shared area",
      "caseSensitive": false,
      "prohibited": false,
      "category": "product",
      "scope": "project"
    }
  ]
}

Look up translation-memory matches for source texts, with placeholders mapped onto your text. Matches come from the project's own memory and, while the project shares its memory with its workspace, from other projects in the workspace that share theirs. Translator role or higher.

At most 3 matches per text; a text without a match returns an empty matches array. origin says where the entry came from: approved (an approved label), human_edit (a person edited the value) or manual (added or edited in the memory itself). quality runs from 0 to 1.

{
  "results": [
    {
      "text": "Save changes",
      "matches": [
        {
          "sourceText": "Save changes",
          "targetText": "Saglabāt izmaiņas",
          "match": 100,
          "quality": 1,
          "placeholderMapped": false,
          "origin": "approved"
        }
      ]
    }
  ]
}

Run the checks on a branch now. Translator role or higher. Changes no translation.

The inline response lists at most 200 open issues, errors first. A large branch, or one that is already being checked, continues in the background: HTTP 202 with { "branch": "feat-checkout", "background": true }. Read the result with the issues endpoint.

{
  "branch": "feat-checkout",
  "pairsChecked": 84,
  "counts": { "error": 1, "warning": 3, "info": 0 },
  "issues": [
    {
      "id": "6659f1a2b3c4d5e6f7081931",
      "branch": "feat-checkout",
      "key": "checkout.total",
      "lang": "lv",
      "checkId": "placeholders",
      "severity": "error",
      "code": "placeholder_missing",
      "params": { "placeholders": ["{amount}"], "list": "{amount}", "count": 1 },
      "source": "rule",
      "ignored": false,
      "createdAt": "2026-11-03T09:12:04.771Z"
    }
  ]
}

Stored issues of a branch, paged by cursor. Translator role or higher.

counts are the open issues of the branch, narrowed by key, lang and source but not by severity. Issues have the same shape as in the run response; AI review findings may add message and suggestion.

{
  "issues": [],
  "nextCursor": null,
  "counts": { "error": 1, "warning": 3, "info": 0 }
}

Preview the merge gate for merging a branch into the token's base branch, the only target a token merges into. Translator role or higher.

applies is false when the mode is off, or when the gate covers only merges into main and the base is another branch. A branch that doesn't exist answers source_branch_not_found.

{
  "source": "feat-checkout",
  "target": "main",
  "gate": {
    "mode": "block",
    "applies": true,
    "blocked": true,
    "errors": 1,
    "warnings": 3,
    "pairsChecked": 36,
    "issues": []
  }
}

Queue an AI review of translations on a branch. Professional and Agency plans, billed against the separate AI review allowance. Developer role. Findings are warnings at most and never block a merge.

A plan without AI review returns feature_not_available with "feature": "aiReview". Other errors: unknown_languages (a language the project can't review), nothing_to_review, too_many_pairs (narrow it with keys or langs), ai_review_quota_exceeded and ai_review_in_progress (one review per project at a time). The findings appear in the issues endpoint with source=ai.

{
  "jobId": "6659f1a2b3c4d5e6f7081930",
  "status": "queued",
  "pairs": 120,
  "estimatedCharacters": 9400
}

The latest AI review job on a branch this token may use (or null), with progress counts, the allowance and the project's source language. Translator role or higher.

trigger is auto for a review started by the project's "AI review after AI translation" setting. An empty langs means every target language.

{
  "job": {
    "id": "6659f1a2b3c4d5e6f7081930",
    "status": "completed",
    "branch": "feat-checkout",
    "trigger": "manual",
    "langs": [],
    "counts": { "total": 120, "reviewed": 120, "failed": 0, "issues": 7 },
    "estimatedCharacters": 9400,
    "charactersBilled": 9312,
    "error": null,
    "createdAt": "2026-11-03T09:30:00.000Z",
    "startedAt": "2026-11-03T09:30:01.000Z",
    "finishedAt": "2026-11-03T09:31:12.000Z"
  },
  "quota": { "enabled": true, "used": 9312, "limit": 1000000, "remaining": 990688, "month": "2026-11" },
  "sourceLanguage": "en"
}

Start a capture run. Returns HTTP 201. A project can start 30 runs in a rolling 24 hours; the next one gets capture_run_limit (HTTP 429, with Retry-After).

{ "runId": "6659f1a2b3c4d5e6f7081940" }

Ask which images the server already holds, so unchanged screens are not uploaded again.

A run that is already completed answers run_not_open (HTTP 409).

{ "existing": ["9f2c4e…"] }

Upload one screen as multipart/form-data. Returns HTTP 201. A run holds at most 500 screens (run_screen_limit).

links is the number of keys the screen was linked to. Errors: invalid_meta, meta_too_large, invalid_image, image_too_large, screenshot_quota_exceeded (storage full), run_screen_limit and run_not_open. A 503 with Retry-After means the server is busy; send that screen again after the wait.

{ "screenshotId": "6659f1a2b3c4d5e6f7081950", "deduped": false, "links": 12 }

Finish the run. Newer captures replace older ones of the same screen name, viewport and locale. Calling it again on a completed run returns the same result.

linked counts key links on the run's screens, ambiguous the links worth a check in the app, and superseded the older captures this run replaced.

{
  "run": {
    "id": "6659f1a2b3c4d5e6f7081940",
    "name": "e2e main",
    "branch": "main",
    "commitSha": "4f1c2ab",
    "status": "completed",
    "counts": { "screens": 18, "linked": 16, "ambiguous": 1, "superseded": 3 },
    "startedBy": { "type": "token", "name": "ci-token" },
    "createdAt": "2026-11-03T09:40:00.000Z",
    "completedAt": "2026-11-03T09:41:30.000Z"
  }
}

The project's distributions on branches this token may use. Translator role or higher.

publishFilter is all or approved, format is json-nested or json-flat, and latestVersion is the version the manifest serves now (after a rollback, the version you rolled back to).

{
  "distributions": [
    {
      "id": "6659f1a2b3c4d5e6f7081960",
      "name": "Web app",
      "publicId": "k3J9xQ2mP0aZ7vB1cD5eFg",
      "branch": "main",
      "publishFilter": "all",
      "format": "json-nested",
      "autoPublishOnMerge": false,
      "status": "active",
      "latestVersion": 4,
      "manifestUrl": "https://cdn.translatize.com/d/k3J9xQ2mP0aZ7vB1cD5eFg/manifest.json"
    }
  ]
}

Publish the distribution's branch as a new release. Returns HTTP 201. Developer role, and the distribution's branch must be in the token's allowed set (branch_not_allowed). Send an empty JSON body – the distribution decides branch, format and filter.

Publishing works whether or not the account holds delivery blocks; the CDN serves a distribution only while it does. A branch with nothing to publish (no values, or no approved labels with the approved filter) answers nothing_to_publish (HTTP 422).

{
  "release": {
    "version": 5,
    "labelCount": 312,
    "languages": {
      "en": { "path": "/d/k3J9xQ2mP0aZ7vB1cD5eFg/v5/en.json", "hash": "…", "bytes": 18211 }
    },
    "createdAt": "2026-11-02T09:12:04.771Z"
  },
  "manifestUrl": "https://cdn.translatize.com/d/k3J9xQ2mP0aZ7vB1cD5eFg/manifest.json"
}