Skip to content

API V1

Exports

Endpoints for requesting a resource export and checking their statuses

An export assembles the files of a project in the background and offers them as one ZIP file. Both operations need the resourcesView permission on the project.

Workflow

  1. Request a resource export. The response carries the export id; its status starts as SCHEDULED.
  2. Poll Get resource export status until the status is SUCCESS, ERROR or SKIPPED.
  3. On SUCCESS, download the ZIP file from downloadUrl.
POST  .../exports        ->  { "id": "reg_...", "status": "SCHEDULED" }
GET   .../exports/{id}   ->  { "id": "reg_...", "status": "SUCCESS", "downloadUrl": "https://..." }

The recipe Export translations (API V1) shows the whole flow in Shell and Python.

Status values

The export and each entry of resourceExports (one per file and language) use the same values:

Status Meaning
NEW, SCHEDULED The export waits to start.
PROCESSING LingoHub is writing the files.
SUCCESS Final. downloadUrl holds the link to the ZIP file.
ERROR Final. errorDetails says what went wrong.
SKIPPED Final. The export was cancelled or skipped; there is no file.

Request body

The body is optional. Without it, the export contains every file in every language of the project’s default branch.

Field Meaning
filePaths Exports only these files. Give each path with its language placeholder, for example config/locales/%{locale}/messages.yml, as Get project resource file status returns it in filePathWithLocalePlaceholder. A path the project doesn’t have returns 404.
iso2Slugs Exports only these languages. Use the language codes of the project, for example en or de-AT.
exportFormat Writes the files in another format than the project’s: strings.ios, xml.android.resources, properties or standard_json. Any other value returns 422.
branch Name of the project branch to export. An unknown name returns 422.
{
  "filePaths": ["config/locales/%{locale}/messages.yml"],
  "iso2Slugs": ["en", "de"],
  "exportFormat": "standard_json"
}

The values of exportFormat differ from the format IDs that the project status reports in supportedExportFormats. Those belong to the projectType parameter of Download a resource file.

downloadUrl is a pre-signed link that is valid for 24 hours. Every call of the status operation returns a fresh link, so read the export again if a link has expired. Each entry of resourceExports has its own downloadUrl for the single file. filePath is the name of the ZIP file.

Errors

Status Meaning
401 The API key is missing or invalid.
403 The key lacks the resourcesView permission on the project.
404 The workspace, the project, the export or a path in filePaths doesn’t exist.
422 exportFormat has an invalid value, or the branch doesn’t exist.

Operations

Operation Request
Request a resource export POST /v1/{workspaceUrl}/projects/{projectUrl}/exports
Get resource export status GET /v1/{workspaceUrl}/projects/{projectUrl}/exports/{id}