Upload translation files

Owner/Admin/Editor; active workspace/project required. Current membership is checked again after locks. Up to 20 files, 20 MiB total, field name files. Private files expire in 24 hours. Returns mapping state; submit options to queue analysis. ZIP upload is rejected.

POST /api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/imports

Operation: uploadImport · Download OpenAPI

Access

Requires an authenticated Localisync panel session. The API checks current membership and permissions for workspace operations. See authentication and request rules.

sessionCookie

{
  "type": "apiKey",
  "in": "cookie",
  "name": "__Host-localisync-session",
  "description": "Production Secure HttpOnly session. Explicit local HTTP uses localisync-session."
}

Parameters

Name	Location	Required	Description
`workspaceId`	path	Yes	See constraints below.
`projectId`	path	Yes	See constraints below.
`branchId`	path	Yes	See constraints below.
`Origin`	header	Yes	Must equal the configured panel origin.
`X-CSRF-Token`	header	Yes	Session-bound token from auth/me.
`Idempotency-Key`	header	Yes	Reuse only with the identical request. A different payload returns 409.

workspaceId

{
  "type": "string",
  "format": "uuid"
}

projectId

{
  "type": "string",
  "format": "uuid"
}

branchId

{
  "type": "string",
  "format": "uuid"
}

Origin

{
  "type": "string",
  "format": "uri"
}

X-CSRF-Token

{
  "type": "string"
}

Idempotency-Key

{
  "type": "string",
  "format": "uuid"
}

Request body

Required: Yes.

multipart/form-data

Field	Type	Required	Constraints / description
`files`	Array of string	Yes	minItems: `1`; maxItems: `20`

{
  "type": "object",
  "required": [
    "files"
  ],
  "properties": {
    "files": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "type": "string",
        "contentEncoding": "binary"
      }
    }
  },
  "additionalProperties": false
}

Responses

201

Successful response. Queued jobs still require polling; completion is explicit.

Content type: application/json Schema reference: Transfer.

Field	Type	Required	Constraints / description
`id`	string	Yes	format: `"uuid"`; pattern: `"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`workspaceId`	string	Yes	format: `"uuid"`; pattern: `"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`projectId`	string	Yes	format: `"uuid"`; pattern: `"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`branchId`	string	Yes	format: `"uuid"`; pattern: `"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`kind`	`import`, `export`	Yes	—
`state`	`mapping`, `queued`, `processing`, `ready`, `applying`, `completed`, `failed`, `conflict`, `cancelled`, `expired`	Yes	—
`revision`	integer	Yes	maximum: `9007199254740991`
`options`	See schema	Yes	—
`files`	Array of object	Yes	—
`discovery`	Array of object	Yes	—
`summary`	object	Yes	—
`artifact`	See schema	Yes	—
`errorCode`	string or null	Yes	—
`createdAt`	string	Yes	format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"`
`updatedAt`	string	Yes	format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"`
`expiresAt`	string	Yes	format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"`

{
  "$ref": "#/components/schemas/Transfer"
}