Skip to content

API Reference

Jump to bottom
TenzinGayche edited this page Dec 15, 2025 · 1 revision

API Reference

Complete documentation for all endpoints in the LangGraph Translation API.

Base URL: http://localhost:8001 (development)

📋 Table of Contents

System Endpoints

GET /health

Check API status and available models.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "available_models": {
    "claude-sonnet-4-20250514": {
      "provider": "Anthropic",
      "description": "Claude Sonnet 4.0",
      "capabilities": ["text", "reasoning", "translation"],
      "context_window": 200000
    }
  }
}

GET /models

Get all supported translation models.

Response:

{
  "claude-sonnet-4-20250514": {
    "provider": "Anthropic",
    "description": "Claude Sonnet 4.0 (2025-05-14)",
    "capabilities": ["text", "reasoning", "translation"],
    "context_window": 200000
  },
  "gemini-2.5-pro": {
    "provider": "Google",
    "description": "Gemini 2.5 Pro - Default thinking enabled",
    "capabilities": ["text", "reasoning", "translation"],
    "context_window": 30720
  }
}

POST /system/clear-cache

Clear the server-side cache for all memoized functions.

Response:

{
  "status": "cache_cleared",
  "cleared_items": 42
}

Translation Endpoints

POST /translate

Translate multiple Buddhist texts with batch processing.

Request Body:

{
  "texts": ["om mani padme hum", "བྱང་ཆུབ་སེམས་དཔའ"],
  "target_language": "english",
  "model_name": "claude-sonnet-4-20250514",
  "text_type": "Buddhist text",
  "batch_size": 5,
  "model_params": {},
  "user_rules": "Use traditional terminology"
}
Field Type Required Description
texts string[] ✅ List of texts to translate (1-100)
target_language string ✅ Target language
model_name string ❌ Model to use (default: "claude")
text_type string ❌ Type of text (default: "Buddhist text")
batch_size int ❌ Texts per batch (1-50, default: 5)
model_params object ❌ Additional model parameters
user_rules string ❌ Custom translation rules

Response:

{
  "success": true,
  "results": [
    {
      "original_text": "om mani padme hum",
      "translated_text": "Om Mani Padme Hum (Hail the jewel in the lotus)",
      "metadata": {
        "batch_id": "abc123",
        "model_used": "claude-sonnet-4-20250514",
        "text_type": "mantra"
      }
    }
  ],
  "metadata": {
    "initialized_at": "2025-01-15T10:00:00Z",
    "completed_at": "2025-01-15T10:00:05Z",
    "total_processing_time": 5.0,
    "successful_batches": 1,
    "failed_batches": 0,
    "total_translations": 2
  },
  "errors": []
}

POST /translate/single

Translate a single Buddhist text.

Request Body:

{
  "text": "བྱང་ཆུབ་སེམས་དཔའ",
  "target_language": "english",
  "model_name": "claude-sonnet-4-20250514",
  "text_type": "Buddhist text",
  "model_params": {},
  "user_rules": null
}

Response: Same as /translate

POST /translate/stream

Stream translation progress with real-time updates (SSE).

Request Body: Same as /translate

Response: text/event-stream

Event: batch_completed

{
  "timestamp": "2025-01-15T10:00:02Z",
  "type": "batch_completed",
  "status": "batch_completed",
  "batch_results": [
    {
      "original_text": "...",
      "translated_text": "...",
      "metadata": {}
    }
  ]
}

Event: completion

{
  "timestamp": "2025-01-15T10:00:05Z",
  "type": "completion",
  "status": "completed",
  "results": [...]
}

POST /translate/single/stream

Stream single text translation with real-time progress.

Request Body: Same as /translate/single

Response: text/event-stream

Glossary Endpoints

POST /glossary/extract

Extract a consolidated glossary from translated texts.

Request Body:

{
  "items": [
    {
      "original_text": "བྱང་ཆུབ་སེམས",
      "translated_text": "bodhicitta",
      "metadata": {}
    }
  ],
  "model_name": "claude-sonnet-4-20250514",
  "batch_size": 5
}

Response:

{
  "terms": [
    {
      "source_term": "བྱང་ཆུབ་སེམས",
      "translated_term": "bodhicitta"
    },
    {
      "source_term": "སྟོང་པ་ཉིད",
      "translated_term": "emptiness"
    }
  ]
}

POST /glossary/extract/stream

Extract glossary with real-time streaming progress.

Request Body: Same as /glossary/extract

Response: text/event-stream

Event: glossary_batch_completed

{
  "timestamp": "...",
  "type": "glossary_batch_completed",
  "status": "batch_complete",
  "terms": [{"source_term": "...", "translated_term": "..."}]
}

Event: completion

{
  "timestamp": "...",
  "type": "completion",
  "status": "completed",
  "glossary": {"terms": [...]}
}

Standardization Endpoints

POST /standardize/analyze

Analyze translations to find inconsistent glossary terms.

Request Body:

{
  "items": [
    {
      "original_text": "བྱང་ཆུབ་སེམས་བསྐྱེད",
      "translated_text": "generate bodhicitta",
      "glossary": [
        {"source_term": "བྱང་ཆུབ་སེམས", "translated_term": "bodhicitta"}
      ]
    },
    {
      "original_text": "བྱང་ཆུབ་སེམས་བསྐྱེད",
      "translated_text": "generate awakening mind",
      "glossary": [
        {"source_term": "བྱང་ཆུབ་སེམས", "translated_term": "awakening mind"}
      ]
    }
  ]
}

Response:

{
  "inconsistent_terms": {
    "བྱང་ཆུབ་སེམས": ["bodhicitta", "awakening mind"]
  }
}

POST /standardize/apply

Apply standardization rules to translations.

Request Body:

{
  "items": [
    {
      "original_text": "བྱང་ཆུབ་སེམས་བསྐྱེད",
      "translated_text": "generate awakening mind",
      "glossary": []
    }
  ],
  "standardization_pairs": [
    {
      "source_word": "བྱང་ཆུབ་སེམས",
      "standardized_translation": "bodhicitta"
    }
  ],
  "model_name": "claude-sonnet-4-20250514",
  "user_rules": null
}

Response:

{
  "updated_items": [
    {
      "original_text": "བྱང་ཆུབ་སེམས་བསྐྱེད",
      "translated_text": "generate bodhicitta",
      "glossary": [
        {"source_term": "བྱང་ཆུབ་སེམས", "translated_term": "bodhicitta"}
      ]
    }
  ]
}

POST /standardize/apply/stream

Apply standardization with streaming progress.

Request Body: Same as /standardize/apply

Response: text/event-stream

Event: retranslation_completed

{
  "timestamp": "...",
  "type": "retranslation_completed",
  "status": "item_updated",
  "index": 0,
  "updated_item": {...}
}

UCCA Endpoints

POST /ucca/generate

Generate a UCCA graph for a single input text.

Request Body:

{
  "input_text": "བྱང་ཆུབ་སེམས་དཔའ་སེམས་ཅན་ཐམས་ཅད་ལ་སྙིང་རྗེ་བསྐྱེད།",
  "commentary_1": "Optional commentary 1",
  "commentary_2": "Optional commentary 2",
  "commentary_3": "Optional commentary 3",
  "sanskrit_text": "Optional Sanskrit parallel",
  "model_name": "claude-sonnet-4-20250514",
  "model_params": {}
}

Response:

{
  "ucca_graph": {
    "scenes": [...],
    "participants": [...],
    "processes": [...]
  },
  "raw_json": "..."
}

POST /ucca/generate/batch

Generate UCCA graphs for multiple texts.

Request Body:

{
  "items": [
    {
      "input_text": "...",
      "commentary_1": null,
      "commentary_2": null,
      "commentary_3": null,
      "sanskrit_text": null
    }
  ],
  "model_name": "claude-sonnet-4-20250514",
  "model_params": {},
  "batch_size": 5
}

Response:

[
  {
    "index": 0,
    "ucca_graph": {...}
  },
  {
    "index": 1,
    "error": "Failed to parse..."
  }
]

POST /ucca/generate/stream

Generate UCCA graphs with streaming progress.

Request Body: Same as /ucca/generate/batch

Response: text/event-stream

Gloss Endpoints

POST /gloss/generate

Generate gloss analysis for a single text.

Request Body:

{
  "input_text": "བྱང་ཆུབ་སེམས་དཔའ",
  "ucca_interpretation": null,
  "commentary_1": null,
  "commentary_2": null,
  "commentary_3": null,
  "sanskrit_text": null,
  "model_name": "claude-sonnet-4-20250514",
  "model_params": {}
}

Response:

{
  "standardized_text": "བྱང་ཆུབ་ སེམས་དཔའ་",
  "note": "Segmented with standard spacing",
  "analysis": "[{\"segment\": \"...\", \"meaning\": \"...\"}]",
  "glossary": {"བྱང་ཆུབ": "enlightenment"},
  "raw_output": "..."
}

POST /gloss/generate/batch

Generate gloss for multiple texts.

Request Body:

{
  "items": [
    {
      "input_text": "...",
      "ucca_interpretation": null,
      "commentary_1": null,
      "commentary_2": null,
      "commentary_3": null,
      "sanskrit_text": null
    }
  ],
  "model_name": "claude-sonnet-4-20250514",
  "model_params": {},
  "batch_size": 5
}

Response:

[
  {
    "index": 0,
    "standardized_text": "...",
    "note": "...",
    "analysis": "...",
    "glossary": {...}
  }
]

POST /gloss/generate/stream

Generate gloss with streaming progress.

Request Body: Same as /gloss/generate/batch

Response: text/event-stream

Workflow Endpoints

POST /workflow/run

Run a combo-key based translation workflow.

Request Body:

{
  "combo_key": "source+ucca+gloss",
  "input": {
    "source": "བྱང་ཆུབ་སེམས་དཔའ",
    "ucca": {"scenes": [...]},
    "gloss": {"glossary": {...}},
    "commentaries": ["Commentary 1", "Commentary 2"],
    "sanskrit": "bodhisattva",
    "target_language": "english",
    "model": "claude-sonnet-4-20250514"
  },
  "model_name": "claude-sonnet-4-20250514",
  "model_params": {},
  "custom_prompt": null
}
Field Type Required Description
combo_key string ✅ Workflow path (e.g., "source+ucca")
input.source string ✅ Source text (always required)
input.ucca object ❌ UCCA graph JSON
input.gloss object ❌ Gloss analysis JSON
input.commentaries string[] ❌ Up to 3 commentaries
input.sanskrit string ❌ Sanskrit parallel
input.target_language string ❌ Target language
custom_prompt string ❌ Custom prompt template

Custom Prompt Placeholders:

  • {source} - Source text (required)
  • {ucca} - UCCA JSON
  • {gloss} - Gloss JSON
  • {commentary1}, {commentary2}, {commentary3} - Individual commentaries
  • {commentaries} - All commentaries block
  • {sanskrit} - Sanskrit text
  • {target_language} - Target language

Response:

{
  "combo_key": "gloss+source+ucca",
  "translation": "The bodhisattva..."
}

POST /workflow/run/batch

Run workflow for multiple inputs.

Request Body:

{
  "combo_key": "source+ucca",
  "items": [
    {
      "source": "...",
      "ucca": {...}
    }
  ],
  "model_name": "claude-sonnet-4-20250514",
  "model_params": {}
}

Response:

[
  {
    "index": 0,
    "translation": "..."
  },
  {
    "index": 1,
    "error": "..."
  }
]

Editor Endpoints

POST /editor/comment

Generate grounded commentary for a translation thread.

Request Body:

{
  "messages": [
    {"role": "user", "content": "The translation seems unclear @Comment"}
  ],
  "references": [
    {"type": "commentary", "content": "Explanation from..."}
  ],
  "options": {
    "model_name": "gemini-2.5-pro",
    "mention_scope": "last",
    "max_mentions": 5
  }
}

Trigger: The last message must contain @Comment to activate.

Response:

{
  "mentions": ["@User1"],
  "comment_text": "@User1 The term 'bodhicitta' should be... [ref-commentary-1]",
  "citations_used": ["ref-commentary-1"],
  "metadata": {
    "triggered_by": "@Comment",
    "model_used": "gemini-2.5-pro"
  }
}

POST /editor/comment/stream

Generate commentary with streaming.

Request Body: Same as /editor/comment

Response: text/event-stream

Events:

  • initialization - Mentions and model info
  • comment_delta - Streaming text chunks
  • completion - Final comment with citations

Dharmamitra Proxy Endpoints

POST /dharmamitra/knn-translate-mitra

Proxy to Dharmamitra KNN Translate (SSE streaming).

Request Body:

{
  "query": "བྱང་ཆུབ་སེམས",
  "language": "english",
  "password": "optional-override"
}

Response: text/event-stream

POST /dharmamitra/knn-translate-gemini-no-stream

Proxy to Dharmamitra Gemini endpoint (non-streaming).

Request Body:

{
  "query": "བྱང་ཆུབ་སེམས",
  "language": "english",
  "password": "optional-override"
}

Response: JSON from upstream Dharmamitra API

Pipeline Endpoint

POST /pipeline/run

Run a customizable multi-stage pipeline.

Request Body:

{
  "stages": ["translate", "extract_glossary", "analyze", "apply_standardization"],
  "texts": ["བྱང་ཆུབ་སེམས"],
  "target_language": "english",
  "model_name": "claude-sonnet-4-20250514",
  "text_type": "Buddhist text",
  "batch_size": 5,
  "model_params": {},
  "user_rules": null,
  "items": null,
  "standardization_pairs": [
    {"source_word": "བྱང་ཆུབ་སེམས", "standardized_translation": "bodhicitta"}
  ]
}

Available Stages (in order):

  1. translate - Translation workflow
  2. extract_glossary - Glossary extraction
  3. analyze - Consistency analysis
  4. apply_standardization - Apply rules

Response:

{
  "results": [...],
  "glossary": {"terms": [...]},
  "inconsistent_terms": {...},
  "updated_items": [...],
  "metadata": {"stages": [...]}
}

Error Responses

All endpoints return standard error responses:

400 Bad Request:

{
  "detail": "Model 'invalid-model' is not available. Available models: [...]"
}

500 Internal Server Error:

{
  "detail": "Internal server error: ..."
}

🔗 See Also

LangGraph Translation API | GitHub | OpenPecha | Apache 2.0 License

📚 Documentation

🏠 Home

Getting Started

Core Concepts

API Documentation

Quick Links

Clone this wiki locally