API Overview¶

The Falara API lets you translate text and files programmatically, manage glossaries, style references, structure templates, and more. All endpoints follow REST conventions and return JSON.

Base URL¶

https://falara.io

All API paths are relative to this base URL (e.g. POST https://app.falara.io/v1/jobs).

Authentication¶

Every request (except /health) must include an API key in the X-API-Key header:

X-API-Key: fal_xxxxxxxxxxxxxxxxxxxxxxxx

You can create and manage API keys in the Falara dashboard or via the API Keys endpoints.

Keep your key secret

Never expose API keys in client-side code or public repositories. Rotate keys immediately if compromised.

Endpoints¶

Translation Jobs¶

Method	Path	Description
`POST`	`/v1/jobs`	Create a text translation job
`POST`	`/v1/jobs/batch-text`	Multi-language text translation
`POST`	`/v1/jobs/file`	Translate a file
`POST`	`/v1/jobs/batch-file`	Batch file translation
`POST`	`/v1/jobs/batch-csv`	Batch from CSV (Creation Mode)
`GET`	`/v1/jobs`	List jobs (paginated)
`GET`	`/v1/jobs/{job_id}`	Get job status
`GET`	`/v1/jobs/{job_id}/result`	Get translation result
`GET`	`/v1/jobs/{job_id}/download`	Download translated file
`GET`	`/v1/jobs/batch/{batch_id}`	Get batch status
`GET`	`/v1/jobs/batch/{batch_id}/download`	Download batch as ZIP
`PATCH`	`/v1/jobs/{job_id}/archive`	Archive a job
`PATCH`	`/v1/jobs/{job_id}/unarchive`	Unarchive a job
`POST`	`/v1/jobs/archive-all`	Archive all visible jobs
`POST`	`/v1/jobs/archive-batch`	Archive selected jobs
`POST`	`/v1/jobs/{job_id}/deliver`	Re-deliver file to Google Drive

Glossaries¶

Method	Path	Description
`GET`	`/v1/glossaries`	List glossaries
`POST`	`/v1/glossaries`	Create a glossary
`GET`	`/v1/glossaries/{id}`	Get a glossary
`PUT`	`/v1/glossaries/{id}`	Update a glossary
`DELETE`	`/v1/glossaries/{id}`	Delete a glossary
`POST`	`/v1/glossaries/{id}/entries`	Add an entry to a glossary
`POST`	`/v1/glossaries/upload/preview`	Preview a bulk import
`POST`	`/v1/glossaries/upload/commit`	Commit a bulk import

Style References¶

Method	Path	Description
`POST`	`/v1/style-references`	Create a style reference
`GET`	`/v1/style-references`	List style references
`GET`	`/v1/style-references/{id}`	Get a style reference
`PUT`	`/v1/style-references/{id}`	Update a style reference
`DELETE`	`/v1/style-references/{id}`	Delete a style reference

Structure Templates¶

Method	Path	Description
`GET`	`/v1/structure-templates`	List templates
`GET`	`/v1/structure-templates/{id}`	Get a template
`POST`	`/v1/structure-templates`	Create a template
`POST`	`/v1/structure-templates/from-file`	Derive a template from a document
`DELETE`	`/v1/structure-templates/{id}`	Delete a template

CSV Mappings¶

Method	Path	Description
`GET`	`/v1/csv-mappings`	List mappings
`GET`	`/v1/csv-mappings/{id}`	Get a mapping
`POST`	`/v1/csv-mappings`	Create a mapping
`DELETE`	`/v1/csv-mappings/{id}`	Delete a mapping

Google Drive¶

Method	Path	Description
`GET`	`/v1/integrations/google/connect`	Start OAuth flow
`GET`	`/v1/integrations/google/status`	Connection status
`DELETE`	`/v1/integrations/google/disconnect`	Disconnect Google Drive
`GET`	`/v1/integrations/google/picker-token`	Get a Picker token
`POST`	`/v1/services/google-drive/jobs`	Create jobs from Drive files

Webhooks¶

Method	Path	Description
`GET`	`/v1/webhooks/config`	Get webhook configuration
`PUT`	`/v1/webhooks/config`	Set webhook URL and secret
`DELETE`	`/v1/webhooks/config`	Disable webhook

Account & Keys¶

Method	Path	Description
`GET`	`/v1/account`	Get account info
`PATCH`	`/v1/account`	Rename account
`GET`	`/v1/account/usage`	Get word quota usage
`DELETE`	`/v1/account/data`	GDPR data deletion
`POST`	`/v1/api-keys`	Create an API key
`GET`	`/v1/api-keys`	List API keys
`DELETE`	`/v1/api-keys/{key_hash}`	Revoke an API key

Other¶

Method	Path	Description
`GET`	`/health`	Health check (no auth required)

Pagination¶

List endpoints use cursor-based pagination. Control the page size with limit and navigate forward with cursor.

Parameter	Type	Description
`limit`	integer	Maximum number of items to return. The default varies per endpoint.
`cursor`	string	Opaque cursor returned by a previous response. Omit for the first page.

Paginated responses wrap the result set in a standard envelope:

{
  "data": [
    { "id": "job_abc123", "status": "completed", "..." : "..." },
    { "id": "job_def456", "status": "processing", "..." : "..." }
  ],
  "pagination": {
    "cursor": "eyJpZCI6ICJqb2JfZGVmNDU2In0",
    "has_more": true
  }
}

To fetch the next page, pass the returned cursor value as a query parameter:

GET /v1/jobs?limit=20&cursor=eyJpZCI6ICJqb2JfZGVmNDU2In0

When has_more is false, you have reached the end of the list and cursor will be null.

Iterate until done

Keep requesting pages while has_more is true. Do not assume a fixed total count.

Error Format¶

All errors return a JSON body with a consistent structure:

{
  "detail": "A human-readable description of the error."
}

Common HTTP status codes:

Status	Meaning
`400`	Bad Request -- invalid parameters or payload
`401`	Unauthorized -- missing or invalid API key
`403`	Forbidden -- your plan does not allow this action
`404`	Not Found -- resource does not exist
`409`	Conflict -- resource already exists or state conflict
`413`	Payload Too Large -- file or text exceeds size limit
`422`	Unprocessable Entity -- validation error
`429`	Too Many Requests -- rate limit exceeded
`500`	Internal Server Error -- unexpected failure

Rate limiting

The API is limited to 50 requests per minute per API key. When you receive a 429 response, back off and retry after the period indicated by the Retry-After header (if present). Implement exponential backoff for production integrations.

Language Codes¶

Falara uses BCP 47 language tags. Common examples:

Code	Language
`de`	German
`en`	English
`es`	Spanish
`fr`	French
`it`	Italian
`ja`	Japanese
`ko`	Korean
`nl`	Dutch
`pl`	Polish
`pt`	Portuguese
`pt-BR`	Brazilian Portuguese
`ru`	Russian
`zh`	Chinese (Simplified)
`zh-TW`	Chinese (Traditional)

You can use any valid BCP 47 tag. The source language is auto-detected when omitted.

Text job exampleAuto-detect source

{
  "source_lang": "en",
  "target_lang": "de",
  "text": "Hello, world!"
}

{
  "target_lang": "de",
  "text": "Hello, world!"
}

Auto-detection

Omitting source_lang triggers automatic language detection. For best results, provide the source language explicitly when you know it.