Files and translation jobs API

Use this API to upload source files, create translation jobs, check progress, and retrieve translated files. It is also the API used by Platform CLI sync. For identity, project discovery, and Queries, use the separate Projects and Queries API. See Choose an API for base URLs and authentication. The OpenAPI document for that API does not describe these file and job routes.

Base URL

https://hyperlocalise.com/api/v1

The CLI hyperlocalise.api_base_url default is https://hyperlocalise.com/api. Paths below are relative to that host, including /v1, except job reads. Read jobs from https://api.hyperlocalise.com/v1. See Read jobs.

Authentication

Create a key under Settings → API Keys. Send it on every request:

x-api-key: <secret>

Missing, invalid, or revoked keys return 401 with error: "unauthorized". An archived workspace returns 403 with error: "workspace_archived".

Permissions

Permission	Used by
`files:write`	Upload a source file
`files:read`	Download a stored file, reconstructed translation, or image variant
`jobs:write`	Create a translation job
`jobs:read`	Read job status and latest job for a source path

New keys receive all four permissions. A key only sees projects the key’s creator can access.

Errors

JSON errors use this envelope:

{
  "error": "machine_readable_code",
  "message": "Human-readable description"
}

Branch on error. message is for debugging and may change. File downloads return the raw body instead of JSON.

Files

Upload a source file

POST /v1/files Permission: files:write multipart/form-data. Maximum body size is 25 MiB.

Field	Required	Notes
`file`	yes	The source file bytes
`projectId`	yes	Platform project id
`sourcePath`	yes	Repository-style path, max 2048 characters
`sourceHash`	no
`commitSha`	no
`workflowRunId`	no
`sourceLocale`	no
`format`	no
`branch`	no

201 response for a native project (resource-keyed):

{
  "file": {
    "id": "file_...",
    "sourceFileVersionId": "...",
    "filename": "en.json",
    "contentType": "application/json",
    "byteSize": 128,
    "sha256": "...",
    "destination": "native"
  }
}

TMS-backed projects return destination: "external_tms" plus provider fields instead of the stored-file metadata. This is the same upload hyperlocalise sync push performs. It does not create a job.

Download a stored file

GET /v1/files/{fileId}/download Permission: files:read Returns the file bytes with Content-Type and Content-Disposition.

Jobs

Create a job

POST /v1/jobs Permission: jobs:write JSON body. Discriminate on type. String job

{
  "type": "string",
  "projectId": "project_123",
  "stringInput": {
    "sourceText": "Save changes",
    "sourceLocale": "en-US",
    "targetLocales": ["fr-FR"],
    "context": "Primary toolbar button",
    "maxLength": 24
  }
}

File job

{
  "type": "file",
  "projectId": "project_123",
  "fileInput": {
    "sourceFileId": "file_...",
    "fileFormat": "json",
    "sourceLocale": "en-US",
    "targetLocales": ["fr-FR"]
  }
}

sourceFileId must already exist in the project (upload first). Locales must match the project. 201 response:

{
  "job": {
    "id": "job_...",
    "type": "file",
    "status": "queued"
  }
}

The CLI does not call this endpoint during sync push. Platform automations and the UI create jobs after upload.

Read jobs

Job reads use a different host from the rest of this API:

https://api.hyperlocalise.com/v1

Send the same x-api-key. https://hyperlocalise.com/api/v1 no longer serves these routes.

Latest job for a source path

GET https://api.hyperlocalise.com/v1/jobs/latest?projectId={projectId}&sourcePath={sourcePath} Permission: jobs:read Returns the most recent succeeded file job for that source path, including outputFiles.

Get a job

GET https://api.hyperlocalise.com/v1/jobs/{jobId} Permission: jobs:read

{
  "job": {
    "id": "job_...",
    "projectId": "project_123",
    "type": "file",
    "status": "completed",
    "createdAt": "...",
    "updatedAt": "...",
    "completedAt": "...",
    "lastError": null,
    "outputFiles": [
      { "fileId": "file_...", "locale": "fr-FR", "filename": "fr.json" }
    ]
  }
}

Job status

GET https://api.hyperlocalise.com/v1/jobs/{jobId}/status Permission: jobs:read Smaller payload with id, projectId, kind, type, status, timestamps, and lastError.

curl --fail-with-body "https://api.hyperlocalise.com/v1/jobs/$JOB_ID/status" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY"

Translations and images

These reconstruct current project state. They do not require a job id. That is what sync pull uses.

Download a reconstructed translation

GET /v1/projects/{projectId}/translations/download?sourcePath={sourcePath}&locale={locale} Permission: files:read Returns the translated file bytes for that source path and target locale. To export only the segments that match Content Editor filters (CSV, TMX, XLIFF, XLSX), use Download in the Content Editor queue—not this endpoint.

Download an image variant

GET /v1/projects/{projectId}/images/download?sourcePath={sourcePath}&locale={locale} Permission: files:read Returns the localized image variant when one exists for that path and locale.

Example

Upload a source file with curl:

curl -X POST "https://hyperlocalise.com/api/v1/files" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -F "projectId=project_123" \
  -F "sourcePath=locales/en-US.json" \
  -F "file=@locales/en-US.json"

Download the French reconstruction:

curl -L "https://hyperlocalise.com/api/v1/projects/project_123/translations/download?sourcePath=locales/en-US.json&locale=fr-FR" \
  -H "x-api-key: $HYPERLOCALISE_API_KEY" \
  -o locales/fr-FR.json

Platform guide

Files and translation jobs API

Base URL

Authentication

Permissions

Errors

Files

Upload a source file

Download a stored file

Jobs

Create a job

Read jobs

Latest job for a source path

Get a job

Job status

Translations and images

Download a reconstructed translation

Download an image variant

Example

Next

​Base URL

​Authentication

​Permissions

​Errors

​Files

​Upload a source file

​Download a stored file

​Jobs

​Create a job

​Read jobs

​Latest job for a source path

​Get a job

​Job status

​Translations and images

​Download a reconstructed translation

​Download an image variant

​Example

​Next

Base URL

Authentication

Permissions

Errors

Files

Upload a source file

Download a stored file

Jobs

Create a job

Read jobs

Latest job for a source path

Get a job

Job status

Translations and images

Download a reconstructed translation

Download an image variant

Example

Next