REST API Reference
Overview
Section titled “Overview”LokAI exposes a REST API at /api/v1 for third-party integrations, alongside a type-safe tRPC endpoint at /trpc for first-party clients (Studio, CLI).
Base URL: https://api-dev.lokai.cloud/api/v1
All requests must include an Authorization: Bearer <token> header.
Request limits
Section titled “Request limits”The default HTTP request body limit is 1 MiB, including key bulk-create requests and tRPC batches. Glossary import allows an 8 MiB HTTP body over POST /api/v1/workspaces/:workspaceId/glossary/import and standalone POST /trpc/glossary.import, with 1 MiB of UTF-8 content and 1,000 entries per import. These limits apply to every plan.
Exceeding a body or content byte limit returns 413 PAYLOAD_TOO_LARGE. An oversized HTTP body is rejected before dispatch using the REST error envelope, including for tRPC requests. A content cap rejected inside tRPC uses its native error format. Exceeding the entry count returns 400 BAD_REQUEST before writes. Ordinary REST request-envelope validation uses 422 VALIDATION_ERROR.
See Plans and limits for the limits and Import and export for splitting and retrying imports.
Authentication
Section titled “Authentication”Current bearer token types:
- Supabase JWTs for human sessions
- personal access tokens (PATs)
- workspace access tokens (WATs)
PATs and WATs are both scope-aware machine identities. PATs are additionally bounded by the owning user’s effective permissions.
Some actions need a signed-in person and return 403 to PATs and WATs: creating, rotating and revoking tokens, creating or leaving a workspace, and listing, accepting or declining your invitations. A token can never create another token.
Resources
Section titled “Resources”- Workspaces —
/workspaces - Members & invitations —
/workspaces/:workspaceId/members,/workspaces/:workspaceId/invitations,/me/invitations - Teams —
/workspaces/:workspaceId/teams - Access —
/workspaces/:workspaceId/roles,/workspaces/:workspaceId/capabilities,/workspaces/:workspaceId/grants - Projects —
/workspaces/:workspaceId/projects - Translation Keys —
/projects/:projectId/keys - Translations —
/keys/:keyId/translations - Glossary —
/workspaces/:workspaceId/glossary - Tenants —
/workspaces/:workspaceId/tenants - Export —
/projects/:projectId/export
Members and invitations
Section titled “Members and invitations”Workspace members and the invitations sent by the workspace:
GET /api/v1/workspaces/:workspaceId/membersPOST /api/v1/workspaces/:workspaceId/members/invitePATCH /api/v1/workspaces/:workspaceId/members/:userIdDELETE /api/v1/workspaces/:workspaceId/members/:userIdDELETE /api/v1/workspaces/:workspaceId/invitations/:invitationIdPOST /api/v1/workspaces/:workspaceId/invitations/:invitationId/resendPOST /api/v1/workspaces/:workspaceId/invitations/acceptInvitations addressed to the caller, who needs no workspace membership:
GET /api/v1/me/invitationsGET /api/v1/me/invitations/:invitationIdPOST /api/v1/me/invitations/:invitationId/decline- The member list includes pending invitations with
memberStatus: "invited". Theiridis the invitation ID used by the revoke and resend endpoints. They carry only the email address. - Inviting takes
{ "email", "roleId" }. Get role IDs fromGET /api/v1/workspaces/:workspaceId/roles. Owner cannot be invited. - Inviting, resending and revoking require
members.invite. Changing a role requiresmembers.update_role, removing a membermembers.remove. - Invite and resend return the same response whether or not the address already has an account.
POST .../invitations/acceptaccepts the caller’s pending invitation to that workspace.GET /me/invitations/:invitationIdreturns403when the caller is not the invitee.
Project members are project-scoped grants. List them with GET /api/v1/workspaces/:workspaceId/projects/:projectId/members?include_inherited=true, and manage them through the grant endpoints below with scopeType: "project". GET /api/v1/workspaces/:workspaceId/projects/:projectId/members/candidates lists the workspace members who can still be added; it needs project_members.manage, not members.read, so Project Managers can use it. GET .../projects/:projectId/members/roles lists the roles that can be granted on the project, under the same permission. See Members & Roles and Inviting People for how these work in Studio.
GET /api/v1/workspaces/:workspaceId/teamsPOST /api/v1/workspaces/:workspaceId/teamsGET /api/v1/workspaces/:workspaceId/teams/:teamIdPATCH /api/v1/workspaces/:workspaceId/teams/:teamIdDELETE /api/v1/workspaces/:workspaceId/teams/:teamIdPUT /api/v1/workspaces/:workspaceId/teams/:teamId/members/:userIdDELETE /api/v1/workspaces/:workspaceId/teams/:teamId/members/:userId- Reading teams requires
teams.read. Creating, renaming, deleting teams and managing their members requiresteams.manageand theteamscapability (Pro and above). - Create takes
{ "name", "description"? }. Names are unique per workspace (412when taken). Update takesname,description, or both. - Only workspace members can join a team. Adding someone already in it returns
added: false. - Deleting a team revokes its grants first and reports
revokedGrantCount. Members keep their own grants. - A team’s roles are grants with
subjectType: "team", created and changed through the grant endpoints below. Owner cannot be granted to a team. - The member list returns each member’s
teams, and the project member list (withinclude_inherited=true) returnsteams: the team roles that reach the project.
Access endpoints
Section titled “Access endpoints”Current REST access surface:
GET /api/v1/workspaces/:workspaceId/rolesGET /api/v1/workspaces/:workspaceId/capabilitiesGET /api/v1/workspaces/:workspaceId/grantsPOST /api/v1/workspaces/:workspaceId/grantsPATCH /api/v1/workspaces/:workspaceId/grants/:grantIdDELETE /api/v1/workspaces/:workspaceId/grants/:grantIdGET /api/v1/workspaces/:workspaceId/audit/accessGET /api/v1/workspaces/:workspaceId/access-tokensPOST /api/v1/workspaces/:workspaceId/access-tokensPOST /api/v1/workspaces/:workspaceId/access-tokens/:id/rotateDELETE /api/v1/workspaces/:workspaceId/access-tokens/:id
GET /api/v1/me/effective-permissions?workspace_id=:workspaceIdGET /api/v1/me/access-tokens/mineGET /api/v1/me/access-tokens?workspace_id=:workspaceIdPOST /api/v1/me/access-tokensPOST /api/v1/me/access-tokens/:id/rotate?workspace_id=:workspaceIdDELETE /api/v1/me/access-tokens/:id?workspace_id=:workspaceIdGET /api/v1/me/access-tokens/mine requires a user session and no workspace header.
It returns { tokens, workspaces } for your active memberships. Each workspace includes
its id, slug, name, PAT action permissions, and quota. Tokens are included only where you
have personal_tokens.read. Scoped PAT and WAT credentials cannot call this endpoint.
Manage PATs in Studio under Account → Access tokens, and WATs under
Workspace Settings → Tokens. Existing scoped mutation endpoints remain available;
rotation and revocation use the token’s workspace.
Capabilities and quotas
Section titled “Capabilities and quotas”GET /api/v1/workspaces/:workspaceId/capabilities is the REST debugging surface for effective plan state.
The response includes:
capabilities[]for boolean feature gatesquotas.workspace[]alwaysquotas.projectwhenproject_idis suppliedquotas.tenantwhentenant_idis suppliedquotas.userwhenuser_idis supplied
This endpoint is especially useful for inspecting scoped limits such as:
keys_per_projectbase_languages_per_projectrules_per_tenantpats_per_user
Deferred areas
Section titled “Deferred areas”The data model already supports custom roles, but the current shipped surface keeps them deferred:
- no custom-role CRUD
- read-only role listing through
/roles
Export Endpoints
Section titled “Export Endpoints”Export routes live under:
/api/v1/workspaces/:workspaceId/projects/:projectId/exportGet Export Capabilities
Section titled “Get Export Capabilities”GET /api/v1/workspaces/:workspaceId/projects/:projectId/exportReturns supported formats and available query parameters.
Download a Single Export Result
Section titled “Download a Single Export Result”GET /api/v1/workspaces/:workspaceId/projects/:projectId/export/:formatIf the export resolves to a single file, the route may return that file directly. If multiple output files are generated, the response is a ZIP archive.
Download a ZIP Archive
Section titled “Download a ZIP Archive”GET /api/v1/workspaces/:workspaceId/projects/:projectId/export/bulk/:formatThis endpoint always returns a ZIP archive and is the preferred endpoint for automation.
Export Query Parameters
Section titled “Export Query Parameters”Core Parameters
Section titled “Core Parameters”| Parameter | Type | Description |
|---|---|---|
languages |
string |
Comma-separated language codes such as fr,de,ja |
version |
latest | validated |
Export the latest translation state or only validated/published content |
status |
legacy enum | Legacy alias. validated, approved, and published map to version=validated |
namespace |
string |
Filter keys by exact namespace. An empty value selects the keys that have none |
namePattern |
string |
Filter keys by name pattern, where * matches any text |
tags |
string |
Comma-separated tag filter |
include_empty |
true | false |
Include keys without translation text |
Content Shaping
Section titled “Content Shaping”| Parameter | Type | Description |
|---|---|---|
content_mode |
per_language | multilingual |
multilingual is currently supported for JSON and YAML only |
structure_template |
string |
JSON-encoded template using placeholders, $for loops, and $if conditionals |
include_metadata |
true | false |
Supported for json, json-nested, and yaml; mainly affects the default export shape when no custom structure_template is used |
Archive Layout
Section titled “Archive Layout”| Parameter | Type | Description |
|---|---|---|
path_template |
string |
Archive path template using {language}, {variant}, {tenant}, {file}, and {ext} |
Tenant Variants
Section titled “Tenant Variants”| Parameter | Type | Description |
|---|---|---|
tenant_id |
string |
Export a single tenant variant |
tenant_ids |
string |
Comma-separated tenant IDs or all |
include_vanilla |
true | false |
Include the base non-tenant variant |
If tenant features are disabled on the workspace, the export route rejects tenant-specific parameters.
ZIP Naming
Section titled “ZIP Naming”Archive responses are named using:
{project-slug}-{latest|validated}-{YYYY-MM-DD}.zipPath Template Tokens
Section titled “Path Template Tokens”Supported tokens:
{language}{variant}{tenant}: alias for{variant}{file}{ext}
Examples:
{language}/{file}.{ext}{file}.{language}.{ext}{variant}/{language}/{file}.{ext}{language}/{variant}/{file}.{ext}{file}.{variant}.{language}.{ext}Multilingual Export Example
Section titled “Multilingual Export Example”GET /api/v1/workspaces/:workspaceId/projects/:projectId/export/bulk/yaml?languages=en,fr,es&content_mode=multilingualThis produces one YAML file per logical file path, with all selected languages embedded in the same document.
Advanced Structure Template Example
Section titled “Advanced Structure Template Example”{ "$for": "keys", "$as": "key", "$body": { "name": "{{key.name}}", "translations": { "$for": "key.translations", "$as": "translation", "$body": { "language": "{{translation.language}}", "text": "{{translation.text}}" } } }}Common Response Headers
Section titled “Common Response Headers”Successful file downloads typically include:
Content-TypeContent-DispositionCache-Control: no-store
For ZIP downloads, Content-Disposition contains the archive filename to use on disk.
Glossary Import/Export
Section titled “Glossary Import/Export”Glossary routes live under:
/api/v1/workspaces/:workspaceId/glossaryExport Glossary
Section titled “Export Glossary”GET /api/v1/workspaces/:workspaceId/glossary/export?format=json|yaml|csvReturns a downloadable attachment (Content-Disposition + format-specific Content-Type).
Import Glossary
Section titled “Import Glossary”POST /api/v1/workspaces/:workspaceId/glossary/importContent-Type: application/json{ "format": "json", "content": "{ \"entries\": [ ... ] }"}Response payload:
{ "success": true, "data": { "created": 2, "updated": 5, "failed": 0, "errors": [] }}Glossary import is best-effort across entries. Each entry, its supplied translations and history are atomic; other entries can succeed when one fails. The REST endpoint returns 201 with the created, updated, failed, and errors summary even if some entries fail.
Key bulk create accepts at most 100 keys within the default 1 MiB body limit. It attempts keys independently and retains successful writes when other keys fail. There is no transaction for the whole bulk request. Retry only failed keys to avoid duplicate-name errors.