Helper Endpoints

Utility endpoints for language detection, engine information, and usage statistics.

---

Language Detection

Detect Language

POST /v1/detect-language

Detect the language of a text sample. Useful for auto-detecting source language before translation.

Authentication: X-API-Key header

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/detect-language \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bonjour, comment allez-vous?"}'

import requests

resp = requests.post(
    "https://app.falara.io/v1/detect-language",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"text": "Bonjour, comment allez-vous?"},
)
lang = resp.json()["language"]  # "fr"

const resp = await fetch(
  "https://app.falara.io/v1/detect-language",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text: "Bonjour, comment allez-vous?" }),
  }
);
const { language } = await resp.json();

Request Body

Field	Type	Required	Description
text	string	yes	Text to analyze (min 3 characters)

Response 200 OK

{
  "language": "fr",
  "confidence": 0.98,
  "alternatives": [
    {"language": "it", "confidence": 0.01},
    {"language": "es", "confidence": 0.01}
  ]
}

Field	Type	Description
language	string	Detected BCP-47 language code
confidence	float	Confidence score (0.0 - 1.0)
alternatives	list	Other possible languages with lower confidence

---

Translation Engines

List Available Engines

GET /v1/engines

List all translation engines available for your account.

Authentication: X-API-Key header

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/engines \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/engines",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
engines = resp.json()["engines"]

const resp = await fetch(
  "https://app.falara.io/v1/engines",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { engines } = await resp.json();

Response 200 OK

{
  "engines": [
    {
      "id": "claude",
      "name": "Claude",
      "provider": "anthropic",
      "default": true,
      "quality_levels": ["standard", "premium"]
    },
    {
      "id": "deepl",
      "name": "DeepL",
      "provider": "deepl",
      "default": false,
      "quality_levels": ["standard"]
    },
    {
      "id": "gemini",
      "name": "Gemini",
      "provider": "google",
      "default": false,
      "quality_levels": ["standard", "premium"]
    },
    {
      "id": "gpt4",
      "name": "GPT-4",
      "provider": "openai",
      "default": false,
      "quality_levels": ["standard", "premium"]
    }
  ],
  "default_engine": "claude"
}

Field	Type	Description
id	string	Engine identifier for API requests
name	string	Human-readable engine name
provider	string	AI provider
default	boolean	Whether this is the default engine
quality_levels	list	Supported quality levels

---

Usage Statistics

Usage Breakdown

GET /v1/usage/breakdown

Get detailed usage statistics broken down by user, API key, and time period.

Authentication: X-API-Key header (requires admin or owner role)

Query Parameters

Parameter	Type	Required	Description
period	string	no	day, week, month (default: month)
start_date	string	no	Start date (ISO 8601)
end_date	string	no	End date (ISO 8601)

cURLPythonJavaScript

curl -X GET "https://app.falara.io/v1/usage/breakdown?period=month" \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/usage/breakdown",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"period": "month"},
)
breakdown = resp.json()

const resp = await fetch(
  "https://app.falara.io/v1/usage/breakdown?period=month",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const breakdown = await resp.json();

Response 200 OK

{
  "period": "2026-04",
  "total_words": 125000,
  "total_jobs": 342,
  "by_user": [
    {
      "user_id": "usr_abc123",
      "email": "user@example.com",
      "words": 75000,
      "jobs": 210
    },
    {
      "user_id": "usr_def456",
      "email": "colleague@example.com",
      "words": 50000,
      "jobs": 132
    }
  ],
  "by_api_key": [
    {
      "key_hash": "k_abc...",
      "name": "Production",
      "words": 100000,
      "jobs": 280
    },
    {
      "key_hash": "k_def...",
      "name": "Development",
      "words": 25000,
      "jobs": 62
    }
  ],
  "by_engine": [
    {"engine": "claude", "words": 80000},
    {"engine": "deepl", "words": 30000},
    {"engine": "gemini", "words": 15000}
  ]
}

---

Errors

Status	Reason
401 Unauthorized	Missing or invalid API key
400 Bad Request	Text too short for detection
403 Forbidden	Insufficient permissions for usage breakdown