Public SDK API reference

Base URLs:

• Production: https://sdk-api.kalima.digital/api/v1
• QA: https://qa-sdk-api.kalima.digital/api/v1

Authentication model

The public SDK API uses the project key as the client credential. Depending on the endpoint, the project key is supplied either in the path or in the X-Project-Key header.

GET /projects/key/:projectKey

Returns the public project settings needed by clients at runtime.

Response shape

{
  "sourceLocale": "en",
  "supportedLocales": ["en", "fr", "es"],
  "extraction": {
    "extractPhrases": true,
    "extractionMode": "source",
    "sendFrequency": 900000,
    "minStringsToSend": 30
  },
  "instantTranslation": {
    "enabled": true,
    "cacheTtlMs": 600000,
    "batchSize": 25
  }
}

GET /translate/:projectKey/:langCode

Returns approved translations for a locale.

Response shape

{
  "translations": {
    "Welcome": "Bienvenue",
    "Pricing": "Tarification"
  }
}

POST /phrases/batch-extract

Accepts batched phrase extraction payloads.

Body

{
  "projectKey": "your-project-key",
  "sourceUrl": "https://app.example.com/account",
  "sourceType": "dom",
  "phrases": [
    {
      "sourceText": "Welcome back",
      "context": "Dashboard hero",
      "count": 1,
      "locations": [
        {
          "url": "https://app.example.com/account",
          "path": "main > h1",
          "context": "Dashboard hero",
          "element": "h1"
        }
      ]
    }
  ],
  "metadata": {
    "environment": "prod"
  },
  "hashOptions": {
    "verifyHashes": true,
    "detectDuplicates": true,
    "trackChanges": true
  }
}

Notes

• phrases accepts up to 500 items per request
• Phrase extraction is only available for projects with the required feature enabled

POST /translate/instant

Translates up to 50 text values in one request. The project must have instant translation enabled and the request origin must match the configured allowed origins when an allowlist is set.

Headers

X-Project-Key: your-project-key
Content-Type: application/json

Body

{
  "texts": ["Welcome back", "Manage billing"],
  "sourceLanguage": "en",
  "targetLanguage": "fr",
  "context": "account dashboard"
}

Response

{
  "translations": ["Bienvenue", "Gerer la facturation"],
  "sources": ["approved", "machine"],
  "sourceLanguage": "en",
  "targetLanguage": "fr",
  "timestamp": "2026-03-28T10:15:00.000Z"
}

translations[] preserves the request order. sources[] mirrors that order and is one of:

• approved: returned from approved stored translations
• machine: generated by machine translation
• fallback: source text was returned unchanged

Errors and runtime headers

Condition	Typical status
Invalid or missing project key	401 or 404
Validation failure	400
Feature not enabled for the project	403
Rate limit exceeded	429

Some responses may include X-SDK-FailOpen: true when a bounded quota fail-open path was used.

Rate limiting

Kalima applies layered request controls across:

• IP-level limits
• Project-level limits
• Global service limits

Do not rely on exact numeric limits staying fixed. Build clients to back off on 429 and retry safely.

Support

Need help shipping this integration?

If you hit a blocker, contact Kalima with your project key, target environment, and a short description of what failed.

Contact KalimaEmail info@kalima.digital