Text Translation¶

Submit text for translation or creation through the Falara pipeline.

POST /v1/jobs¶

Create a translation or creation job from inline text.

Authentication

Header: X-API-Key: your_api_key

Content-Type: application/json Status: 202 Accepted

Request Body¶

Field	Type	Required	Default	Description
`mode`	`"translation"` \| `"creation"`	yes	—	`"translation"` translates source text. `"creation"` generates new content in the target language based on instructions.
`source_lang`	`string`	yes	—	BCP-47 source language code (e.g., `"de"`, `"en"`).
`target_lang`	`string` \| `list[string]`	yes	—	BCP-47 target language code, or a list of codes for multi-language jobs. When a list is provided, one job per language is created sharing a `batch_id`.
`text`	`string`	yes*	—	Source text to translate. *Either `text` or `texts` is required.
`texts`	`list[string \\| object]`	yes*	—	List of source texts for batch-in-one-job translation. Each item can be a plain string or an object with `text` and optional `metadata` (see Metadata Passthrough). *Either `text` or `texts` is required.
`domain`	`string`	no	`null`	Subject domain (e.g., `"legal"`, `"medical"`, `"marketing"`). Guides terminology choices.
`tone`	`string`	no	`null`	Desired tone of voice (e.g., `"formal"`, `"casual"`, `"technical"`).
`instructions`	`string`	no	`null`	Free-text instructions for the translator (max 2000 chars).
`glossary_ids`	`list[string]`	no	`[]`	List of glossary IDs to apply during translation.
`glossary_priority`	`"account_first"` \| `"private_first"`	no	`"account_first"`	When multiple glossaries define the same term, account-scoped glossaries take precedence (`account_first`) or private ones do (`private_first`).
`glossary`	`list[object]`	no	`[]`	Inline glossary entries (`[{"source": "...", "target": "..."}]`). Merged with glossary_ids entries.
`style_reference`	`string`	no	`null`	Reference text in the target language to match style and tone.
`constraints`	`list[object]`	no	`null`	Output constraints as a list of constraint objects, e.g. `[{"type": "max_chars", "value": 100}]`.
`text_type`	`string`	no	`null`	Free-form content category, e.g. `"marketing"`, `"legal"`, `"technical"`, `"software_ui"`.
`tier`	`string`	no	`null`	Deprecated. Use `quality` instead.
`source_review`	`boolean` \| `null`	no	`null`	Enable source text quality check before translation. `null` uses the tier default.
`quality`	`"standard"` \| `"premium"`	no	`"standard"`	Translation quality level. `premium` uses Claude Opus (1.5x word quota). See Quality Levels.
`project_name`	`string`	no	`null`	Project label for organizing jobs. Filterable in `GET /v1/jobs`.

`text` vs `texts`¶

	`text`	`texts`
Input	Single string	List of strings
Segmentation	Supervisor splits into segments	Each string = one segment
Use case	Articles, documents, paragraphs	UI labels, product names, short strings
Context flow	Sequential with prior-segment context	Sequential within the list

Response (202) -- Single Language¶

When target_lang is a string:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Job created successfully."
}

Response (202) -- Multi-Language¶

When target_lang is a list:

{
  "batch_id": "batch_550e8400-e29b-41d4-a716-446655440000",
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440001",
      "target_language": "en",
      "status": "queued"
    },
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440002",
      "target_language": "fr",
      "status": "queued"
    }
  ],
  "total_jobs": 2
}

Examples¶

Simple Translation¶

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Die Qualität unserer Produkte spricht für sich.",
    "domain": "marketing",
    "tone": "professional"
  }'

import os
import requests

response = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": os.environ["FALARA_API_KEY"]},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Die Qualität unserer Produkte spricht für sich.",
        "domain": "marketing",
        "tone": "professional",
    },
)
print(response.json())

const response = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: "en",
    text: "Die Qualität unserer Produkte spricht für sich.",
    domain: "marketing",
    tone: "professional",
  }),
});
const data = await response.json();
console.log(data);

With Glossary¶

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Die Qualität unserer Produkte spricht für sich.",
    "glossary_ids": ["gloss_abc12345"],
    "glossary": [
      { "source": "Produkte", "target": "products" }
    ],
    "glossary_priority": "account_first"
  }'

import os
import requests

response = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": os.environ["FALARA_API_KEY"]},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Die Qualität unserer Produkte spricht für sich.",
        "glossary_ids": ["gloss_abc12345"],
        "glossary": [
            {"source": "Produkte", "target": "products"}
        ],
        "glossary_priority": "account_first",
    },
)
print(response.json())

const response = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: "en",
    text: "Die Qualität unserer Produkte spricht für sich.",
    glossary_ids: ["gloss_abc12345"],
    glossary: [
      { source: "Produkte", target: "products" }
    ],
    glossary_priority: "account_first",
  }),
});
const data = await response.json();
console.log(data);

With Source Review¶

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Die Qualität unserer Produkte spricht für sich.",
    "source_review": true
  }'

import os
import requests

response = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": os.environ["FALARA_API_KEY"]},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Die Qualität unserer Produkte spricht für sich.",
        "source_review": True,
    },
)
print(response.json())

const response = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: "en",
    text: "Die Qualität unserer Produkte spricht für sich.",
    source_review: true,
  }),
});
const data = await response.json();
console.log(data);

Premium Quality¶

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Unsere Premium-Produkte setzen Maßstäbe.",
    "quality": "premium",
    "project_name": "Q2 Marketing Campaign"
  }'

import os
import requests

response = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": os.environ["FALARA_API_KEY"]},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Unsere Premium-Produkte setzen Maßstäbe.",
        "quality": "premium",
        "project_name": "Q2 Marketing Campaign",
    },
)
print(response.json())

const response = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: "en",
    text: "Unsere Premium-Produkte setzen Maßstäbe.",
    quality: "premium",
    project_name: "Q2 Marketing Campaign",
  }),
});
const data = await response.json();
console.log(data);

Creation Mode¶

Creation Mode

Use mode: "creation" to generate new content in the target language. Provide instructions to describe what content should be created.

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "creation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Falara ist eine KI-gestützte Übersetzungsplattform für Unternehmen.",
    "instructions": "Write a compelling landing page headline and subheadline based on this product description.",
    "tone": "professional",
    "domain": "marketing"
  }'

import os
import requests

response = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": os.environ["FALARA_API_KEY"]},
    json={
        "mode": "creation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Falara ist eine KI-gestützte Übersetzungsplattform für Unternehmen.",
        "instructions": "Write a compelling landing page headline and subheadline based on this product description.",
        "tone": "professional",
        "domain": "marketing",
    },
)
print(response.json())

const response = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "creation",
    source_lang: "de",
    target_lang: "en",
    text: "Falara ist eine KI-gestützte Übersetzungsplattform für Unternehmen.",
    instructions: "Write a compelling landing page headline and subheadline based on this product description.",
    tone: "professional",
    domain: "marketing",
  }),
});
const data = await response.json();
console.log(data);

Multi-Language Translation¶

Multi-Language

Pass a list of language codes to target_lang to create one job per target language. All jobs share a batch_id for easy tracking.

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": ["en", "fr", "es"],
    "text": "Die Qualität unserer Produkte spricht für sich.",
    "domain": "marketing",
    "project_name": "Website Localization"
  }'

import os
import requests

response = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": os.environ["FALARA_API_KEY"]},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": ["en", "fr", "es"],
        "text": "Die Qualität unserer Produkte spricht für sich.",
        "domain": "marketing",
        "project_name": "Website Localization",
    },
)
print(response.json())

const response = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: ["en", "fr", "es"],
    text: "Die Qualität unserer Produkte spricht für sich.",
    domain: "marketing",
    project_name: "Website Localization",
  }),
});
const data = await response.json();
console.log(data);

Response:

{
  "batch_id": "batch_550e8400-e29b-41d4-a716-446655440000",
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440001",
      "target_language": "en",
      "status": "queued"
    },
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440002",
      "target_language": "fr",
      "status": "queued"
    },
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440003",
      "target_language": "es",
      "status": "queued"
    }
  ],
  "total_jobs": 3
}

Metadata Passthrough¶

When using texts, each item can optionally include a metadata object. Falara stores this metadata unchanged and returns it alongside each translated segment in the result. This enables connector integrations to track which translation belongs to which source record — without Falara needing to understand the metadata structure.

Opaque pass-through

Falara does not parse, validate, or index metadata. It is stored as-is and returned as-is. Maximum size: 8 KB per segment.

Request with Metadata¶

{
  "mode": "translation",
  "source_lang": "en",
  "target_lang": "de",
  "texts": [
    {
      "text": "Complete purchase",
      "metadata": {
        "resource_id": "product_123",
        "field": "checkout_button",
        "max_characters": 25
      }
    },
    {
      "text": "Add to cart",
      "metadata": {
        "resource_id": "product_123",
        "field": "cart_button"
      }
    },
    "Free shipping on all orders"
  ]
}

Mixed arrays

You can mix plain strings and objects with metadata in the same texts array. Strings are treated as segments without metadata.

Result with Metadata¶

When any segment in the request included metadata, the translation field in GET /v1/jobs/{job_id}/result returns an array of objects instead of a plain string:

{
  "job_id": "550e8400-...",
  "status": "completed",
  "translation": [
    {
      "text": "Kauf abschließen",
      "metadata": {
        "resource_id": "product_123",
        "field": "checkout_button",
        "max_characters": 25
      }
    },
    {
      "text": "In den Warenkorb",
      "metadata": {
        "resource_id": "product_123",
        "field": "cart_button"
      }
    },
    {
      "text": "Kostenloser Versand für alle Bestellungen",
      "metadata": null
    }
  ],
  "qa_score": 95.0,
  "word_count": { "source": 11, "target": 13 },
  "billed_words": 13,
  "delivery_notes": [],
  "warning": null
}

Segments without metadata receive "metadata": null in the response.

Backward compatible

If no segment in the request includes metadata, the translation field remains a plain string or list of strings — existing integrations are unaffected.

Errors¶

Status	Description
`401`	Invalid or missing API key.
`422`	Validation error (missing required fields, invalid language code, etc.).
`429`	Rate limit or word quota exceeded.

POST /v1/jobs/batch-text¶

Submit text for multi-language translation in a single request. This endpoint enforces multi-language mode: target_lang must be a list of language codes. One job per target language is created, all sharing a batch_id.

Multi-language only

target_lang must be a list (e.g. ["en", "fr"]). Passing a single string returns 422 Unprocessable Entity. For single-language jobs, use POST /v1/jobs instead.

Authentication

Header: X-API-Key: your_api_key

Content-Type: application/json Status: 202 Accepted

Request Body¶

Field	Type	Required	Default	Description
`mode`	`"translation"` \| `"creation"`	yes	—	`"translation"` or `"creation"`.
`source_lang`	`string`	yes	—	BCP-47 source language code.
`target_lang`	`list[string]`	yes	—	List of BCP-47 target language codes. Must be a list. Returns `422` if a string is provided.
`text`	`string`	yes*	—	Source text. *Either `text` or `texts` is required.
`texts`	`list[string \\| object]`	yes*	—	List of source texts (batch-in-one-job). Each item can be a plain string or an object with `text` and optional `metadata` (see Metadata Passthrough). *Either `text` or `texts` is required.
`domain`	`string`	no	`null`	Subject domain (shared across all jobs).
`tone`	`string`	no	`null`	Tone of voice (shared across all jobs).
`instructions`	`string`	no	`null`	Free-text instructions (shared across all jobs).
`glossary_ids`	`list[string]`	no	`[]`	Glossary IDs (shared across all jobs).
`glossary_priority`	`"account_first"` \| `"private_first"`	no	`"account_first"`	Glossary precedence when the same term is defined in multiple glossaries.
`constraints`	`list[object]`	no	`null`	Output constraints, e.g. `[{"type": "max_chars", "value": 100}]` (shared across all jobs).
`text_type`	`string`	no	`null`	Content category, e.g. `"marketing"`, `"legal"` (shared across all jobs).
`source_review`	`boolean` \| `null`	no	`null`	Enable source review. `null` uses the tier default (shared across all jobs).
`quality`	`"standard"` \| `"premium"`	no	`"standard"`	Quality level (shared across all jobs).
`project_name`	`string`	no	`null`	Project label (shared across all jobs).

Response (202)¶

{
  "batch_id": "batch_550e8400-e29b-41d4-a716-446655440000",
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440001",
      "target_language": "en",
      "status": "queued"
    },
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440002",
      "target_language": "fr",
      "status": "queued"
    }
  ],
  "total_jobs": 2
}

Examples¶

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs/batch-text \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": ["en", "fr"],
    "text": "Unsere Plattform vereinfacht den Übersetzungsprozess.",
    "domain": "marketing",
    "project_name": "Website Relaunch"
  }'

import os
import requests

response = requests.post(
    "https://app.falara.io/v1/jobs/batch-text",
    headers={"X-API-Key": os.environ["FALARA_API_KEY"]},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": ["en", "fr"],
        "text": "Unsere Plattform vereinfacht den Übersetzungsprozess.",
        "domain": "marketing",
        "project_name": "Website Relaunch",
    },
)
print(response.json())

const response = await fetch("https://app.falara.io/v1/jobs/batch-text", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: ["en", "fr"],
    text: "Unsere Plattform vereinfacht den Übersetzungsprozess.",
    domain: "marketing",
    project_name: "Website Relaunch",
  }),
});
const data = await response.json();
console.log(data);

Errors¶

Status	Description
`401`	Invalid or missing API key.
`422`	Validation error (e.g. `target_lang` is not a list, missing required fields).
`429`	Rate limit or word quota exceeded.

Text Translation¶

POST /v1/jobs¶

Request Body¶

text vs texts¶

Response (202) -- Single Language¶

Response (202) -- Multi-Language¶

Examples¶

Simple Translation¶

With Glossary¶

With Source Review¶

Premium Quality¶

Creation Mode¶

Multi-Language Translation¶

Metadata Passthrough¶

Request with Metadata¶

Result with Metadata¶

Errors¶

POST /v1/jobs/batch-text¶

Request Body¶

Response (202)¶

Examples¶

Errors¶

`text` vs `texts`¶