API Documentation

Everything you need to integrate TAO's translation API

Quick Start

1. Get Your API Key

Generate an API key from your dashboard

Dashboard → Settings → API Keys → Generate New Key

2. Make Your First Request

Send a translation request with your API key

POST /api/v1/translate
Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://api.tao-translate.com/api/v1/translate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_language": "en",
    "target_language": "es",
    "text": "Welcome to our new product launch!"
  }'

Authentication

TAO uses Bearer token authentication. Include your API key in the Authorization header of every request.

Header Format: Authorization: Bearer YOUR_API_KEY

Authentication Methods

Method Use Case Example
API Key Server-to-server integration Bearer sk_live_...
JWT Token Web application sessions Bearer eyJhbGc...
Security Note:

Never expose your API key in client-side code or public repositories. Use environment variables to store sensitive credentials.

Language Support

TAO supports 113 languages with auto-detection capability. Language availability depends on your subscription tier.

Tier Capabilities

Tier Languages Characters/Month AI Refinement
Discovery 6 core languages (en, es, fr, de, it, pt) 5,000 None
Professional All 113 languages 1,000,000 Smart AI refinement
Enterprise All 113 languages 8,000,000 Premium AI refinement

Auto-Detection

Set source_language: "auto" to automatically detect the source language. The API will identify the language and proceed with translation.

{
  "source_language": "auto",
  "target_language": "es",
  "text": "This will be automatically detected as English"
}
Discovery Tier Note:

Free tier users attempting to translate non-supported languages will receive a 403 error with upgrade instructions.

Core Translation Endpoints

POST /api/v1/translate

Translate a single text with optional glossary and control vocabulary.

Request Body

{
  "source_language": "en",              // Required: ISO 639-1 code or "auto"
  "target_language": "es",              // Required: ISO 639-1 code
  "text": "Your text to translate",     // Required: 1-50,000 characters
  "mode": "technical",                  // Optional: domain-specific mode
  "strategy": "meta_optional",          // Optional: processing strategy
  "cv_version_ids": ["glcv_set_123"],  // Optional: glossary/control vocab IDs
  "policies": {                         // Optional: processing policies
    "min_gain": 0.25,
    "edit_budget": {
      "max_edits": 10,
      "max_chars_pct": 12
    }
  }
}

Response

{
  "request_id": "req_abc123",
  "translated_text": "Tu texto traducido",
  "quality_tier": "premium",
  "premium_processing": false,
  "glossary_hits": 3,
  "dnt_hits": 1,
  "processing_time_ms": 1247,
  "characters_processed": 28,
  "timestamp": "2025-09-01T10:30:00Z"
}
POST /api/v1/translate/batch

Translate multiple texts in a single request. Maximum 32 texts per batch for Professional/Enterprise tiers.

Request Body

{
  "source_language": "en",
  "target_language": "es",
  "texts": [
    "First text to translate",
    "Second text to translate",
    "Third text to translate"
  ],
  "mode": "technical",
  "cv_version_ids": ["glcv_set_123"]
}

Response

{
  "batch_id": "batch_xyz789",
  "translations": [
    {
      "index": 0,
      "translated_text": "Primer texto traducido",
      "success": true
    },
    {
      "index": 1,
      "translated_text": "Segundo texto traducido",
      "success": true
    },
    {
      "index": 2,
      "translated_text": "Tercer texto traducido",
      "success": true
    }
  ],
  "total_items": 3,
  "successful": 3,
  "failed": 0,
  "processing_time_ms": 2341
}

Glossary & Control Vocabulary (GLCV)

GET /api/v1/glcv/sets

List all your GLCV sets

POST /api/v1/glcv/sets

Create a new GLCV set

GET /api/v1/glcv/sets/{set_id}

Get a specific GLCV set

PUT /api/v1/glcv/sets/{set_id}

Update a GLCV set

POST /api/v1/glcv/sets/{set_id}/terms

Add a term to a GLCV set

DELETE /api/v1/glcv/terms/{term_id}

Delete a term from a GLCV set

POST /api/v1/glcv/sets/{set_id}/bulk-upload

Bulk upload terms from CSV or JSON file

GET /api/v1/glcv/sets/{set_id}/export?format=json

Export GLCV set as JSON or CSV

Example: Creating a GLCV Term

POST /api/v1/glcv/sets/set_123/terms
{
  "term": "Azure DevOps",
  "target_language": "es",
  "target_text": "Azure DevOps",
  "is_dnt": true,
  "term_priority": 100,
  "notes": "Product name - do not translate"
}

Example: Bulk Upload (CSV)

POST /api/v1/glcv/sets/set_123/bulk-upload
Content-Type: multipart/form-data

CSV Format:
term,target_language,target_text,is_dnt,term_priority,notes
Azure DevOps,es,Azure DevOps,true,100,Product name
Kubernetes,es,Kubernetes,true,100,Technology name
dashboard,es,panel de control,false,50,UI term

Example: Export GLCV Set

GET /api/v1/glcv/sets/set_123/export?format=csv

Response: CSV file download
term,target_language,target_text,is_dnt,term_priority,notes
Azure DevOps,es,Azure DevOps,true,100,Product name
Kubernetes,es,Kubernetes,true,100,Technology name
dashboard,es,panel de control,false,50,UI term

Usage & Monitoring

GET /api/v1/usage/current

Get current usage statistics

GET /api/v1/usage/limits

Get your rate limits

GET /api/v1/history

Get translation history

Rate Limits

Rate limits are applied per API key and vary by subscription tier.

Tier Requests/Min Requests/Hour Requests/Day Concurrent
Discovery 10 100 500 1
Professional 60 1,000 10,000 3
Enterprise 300 10,000 100,000 10
Rate Limit Headers:

Every response includes rate limit information in headers:

  • X-RateLimit-Limit - Your rate limit
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - When the limit resets (Unix timestamp)

Error Handling

TAO uses standard HTTP status codes and returns detailed error messages in JSON format.

Error Response Format

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your rate limit of 60 requests per minute",
  "details": {
    "limit": 60,
    "remaining": 0,
    "reset_at": "2025-09-01T10:31:00Z"
  }
}

Common Error Codes

Status Error Code Description
400 invalid_request Invalid request parameters
401 unauthorized Invalid or missing API key
402 quota_exceeded Monthly word quota exceeded
403 forbidden Access denied to resource
429 rate_limit_exceeded Too many requests
500 internal_server_error Server error, please retry

Code Examples

import requests
import json

# Your API configuration
API_KEY = "YOUR_API_KEY"
API_URL = "https://api.tao-translate.com/api/v1/translate"

def translate_text(text, source_lang="en", target_lang="es"):
    """Translate text using TAO API"""
    
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "source_language": source_lang,
        "target_language": target_lang,
        "text": text,
        "strategy": "meta_optional"
    }
    
    response = requests.post(API_URL, headers=headers, json=payload)
    
    if response.status_code == 200:
        return response.json()["translated_text"]
    else:
        print(f"Error: {response.status_code}")
        print(response.json())
        return None

# Example usage
result = translate_text(
    "Welcome to our new product launch!",
    source_lang="en",
    target_lang="es"
)
print(result)  # "¡Bienvenido a nuestro nuevo lanzamiento de producto!"

SDKs & Libraries

Official and community SDKs make it easy to integrate TAO into your applications.

Official SDKs

  • Python: pip install tao-translate
  • Node.js: npm install @tao-translate/sdk
  • PHP: composer require tao-translate/sdk

Community Libraries

  • Ruby: gem install tao_translate
  • Go: go get github.com/tao-translate/go-sdk
  • Java: Maven Central Repository
📚 Need help?

Check out our GitHub repositories for examples and documentation. Join our developer community for support and discussions.

Webhooks (Enterprise)

Enterprise customers can configure webhooks to receive real-time notifications about translation events.

Available Events

  • translation.completed - Translation request completed successfully
  • translation.failed - Translation request failed
  • batch.completed - Batch translation completed
  • quota.warning - 80% of monthly quota consumed
  • quota.exceeded - Monthly quota exceeded

Webhook Payload Example

{
  "event": "translation.completed",
  "timestamp": "2025-09-01T10:30:00Z",
  "data": {
    "request_id": "req_abc123",
    "source_language": "en",
    "target_language": "es",
    "character_count": 150,
    "processing_time_ms": 1247,
    "quality_tier": "premium"
  }
}