API Reference

The Polyglot API powers the CLI and dashboard. You can also call it directly for custom integrations.

Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

Authorization: Bearer pg_your_api_key_here

Get your API key from polyglot auth status or the dashboard settings page.

Base URL

https://api.getpolyglot.ai

Endpoints

Translate strings

POST /api/v1/translate

Body:
{
  "strings": [
    { "value": "Welcome to my app" },
    { "value": "Get started" }
  ],
  "target_language": "de",
  "glossary_terms": [
    { "source_term": "Polyglot", "do_not_translate": true }
  ]
}

Response: 200
{
  "translations": {
    "Welcome to my app": "Willkommen in meiner App",
    "Get started": "Loslegen"
  },
  "from_memory": 0,
  "newly_translated": 2
}

Each string value is limited to 10,000 characters. Split longer content (articles, long-form pages) into one string per paragraph or section.

Translation coverage

GET /api/v1/strings/coverage

Response: 200
{
  "total_strings": 42,
  "languages": [
    { "language": "es", "translated": 42, "total": 42, "percentage": 100.0 },
    { "language": "fr", "translated": 38, "total": 42, "percentage": 90.5 }
  ]
}

Project info

GET /api/v1/projects/current

Response: 200
{
  "id": "proj_abc123",
  "name": "my-app",
  "tier": "pro",
  "framework": "nextjs",
  "source_language": "en",
  "target_languages": ["es", "fr", "de"]
}

Create project

POST /api/v1/projects

Body:
{
  "name": "my-app",
  "framework": "nextjs",
  "source_language": "en",
  "target_languages": ["es", "fr"]
}

Response: 201
{
  "project": { "id": "proj_abc123", "name": "my-app", ... },
  "api_key": "pg_live_..."
}

Glossary

GET /api/v1/glossary              # List all terms
POST /api/v1/glossary             # Create term
PUT /api/v1/glossary/:id          # Update term
DELETE /api/v1/glossary/:id       # Delete term

Usage

GET /api/v1/usage

Response: 200
{
  "current_period": {
    "strings_translated": 250,
    "characters_translated": 45000,
    "api_calls": 38,
    "period_start": "2025-01-01",
    "period_end": "2025-01-31"
  },
  "history": [],
  "project_total_strings": 420,
  "limits": {
    "strings": 10000,
    "languages": 5,
    "characters": null,
    "batch_size": 1000
  },
  "tier": "pro"
}

Rate limits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error responses

Errors return a JSON object with an error field:

{
  "error": "Rate limit exceeded",
  "retry_after": 45
}