API Documentation

Introduction

The Translation API translates text, HTML, and structured JSON into up to 24 official EU languages. Requests and responses are in JSON (UTF-8). Each request selects a quality level: basic (AI), pro (AI with terminology enforcement), or review (plus native-language spot-checking, asynchronous).

To try it out, use the public sandbox key from the customer portal – it behaves like production but is limited to a test quota. Production keys are available after a brief activation process via your customer account.

Public Sandbox Keybd_test_sandbox_2026

Authentication

Each request carries your API key in the Authorization header as a Bearer token. Keys start with bd_test_ (sandbox) or bd_live_ (production). Treat keys like passwords: never in frontend code, never in the repository – if compromise is suspected, revoke and regenerate in the customer portal.

Requests without a valid key receive a 401 status. A key can be assigned a monthly word limit at any time; upon reaching it, the API responds with status 402 until you increase the limit.

Authorization: Bearer bd_live_ihr_schluessel

Translate Text

POST/api/v1/translate

The core endpoint translates one or more texts into a target language. The format field controls processing: text (default), html (markup preserved), or json (only string values are translated, keys and structure remain unchanged).

The response contains translations in input order, the counted source words, and the calculated cost in cents. With the optional Idempotency-Key header, you prevent duplicate processing on network retries: identical keys return the stored first response.

curl https://www.baduno.com/api/v1/translate \
  -H "Authorization: Bearer bd_test_sandbox_2026" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "fr",
    "texts": ["Kostenloser Versand ab 50 Euro."],
    "format": "text",
    "tier": "basic"
  }'

{
  "ok": true,
  "target": "fr",
  "tier": "basic",
  "translations": ["Livraison gratuite à partir de 50 euros."],
  "words": 6,
  "cost_cents": 12,
  "detected_source": "de"
}

Parameter

const res = await fetch("https://www.baduno.com/api/v1/translate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.BADUNO_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ target: "it", texts: [title, description], format: "html" })
});
const { translations } = await res.json();

import os, requests

r = requests.post(
    "https://www.baduno.com/api/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['BADUNO_API_KEY']}"},
    json={"target": "pl", "texts": ["Zurück zur Startseite"], "tier": "pro"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["translations"][0])

$ch = curl_init("https://www.baduno.com/api/v1/translate");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("BADUNO_API_KEY"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode(["target" => "es", "texts" => [$text]])
]);
$out = json_decode(curl_exec($ch), true);

Batch & Webhooks

POST/api/v1/batches

For large volumes or the review stage, work asynchronously: The batch endpoint accepts up to 1,000 texts and responds immediately with a job ID. Once the job is complete – for review after the native-language sample – the API calls your stored webhook URL with the result.

Webhook calls are signed with an HMAC-SHA-256 header, which you can verify using your webhook secret. If your server does not respond with a 2xx status, delivery is retried up to five times with increasing intervals; jobs additionally remain retrievable via GET for 30 days.

POST /api/v1/batches            → { "ok": true, "job": "job_8f2…", "status": "processing" }
GET  /api/v1/batches/job_8f2…   → { "ok": true, "status": "done", "results": [ … ] }

Glossaries

POST/api/v1/glossaries

Glossaries secure your terminology: each entry contains a source term and its binding translation for each target language. Upload is done as CSV in the customer area or via API; the 'pro' and 'review' tiers enforce matches strictly, while 'basic' uses them as recommendations.

Up to 20 glossaries with 5,000 entries each are possible per account. Changes take effect immediately on all subsequent requests – therefore version your glossaries like code and test changes first with the sandbox key.

Languages

GET/api/v1/languages

The languages endpoint provides the currently available target and source languages with ISO code and native name. Use it instead of a hardcoded list – new languages appear there automatically.

Usage

GET/api/v1/usage

The usage endpoint displays, per key, the translated words and incurred costs for the current month as well as the set monthly limit. You can see the same figures graphically in the customer area under "API & Usage".

Error codes

Errors are returned as JSON with the fields error (machine-readable code) and message (description). At minimum, handle the following cases:

Limits & Fairness

By default, 60 requests per minute per key and 30,000 characters per request apply; the sandbox key is additionally limited to the test quota. We enable higher limits after a brief review – contact us with your use case.

Word counting: Words of the source text are counted (Unicode word boundaries), once per target language. For html and json formats, only translatable text nodes or string values are counted – markup, keys, and variables are free.

Data Protection

Processing exclusively for service delivery on EU servers; content is not used for model training and is deleted from processing logs after 30 days. For production use, we conclude a data processing agreement pursuant to Art. 28 GDPR – details in the Trust Center.

Do not send real personal data via the sandbox. Pseudonymize test content or use synthetic examples.

Changelog

July 2026

Launch of the public sandbox: Translation, Batch, Glossary, Languages, and Usage endpoints.

Planned

Production key self-service, style profiles per brand, translation memory per account.

The API is versioned under /v1; backward-compatible extensions (new optional fields, new languages) are made without a version change. Breaking changes appear as a new version with at least twelve months of parallel operation.