API Documentation

Integrate LocaleLens translations into your applications with our REST API

Quick Start

The LocaleLens API allows you to fetch translations programmatically. All requests require an API key for authentication.

Get Your API Key

Navigate to your project
Go to the "API Keys" tab
Click "Create API Key" (each project can have one API key)
Copy the key immediately (you won't see it again!)

Authentication

Include your API key in requests using either the Authorization header or a query parameter.

Authorization: Bearer ll_your_api_key_here

Recommended for server-side requests. More secure and cleaner.

Example with cURL:

curl -H "Authorization: Bearer ll_your_api_key" \
  https://localelens.ai/api/v1/projects/PROJECT_ID/translations/en

Example with fetch:

fetch('https://localelens.ai/api/v1/projects/PROJECT_ID/translations/en', {
  headers: {
    'Authorization': 'Bearer ll_your_api_key'
  }
})

Endpoints

Health Check

GET

/api/v1/health

Check API status and version. No authentication required.

curl https://localelens.ai/api/v1/health

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2025-01-19T12:00:00Z"
}

Get Translations

GET

/api/v1/projects/:projectId/translations/:locale

Fetch all translations for a specific locale. Supports flat (default) or nested format, and optional namespace filtering.

curl -H "Authorization: Bearer ll_your_api_key" \
  https://localelens.ai/api/v1/projects/PROJECT_ID/translations/en

Query Parameters:

?source=stable - Latest release snapshot (default, safe for production)
?source=live - Live translations (current database state, for development)
?namespace=common - Filter by namespace (e.g., only return keys in "common" namespace)
?format=flat - Flat format (default): {"common.save": "Save"}
?format=nested - Nested format: {"common": {"save": "Save"}}
?fresh - Bypass cache — response includes Cache-Control: no-store

Response (Flat Format - Default):

{
  "common.save": "Save",
  "common.cancel": "Cancel",
  "auth.login.title": "Sign In"
}

Response (Nested Format - ?format=nested):

{
  "common": {
    "save": "Save",
    "cancel": "Cancel"
  },
  "auth": {
    "login": {
      "title": "Sign In"
    }
  }
}

Response Headers:

The response includes headers to help you understand which data source was used:

X-LocaleLens-Source - Which source was actually used ("stable" or "live")
X-LocaleLens-Snapshot-Id - The snapshot ID used (or "null" if live)

Caching Strategy:

Source	Cache-Control	Behavior
`?source=stable`	`max-age=3600, immutable`	Cached 1 hour — snapshots never change
`?source=live`	`no-cache (ETag revalidation)`	Always revalidates — fresh data, efficient 304s
`?fresh`	`no-store`	No caching — guaranteed fresh response

Use If-None-Match with the ETag header to get 304 Not Modified when content hasn't changed.

Get Locales

GET

/api/v1/projects/:projectId/locales

List all available locales for a project.

curl -H "Authorization: Bearer ll_your_api_key" \
  https://localelens.ai/api/v1/projects/PROJECT_ID/locales

Response:

{
  "locales": [
    {
      "code": "en",
      "name": "English"
    },
    {
      "code": "es",
      "name": "Spanish"
    }
  ]
}

Get Translation Keys

GET

/api/v1/projects/:projectId/keys

List all translation keys in a project. Supports optional namespace filtering.

curl -H "Authorization: Bearer ll_your_api_key" \
  https://localelens.ai/api/v1/projects/PROJECT_ID/keys

Query Parameters:

?namespace=common - Filter by namespace

Response:

{
  "keys": [
    {
      "key": "common.save",
      "namespace": "common",
      "description": "Save button label"
    }
  ]
}

Error Handling

All errors follow a consistent format with error codes, messages, and helpful links.

Error Response Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 3600 seconds.",
    "request_id": "req_1234567890_abc123",
    "docs_url": "/docs/api#error-handling",
    "retry_after": 3600
  }
}

Standard Error Codes:

UNAUTHORIZED - Invalid or missing API key
FORBIDDEN - API key doesn't have access to project
NOT_FOUND - Project or locale not found
RATE_LIMIT_EXCEEDED - Too many requests (includes retry_after)
INVALID_LOCALE - Locale code is invalid
SERVER_ERROR - Internal server error

Rate Limiting

API requests are rate-limited per API key to ensure fair usage and prevent abuse.

Rate Limits by Tier

Free10,000 requests/month (~333/day)

Pro1M requests/month (~33k/day)

Tip: When you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can try again.

Code Examples

Fetch Translations

const API_KEY = 'll_your_api_key_here';
const PROJECT_ID = 'your-project-id';
const LOCALE = 'en';

const response = await fetch(
  `https://localelens.ai/api/v1/projects/${PROJECT_ID}/translations/${LOCALE}`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
    },
  }
);

if (!response.ok) {
  const error = await response.json();
  console.error('Error:', error.error.message);
  return;
}

const translations = await response.json();
console.log(translations);

Next Steps

Ready to Get Started?

Create an API key from your project's API Keys page
Use the examples above to make your first request
Integrate translations into your application
Check the response headers for caching information

Need Help? Check the error response docs_url field for detailed troubleshooting guides, or contact support with the request_id from error responses.