API Usage

The public REST API lives under /api/v1 and is authenticated with an API key.

Base URL

https://linguolink.dev/api/v1

The base URL follows your deployment’s NEXT_PUBLIC_APP_URL. On a self-hosted instance, replace the host accordingly.

Authentication

Send your API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

API keys are prefixed with ll_ followed by 64 hex characters. The full key is shown only once at creation time — see API Keys.

Quick Test

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://linguolink.dev/api/v1/test

Returns the authenticated key’s name, organization, scopes, rate limit, and usage count.

Pull Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://linguolink.dev/api/v1/pull?project_id=YOUR_PROJECT_ID&language=en&format=json" \
  -o ./locales/en.json

The response is returned as a downloadable file (Content-Disposition: attachment).

Available Endpoints

GET  /api/v1/test                                            # verify authentication (no scope required)
GET  /api/v1/project                                         # authenticated key/org info (no scope required)
GET  /api/v1/project?project_id=...                          # project details: base language, target languages
GET  /api/v1/projects                                        # scope: translations:read — list every project in your org
GET  /api/v1/pull?project_id=...&language=en&format=json     # scope: export:read
POST /api/v1/push                                            # scope: translations:write — see Import Translations
GET  /api/v1/jobs/{jobId}                                     # scope: translations:read — poll a background import job
GET  /api/v1/coverage?project_id=...                          # scope: translations:read — per-locale completeness
GET  /api/v1/api-keys?limit=10&offset=0                      # scope: admin
POST /api/v1/api-keys                                        # scope: admin

GET /api/v1/export and POST /api/v1/import still work as deprecated aliases for /api/v1/pull and /api/v1/push — existing integrations don’t break, but point new code at the current names.

There is currently no public endpoint for editing an individual translation by ID. POST /api/v1/push creates/updates translations in bulk, keyed by key + language — see Import Translations and the CLI. Per-record editing still happens in the dashboard.

Pull query parameters

Parameter	Required	Description
`project_id`	yes	Target project UUID
`language`	yes	Locale code (e.g. `en`, `fr`, `en-US`)
`format`	no	`json` (default), `csv`, `xliff`, `xml`, or `yaml`
`environment`	no	Apply environment-specific overrides (see Environment Overrides)
`selected_ids`	no	JSON array of translation IDs to export a subset, e.g. `["id1","id2"]`

Rate Limiting

Each API key has an hourly request limit (default 1000, configurable 1–10000). Every response includes:

X-RateLimit-Limit:     total requests allowed per hour
X-RateLimit-Remaining: requests remaining in the current window
X-RateLimit-Reset:     Unix timestamp (seconds) when the window resets

Error Handling

Status	Meaning
`400`	Missing/invalid parameter (e.g. `project_id` or `language`)
`401`	Missing, malformed, inactive, expired, or invalid API key
`402`	Translation quota exceeded (push only)
`403`	Key lacks the required scope
`404`	No translations found, or the project doesn’t belong to your org
`409`	Conflict (e.g. an API key with that name already exists)
`413`	Push payload too large (12 MB / 50,000 rows)
`429`	Rate limit exceeded — back off until `X-RateLimit-Reset`
`500`	Internal error

Implement retry with exponential backoff for 429 and transient 5xx failures. For the full interactive reference, see the API docs at /api-docs.

Next Steps

Skip the raw HTTP calls with the CLI
Apply this in Integration Examples
Choose output shape in Export Formats

Overview

Getting Started

Project Management

Translation Management

API and Integrations

Help and Support

Base URL

Authentication

Quick Test

Pull Example

Available Endpoints

Pull query parameters

Rate Limiting

Error Handling

Next Steps

​Base URL

​Authentication

​Quick Test

​Pull Example

​Available Endpoints

​Pull query parameters

​Rate Limiting

​Error Handling

​Next Steps

Base URL

Authentication

Quick Test

Pull Example

Available Endpoints

Pull query parameters

Rate Limiting

Error Handling

Next Steps