Getting started

Use the PolyLingo HTTP API to translate plain text, Markdown, JSON, or HTML while keeping structure intact. This guide covers the production endpoint, authentication, and your first successful request.

Base URL

All examples use the production API:

Every path below is relative to that base (for example, POST /translate means POST https://api.usepolylingo.com/v1/translate).

If you run your own PolyLingo API instance, replace the host with your deployment URL and keep the /v1 prefix unless you have configured otherwise.

Authentication

Protected endpoints expect your API key in the Authorization header:

Authorization: Bearer <your_api_key>

Getting a key: Create one in the PolyLingo app under API keys. You only see the full key once—store it somewhere safe (environment variable or secret manager). Keys can be revoked from the same screen.

Security: Treat the key like a password. Prefer calling the API from your server, not from public browser code, so the key is never exposed to users.

If the header is missing, wrong, or the key is invalid or revoked, the API responds with 401 and error: "invalid_api_key".

Endpoints and keys

First request (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

A successful response includes a translations object (one entry per target language you requested) and a usage object with token counts.

First request (Node.js)

Node.js 18+ includes fetch:

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

Check that the API is reachable

No key is needed for health:

curl -sS "https://api.usepolylingo.com/v1/health"

You should see a small JSON payload indicating the service is up. Use GET /languages for the list of codes you can pass as targets.

CORS and browser apps

The API may restrict which browser origins can call it directly, so that keys are not used from untrusted sites. Server-side calls (Node, Python, edge functions, your backend) are not limited by CORS.

For a single-page app, the usual pattern is: your frontend talks to your backend, and your backend calls PolyLingo with the API key.

Next steps

• API reference — request and response shapes, formats, errors, and limits.