Skip to content

REST API Reference

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.

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.

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.

  • 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

Workspace members and the invitations sent by the workspace:

GET /api/v1/workspaces/:workspaceId/members
POST /api/v1/workspaces/:workspaceId/members/invite
PATCH /api/v1/workspaces/:workspaceId/members/:userId
DELETE /api/v1/workspaces/:workspaceId/members/:userId
DELETE /api/v1/workspaces/:workspaceId/invitations/:invitationId
POST /api/v1/workspaces/:workspaceId/invitations/:invitationId/resend
POST /api/v1/workspaces/:workspaceId/invitations/accept

Invitations addressed to the caller, who needs no workspace membership:

GET /api/v1/me/invitations
GET /api/v1/me/invitations/:invitationId
POST /api/v1/me/invitations/:invitationId/decline
  • The member list includes pending invitations with memberStatus: "invited". Their id is the invitation ID used by the revoke and resend endpoints. They carry only the email address.
  • Inviting takes { "email", "roleId" }. Get role IDs from GET /api/v1/workspaces/:workspaceId/roles. Owner cannot be invited.
  • Inviting, resending and revoking require members.invite. Changing a role requires members.update_role, removing a member members.remove.
  • Invite and resend return the same response whether or not the address already has an account.
  • POST .../invitations/accept accepts the caller’s pending invitation to that workspace.
  • GET /me/invitations/:invitationId returns 403 when 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/teams
POST /api/v1/workspaces/:workspaceId/teams
GET /api/v1/workspaces/:workspaceId/teams/:teamId
PATCH /api/v1/workspaces/:workspaceId/teams/:teamId
DELETE /api/v1/workspaces/:workspaceId/teams/:teamId
PUT /api/v1/workspaces/:workspaceId/teams/:teamId/members/:userId
DELETE /api/v1/workspaces/:workspaceId/teams/:teamId/members/:userId
  • Reading teams requires teams.read. Creating, renaming, deleting teams and managing their members requires teams.manage and the teams capability (Pro and above).
  • Create takes { "name", "description"? }. Names are unique per workspace (412 when taken). Update takes name, 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 (with include_inherited=true) returns teams: the team roles that reach the project.

Current REST access surface:

GET /api/v1/workspaces/:workspaceId/roles
GET /api/v1/workspaces/:workspaceId/capabilities
GET /api/v1/workspaces/:workspaceId/grants
POST /api/v1/workspaces/:workspaceId/grants
PATCH /api/v1/workspaces/:workspaceId/grants/:grantId
DELETE /api/v1/workspaces/:workspaceId/grants/:grantId
GET /api/v1/workspaces/:workspaceId/audit/access
GET /api/v1/workspaces/:workspaceId/access-tokens
POST /api/v1/workspaces/:workspaceId/access-tokens
POST /api/v1/workspaces/:workspaceId/access-tokens/:id/rotate
DELETE /api/v1/workspaces/:workspaceId/access-tokens/:id
GET /api/v1/me/effective-permissions?workspace_id=:workspaceId
GET /api/v1/me/access-tokens/mine
GET /api/v1/me/access-tokens?workspace_id=:workspaceId
POST /api/v1/me/access-tokens
POST /api/v1/me/access-tokens/:id/rotate?workspace_id=:workspaceId
DELETE /api/v1/me/access-tokens/:id?workspace_id=:workspaceId

GET /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.

GET /api/v1/workspaces/:workspaceId/capabilities is the REST debugging surface for effective plan state.

The response includes:

  • capabilities[] for boolean feature gates
  • quotas.workspace[] always
  • quotas.project when project_id is supplied
  • quotas.tenant when tenant_id is supplied
  • quotas.user when user_id is supplied

This endpoint is especially useful for inspecting scoped limits such as:

  • keys_per_project
  • base_languages_per_project
  • rules_per_tenant
  • pats_per_user

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 routes live under:

/api/v1/workspaces/:workspaceId/projects/:projectId/export
GET /api/v1/workspaces/:workspaceId/projects/:projectId/export

Returns supported formats and available query parameters.

GET /api/v1/workspaces/:workspaceId/projects/:projectId/export/:format

If 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.

GET /api/v1/workspaces/:workspaceId/projects/:projectId/export/bulk/:format

This endpoint always returns a ZIP archive and is the preferred endpoint for automation.

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
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
Parameter Type Description
path_template string Archive path template using {language}, {variant}, {tenant}, {file}, and {ext}
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.

Archive responses are named using:

{project-slug}-{latest|validated}-{YYYY-MM-DD}.zip

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}
GET /api/v1/workspaces/:workspaceId/projects/:projectId/export/bulk/yaml?languages=en,fr,es&content_mode=multilingual

This produces one YAML file per logical file path, with all selected languages embedded in the same document.

{
"$for": "keys",
"$as": "key",
"$body": {
"name": "{{key.name}}",
"translations": {
"$for": "key.translations",
"$as": "translation",
"$body": {
"language": "{{translation.language}}",
"text": "{{translation.text}}"
}
}
}
}

Successful file downloads typically include:

  • Content-Type
  • Content-Disposition
  • Cache-Control: no-store

For ZIP downloads, Content-Disposition contains the archive filename to use on disk.

Glossary routes live under:

/api/v1/workspaces/:workspaceId/glossary
GET /api/v1/workspaces/:workspaceId/glossary/export?format=json|yaml|csv

Returns a downloadable attachment (Content-Disposition + format-specific Content-Type).

POST /api/v1/workspaces/:workspaceId/glossary/import
Content-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.