API overview
This reference describes the management API used by the Customer Panel. It covers accounts, workspaces, projects, language configuration, translation keys/values, tags, background file transfers, branch management and publishing. The independent delivery API has a separate authentication and cache contract.
Contracts
Section titled “Contracts”The reference is generated from the same reviewed OpenAPI files kept with the application. Every operation has a permanent page under its API group.
| Contract | Download |
|---|---|
| Git synchronization | OpenAPI JSON |
| Authentication | OpenAPI JSON |
| Workspaces and memberships | OpenAPI JSON |
| Projects, languages and locale catalog | OpenAPI JSON |
| Translation keys and values | OpenAPI JSON |
| Import, export and key tags | OpenAPI JSON |
| Branch management | OpenAPI JSON |
| Publishing and releases | OpenAPI JSON |
| Independent delivery | OpenAPI JSON |
Management paths begin with /api/v1. The panel forwards supported requests to the API on the same origin. These endpoints require a customer session; distribution read keys cannot manage content. Independent delivery paths begin with /delivery/v1 and require a distribution/channel-scoped Bearer key. They use no session cookie or CSRF token. See the delivery protocol for signature verification and private cache rules. The five SDK packages remain a separate delivery.
Authentication and CSRF
Section titled “Authentication and CSRF”Sign-in uses a full browser navigation to the login endpoint, followed by the identity service’s Authorization Code + PKCE flow. Its callback is a protocol endpoint; do not call it as a data-fetch request.
The server stores provider tokens and gives the browser an opaque session cookie. HTTPS deployments use __Host-localisync-session with Secure, HttpOnly and SameSite=Lax. Explicit local HTTP development uses localisync-session.
Workspace/project mutations require the existing session-bound X-CSRF-Token and an Origin matching the panel. The panel obtains its CSRF value through its server-side session handling. Logout uses a form-encoded csrf field, as described in its operation contract. Backchannel logout is a signed identity-provider notification with its own validation.
The documentation site never receives session cookies, tokens or customer data and does not send API requests. It has no live Try it form. Do not copy credentials into examples or logs.
Authorization
Section titled “Authorization”The API checks current workspace membership on every request. Owner/Admin manage workspace and project settings; narrower actions such as workspace ownership transfer and workspace archival require Owner. See the role matrix.
Owner/Admin/Editor edit translation content; only Owner/Admin archive or restore keys. Viewer reads content and history. Inactive languages and archived parents/keys are read-only.
Removing a member or reducing a role applies to subsequent requests immediately. A resource outside your accessible workspace scope returns 404; an insufficient role within an accessible workspace returns 403. Client-side visibility is not an authorization boundary.
Pagination
Section titled “Pagination”List endpoints use page (default 1) and pageSize (default 25, maximum 100). Responses include items, page, pageSize and hasMore; follow the operation schema for additional fields.
Project lists default to active projects. The status filter also supports archived and all.
Versions and idempotency
Section titled “Versions and idempotency”Workspace and project mutations carry the version last read from the relevant resource. Language changes advance the selected branch version, independently of shared project settings. A stale version returns 409; fetch current state and review the intended change before submitting again.
Key metadata and language values have separate versions. Value mutations carry both the expected keyVersion and cell version; absent values start at zero and clearing preserves monotonic versions. Translation writes do not advance project settings versions. Contract changes may include atomic value corrections.
Creation and invitation operations that declare Idempotency-Key require a UUID. Keep the same key and normalized input when retrying an interrupted request. Reusing it with different input returns a conflict. Starting a genuinely different creation uses a new key.
Replaying an invitation request does not resend its email automatically. Inspect the delivery status and use the explicit resend operation when necessary.
Errors and retries
Section titled “Errors and retries”| Status | Meaning | Caller action |
|---|---|---|
| 400 | Invalid input or rejected state for the operation | Inspect the error code/message and correct the request. |
| 401 | Authentication is missing or no longer valid | Sign in again. |
| 403 | Permission or request-origin/CSRF check failed | Review role and same-origin request handling. |
| 404 | The resource is unavailable within your access scope | Check the current workspace and membership. |
| 409 | A version, idempotency or business-rule conflict | Refresh and review before changing input or retrying. |
| 413 | Request or file size exceeds the permitted limit | Reduce the upload/body; no partial import is applied. |
| 429 | An abuse limit was reached | Respect Retry-After where supplied. |
| 503 | A required service is unavailable | Retry after recovery; do not assume a mutation succeeded. |
Error responses expose error, message and, where supplied, a requestId. Project dependency errors may also include details.dependentLocales. Translation validation errors include details.issues with field, optional locale and reason. The operation-specific schema is authoritative.
Private API responses use Cache-Control: no-store. Translation request bodies have a 1 MiB limit; import options and export configuration also allow 1 MiB. Multipart upload allows 20 MiB of file contents plus bounded multipart overhead. Other request bodies retain the 20 KB limit. Translation values are limited to 16 KiB UTF-8 each. General limits are process-local: 120 requests per minute per route/caller and an aggregate 1,000 per minute per source address. Invitation delivery also has persisted limits.
Request throttling returns 429 with error: rate_limited and a Retry-After delay in seconds. Honor the returned delay and slow polling; exceeding a limit is not a dependency outage. Route delays reflect the remaining window, while aggregate and invitation limits request a 60-second delay. Limits remain active during background imports and branch jobs.
Reading schema examples
Section titled “Reading schema examples”JSON blocks in the reference are schemas, not successful response logs. They preserve required fields, types, bounds and $ref relationships. Follow the linked schema definitions for referenced models. Any explicitly labeled example payload is illustrative and contains no real customer record.
Transfer jobs
Section titled “Transfer jobs”Upload returns a creator-owned job. Map files and generate a versioned preview, then explicitly approve Apply. Creation and Apply use idempotency keys; preview edits use the current revision. Poll status until completion, and fetch paginated issues on errors. Import and export explain state transitions, native mappings and private download retention. Tag mutations use key metadata versions, never cell versions.
Explicit branch context
Section titled “Explicit branch context”Content endpoints include /branches/{branchId} after the project ID. Branchless content API routes are removed. Use mainBranchId from the project or select a branch explicitly. See the migration guide and download the branch OpenAPI contract. Fork, comparison and merge return 202 jobs. Resolutions and Apply are versioned; Apply and job creation use idempotency keys. Current permissions and snapshot freshness are rechecked before atomic commit.
Translation assistance
Section titled “Translation assistance”The Translation assistance API covers workspace connections and explicit branch jobs. Creation, Generate/retry and Apply use idempotency keys; edits carry expected versions. Credentials are write-only. The public delivery protocol and immutable release content are unchanged.
Translation workflow
Section titled “Translation workflow”Language permissions, reviews, context and knowledge sources use the workflow OpenAPI contract. Review mutations carry expected text/key/evidence versions and an idempotency key; one conflict rolls back the entire batch. Resource editor access never grants translation access.
Workspace dashboard
Section titled “Workspace dashboard”Read-only summary, activity, languages, projects, tasks and publications are documented in the Dashboard API contract. Current membership is required; coverage uses main branches while tasks and publishing operations keep their actual branch scope.
Figma content boundary
Section titled “Figma content boundary”The Figma reference documents browser approval, revocation and bounded content commands for the local development plugin. These credentials do not authorize the normal management API. See Figma workflow for scope and recovery.
Choose whether we remember appearance preferences and use Google Analytics on Localisync and its documentation. Optional storage stays off until you accept.
Read our cookie policy