REST API Reference

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.lokai.cloud/api/v1

All requests must include an Authorization: Bearer <token> header.

Authentication

Tokens are obtained via Supabase Auth. Pass the JWT as a Bearer token on every request.

Resources

Workspaces — /workspaces
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

Export Endpoints

Export routes live under:

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

Get Export Capabilities

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

Returns supported formats and available query parameters.

Download a Single Export Result

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.

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

Export Query Parameters

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 namespace pattern
`tags`	`string`	Comma-separated tag filter
`include_empty`	`true \| false`	Include keys without translation text

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

Parameter	Type	Description
`path_template`	`string`	Archive path template using `{language}`, `{variant}`, `{tenant}`, `{file}`, and `{ext}`

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

Archive responses are named using:

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

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

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.

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

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 Import/Export

Glossary routes live under:

/api/v1/workspaces/:workspaceId/glossary

Export Glossary

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

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

Import Glossary

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": []
  }
}