API Reference

Programmatic access to professional-grade translation with consistent terminology. Authenticate with a Bearer token and start translating in minutes.

Base URL: https://ravira.dev/api/v1
Bearer token
v1

Quick Start

Three steps to your first translation:

  1. 1. Create an account at ravira.dev/register
  2. 2. Purchase a character pack and generate an API key in Settings → API
  3. 3. Make your first request:
curl -X POST https://ravira.dev/api/v1/translate \
  -H "Authorization: Bearer rk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world!", "source_lang": "en", "target_lang": "ro"}'

Response:

{
  "translated_text": "Bună ziua, lume!",
  "characters_charged": 13,
  "source_lang": "en",
  "target_lang": "ro"
}

Authentication

All API requests require a Bearer token in the Authorization header. API keys start with rk_live_ and are generated in your account settings.

Important: Your API key is shown only once when created. Store it securely: it cannot be recovered.
Authorization: Bearer rk_live_YOUR_API_KEY

Endpoints

POST/api/v1/translate

Translate text. Requires authentication. Characters are charged on success.

ParameterTypeRequiredDescription
textstringYesText to translate (max 100,000 chars)
source_langstringNoSource language code. Default: auto
target_langstringNoTarget language code. Default: en
GET/api/v1/usage

Returns current character balance and usage. Requires authentication.

curl https://ravira.dev/api/v1/usage \
  -H "Authorization: Bearer rk_live_YOUR_API_KEY"
{
  "characters_balance": 500000,
  "characters_used": 12500,
  "characters_expires_at": "2027-01-01T00:00:00"
}
GET/api/v1/languages

Returns list of supported languages. No authentication required.

curl https://ravira.dev/api/v1/languages

Code Examples

Python

import requests

API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"

def translate(text, target_lang="ro", source_lang="auto"):
    response = requests.post(
        f"{BASE_URL}/translate",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"text": text, "source_lang": source_lang, "target_lang": target_lang}
    )
    response.raise_for_status()
    return response.json()["translated_text"]

result = translate("Hello, world!", target_lang="ro")
print(result)  # Bună ziua, lume!

JavaScript

const API_KEY = "rk_live_YOUR_API_KEY";
const BASE_URL = "https://ravira.dev/api/v1";

async function translate(text, targetLang = "ro", sourceLang = "auto") {
  const response = await fetch(`${BASE_URL}/translate`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text, source_lang: sourceLang, target_lang: targetLang }),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const data = await response.json();
  return data.translated_text;
}

const result = await translate("Hello, world!", "ro");
console.log(result); // Bună ziua, lume!

AI Apps (MCP)

RAVIRA runs a Model Context Protocol (MCP) server. AI apps that support remote MCP servers, such as Claude, ChatGPT, Cursor, VS Code and Claude Code, can translate with RAVIRA directly from a chat, an editor or a terminal, using your RAVIRA balance.

Server URL

https://ravira.dev/mcp

How connecting works

  1. Add https://ravira.dev/mcp as a remote (HTTP) MCP server in your app.
  2. Your browser opens the RAVIRA connection page. Sign in if needed.
  3. Check the domain shown on the page, review the requested access and approve.
  4. The app appears in your Profile, API tab, under Connected applications, where you can disconnect it at any time.

Setup examples

Menus can change between app versions; the server URL is always the same.

Claude (claude.ai and the Claude apps)

Settings, Connectors, Add custom connector, then paste the server URL.

Claude Code (terminal)

claude mcp add --transport http ravira https://ravira.dev/mcp

Then run /mcp inside Claude Code to sign in.

Cursor

{
  "mcpServers": {
    "ravira": { "url": "https://ravira.dev/mcp" }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "ravira": { "type": "http", "url": "https://ravira.dev/mcp" }
  }
}

ChatGPT

In settings, open Connectors (developer mode may need to be enabled) and create a custom connector with the server URL.

Available tools

ToolWhat it doesPermission
ravira_translateTranslates text with the right terminology and your glossarymcp_translate
ravira_usageShows your character balancemcp_usage
ravira_languagesLists the supported languagesmcp_languages
ravira_user_glossaryReads and edits your personal glossarymcp_glossary

Permissions and safety

  • Each app gets only the access you approve on the RAVIRA connection page.
  • Verified apps, such as Claude, connect without a warning. Other apps are marked Unverified and need an explicit confirmation. Apps running on your own computer (localhost), such as editors and command-line tools, are labelled as such.
  • Unverified apps do not get access to your personal glossary unless they ask for it and you approve it.
  • A connected app can only translate and read what its permissions allow. It cannot manage your account, API keys or payments.
  • Resetting your password with Forgot password disconnects all apps and revokes all API keys.

Using an API key instead

Apps that let you set custom headers can use an API key instead of signing in:

Authorization: Bearer rk_live_YOUR_API_KEY

Connections made with an API key do not appear under Connected applications. To stop them, revoke the key in your API keys list.

Error Codes

HTTPError codeDescription
401invalid_api_keyMissing, invalid, or revoked API key.
402insufficient_balanceAccount has no characters remaining. Purchase more at ravira.dev/topup.
429rate_limit_exceededToo many requests. Slow down and retry after the retry_after value (seconds).
400validation_errorInvalid request parameters.
500server_errorInternal server error. Retry after a short delay.

Rate Limits

Rate limits apply per account, not per API key.

  • 60 requests/minute per account across all API keys
  • When exceeded, the API returns HTTP 429 with a retry_after field (seconds)
  • Up to 5 API keys per account for project organization

Use Cases

E-commerce

Multilingual product listings

A seller on Amazon or eBay wants to list products in 5 languages automatically. One API call per language, with consistent terminology across all markets.

import requests

API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"

def translate_product(product):
    languages = {"ro": "Romanian", "de": "German", "fr": "French", "es": "Spanish"}
    translations = {}
    for lang_code, lang_name in languages.items():
        response = requests.post(
            BASE_URL + "/translate",
            headers={"Authorization": "Bearer " + API_KEY},
            json={"text": product["title"] + "

" + product["description"],
                  "source_lang": "en", "target_lang": lang_code}
        )
        translations[lang_code] = response.json()["translated_text"]
    return translations

product = {
    "title": "Wireless Noise-Cancelling Headphones",
    "description": "Premium over-ear headphones with 30-hour battery."
}
result = translate_product(product)
SaaS

Localized user notifications

A SaaS platform translates all notification templates when a new user sets their preferred language. No static translation files: dynamic and always up to date.

const API_KEY = "rk_live_YOUR_API_KEY";
const BASE_URL = "https://ravira.dev/api/v1";

async function localizeNotifications(userId, targetLang) {
  const templates = {
    welcome: "Welcome to our platform! Your account is ready.",
    trial_ending: "Your free trial ends in 3 days.",
    payment_success: "Payment confirmed. Thank you!",
    usage_alert: "You have used 80% of your monthly quota."
  };
  const localized = {};
  for (const [key, text] of Object.entries(templates)) {
    const res = await fetch(BASE_URL + "/translate", {
      method: "POST",
      headers: {
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ text, source_lang: "en", target_lang: targetLang })
    });
    localized[key] = (await res.json()).translated_text;
  }
  return localized;
}

// New user from Romania
localizeNotifications("user_123", "ro").then(t => {
  console.log(t.welcome);
});
Legal

Contract pre-translation

A law firm receives contracts in foreign languages and needs a fast pre-translation before sending to a certified translator. Consistent legal terminology saves review time.

import requests

API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"

def pretranslate_contract(contract_text, source_lang):
    """Pre-translate a contract for internal review."""
    response = requests.post(
        BASE_URL + "/translate",
        headers={"Authorization": "Bearer " + API_KEY},
        json={
            "text": contract_text,
            "source_lang": source_lang,
            "target_lang": "en"
        }
    )
    return response.json()["translated_text"]

# Translate a German contract for English-speaking lawyers
with open("vertrag_2026.txt", "r") as f:
    german_contract = f.read()

english_draft = pretranslate_contract(german_contract, "de")
print("Pre-translation ready for legal review.")
print(english_draft[:200])
Journalism

International news monitoring

A newsroom monitors international sources and automatically translates relevant articles for editors. Runs as a scheduled job every hour.

import requests
import schedule
import time

API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"

def translate_article(article, source_lang):
    response = requests.post(
        BASE_URL + "/translate",
        headers={"Authorization": "Bearer " + API_KEY},
        json={"text": article, "source_lang": source_lang, "target_lang": "en"}
    )
    return response.json()["translated_text"]

def monitor_and_translate():
    # Fetch articles from your news source here
    articles = [
        {"text": "Neue Wirtschaftsdaten zeigen starkes Wachstum...", "lang": "de"},
        {"text": "Les negociations commerciales reprennent...", "lang": "fr"},
    ]
    for article in articles:
        translated = translate_article(article["text"], article["lang"])
        print("Translated:", translated[:80] + "...")

# Run every hour
schedule.every().hour.do(monitor_and_translate)
monitor_and_translate()  # Run immediately on start
HR

Multilingual job postings

A company posting jobs across Europe translates each listing automatically. One source in English, published in 6 languages within seconds.

const API_KEY = "rk_live_YOUR_API_KEY";
const BASE_URL = "https://ravira.dev/api/v1";

const TARGET_MARKETS = ["de", "fr", "es", "it", "pl", "ro"];

async function publishJobPosting(jobDescription) {
  const postings = {};
  for (const lang of TARGET_MARKETS) {
    const res = await fetch(BASE_URL + "/translate", {
      method: "POST",
      headers: {
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        text: jobDescription,
        source_lang: "en",
        target_lang: lang
      })
    });
    postings[lang] = (await res.json()).translated_text;
  }
  console.log("Published in " + Object.keys(postings).length + " languages");
  return postings;
}

const job = "Senior Backend Engineer. Remote. Competitive salary.";
publishJobPosting(job);
Technical

Software documentation

A developer tool translates its documentation to reach international users. Markdown files are translated while code blocks remain untouched.

import requests
import re

API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"

def translate_markdown(md_text, target_lang):
    """Translate markdown, preserving code blocks."""
    # Extract code blocks before translation
    code_blocks = {}
    def save_code(match):
        key = f"CODE_BLOCK_{len(code_blocks)}"
        code_blocks[key] = match.group(0)
        return key
    protected = re.sub(r"```[\s\S]*?```", save_code, md_text)
    # Translate text only
    response = requests.post(
        BASE_URL + "/translate",
        headers={"Authorization": "Bearer " + API_KEY},
        json={"text": protected, "source_lang": "en", "target_lang": target_lang}
    )
    translated = response.json()["translated_text"]
    # Restore code blocks
    for key, block in code_blocks.items():
        translated = translated.replace(key, block)
    return translated

with open("README.md") as f:
    readme = f.read()
translated_readme = translate_markdown(readme, "ro")
print(translated_readme[:300])
Medical

Patient intake forms

A clinic translates patient intake forms for international patients. For internal use and patient comfort, always reviewed by qualified medical staff before clinical decisions.

import requests

API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"

def translate_intake_form(form_data, patient_lang):
    """
    Translate patient intake form for non-English speaking patients.
    For internal use only. Always reviewed by qualified medical staff.
    """
    fields_to_translate = [
        "chief_complaint", "medical_history", "current_medications", "allergies"
    ]
    translated = {}
    for field in fields_to_translate:
        if field in form_data:
            response = requests.post(
                BASE_URL + "/translate",
                headers={"Authorization": "Bearer " + API_KEY},
                json={
                    "text": form_data[field],
                    "source_lang": patient_lang,
                    "target_lang": "en"
                }
            )
            translated[field] = response.json()["translated_text"]
    return translated

patient_form = {
    "chief_complaint": "Durere puternica in piept de 2 zile",
    "allergies": "Penicilina, Ibuprofen"
}
english_form = translate_intake_form(patient_form, "ro")
print("For medical staff review:", english_form)

Ready to start?

Generate your API key in seconds. No setup fees, no subscriptions: pay only for the characters you translate.

Questions? Write to us at humans@ravira.dev