API संदर्भ

त्वरित शुरुआत

तीन चरणों में Entity Enricher इंटीग्रेट करें:

प्रमाणीकरण

सभी API एंडपॉइंट्स (लॉगिन/रजिस्टर को छोड़कर) को प्रमाणीकरण की आवश्यकता होती है। संगठन एक्सेस की के साथ X-API-Key हेडर का उपयोग करें:

curl -H "X-API-Key: ent_your_key_here" \
     https://your-instance.example.com/api/enrichment/options

API Keys पेज से या POST /api/auth/api-keys के माध्यम से API की बनाएँ। की के प्रकार और अनुमतियों के विवरण के लिए API Keys गाइड देखें।

प्रमुख एंडपॉइंट

SSE स्ट्रीमिंग

Enrichment, schema जनरेशन और fusion ऑपरेशन रियल-टाइम प्रगति के लिए Server-Sent Events का उपयोग करते हैं। एक जॉब शुरू करें, एक job_id प्राप्त करें, फिर SSE स्ट्रीम से कनेक्ट करें:

Python उदाहरण

एक संपूर्ण workflow जो schema सूचीबद्ध करता है, enrichment शुरू करता है, परिणाम stream करता है, और अंतिम record प्राप्त करता है:

import httpx
import json

BASE = "https://your-instance.example.com"
KEY = "ent_your_api_key"
HEADERS = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1. List saved schemas
schemas = httpx.get(f"{BASE}/api/schema/saved", headers=HEADERS).json()
schema_id = schemas["schemas"][0]["id"]

# 2. Start enrichment
resp = httpx.post(f"{BASE}/api/single/enrich/stream", headers=HEADERS, json={
    "entity_data": {"name": "Moderna Inc", "country": "US"},
    "schema_id": schema_id,
    "models": ["anthropic::claude-sonnet-4-5-20250514"],
    "strategy": "multi_expertise",
})
job_id = resp.json()["job_id"]

# 3. Stream SSE events
record_id = None
with httpx.stream("GET", f"{BASE}/api/llm/stream/{job_id}", headers=HEADERS) as stream:
    for line in stream.iter_lines():
        if not line.startswith("data: "):
            continue
        event = json.loads(line[6:])

        if event["type"] == "model_completed" and event.get("record_id"):
            record_id = event["record_id"]
        elif event["type"] == "completed":
            break

# 4. Retrieve the enrichment record
if record_id:
    record = httpx.get(f"{BASE}/api/records/{record_id}", headers=HEADERS).json()
    print(json.dumps(record["structured_output"], indent=2))

curl उदाहरण

दो मॉडल के साथ बैच एनरिचमेंट शुरू करें और परिणाम स्ट्रीम करें:

# Start batch enrichment
JOB_ID=$(curl -s -X POST \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  "$BASE/api/enrichment/batch/start" \
  -d '{
    "entities": [
      {"name": "Pfizer Inc", "country": "US"},
      {"name": "Roche", "country": "CH"}
    ],
    "schema_id": "your-schema-uuid",
    "models": ["anthropic::claude-sonnet-4-5-20250514", "openai::gpt-4o"],
    "strategy": "multi_expertise",
    "arbitration_model": "anthropic::claude-sonnet-4-5-20250514"
  }' | jq -r '.job_id')

# Stream events
curl -N -H "X-API-Key: $KEY" "$BASE/api/llm/stream/$JOB_ID"

# List resulting records
curl -s -H "X-API-Key: $KEY" \
  "$BASE/api/records?type=enrichment&page_size=10" | jq '.records'

त्रुटि प्रबंधन

एरर रिस्पॉन्स में एक detail फ़ील्ड होता है जिसमें पढ़ने योग्य एरर मैसेज होता है। प्लान और बिलिंग फ़ेल्योर (402) के साथ अतिरिक्त रूप से एक स्ट्रक्चर्ड बॉडी आती है जिसमें एक स्थिर code होता है — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — साथ ही संबंधित लिमिट और उपयोग की संख्याएँ, ताकि क्लाइंट टेक्स्ट पार्स करने के बजाय कारण के आधार पर ब्रांच कर सके। अगर स्ट्रीम के बीच में कुछ फ़ेल होता है, तो SSE स्ट्रीम एक error इवेंट टाइप भेजती हैं, अंतिम completed इवेंट से पहले।

मॉडल कंपोज़िट कुंजियाँ

मॉडल की पहचान provider_name::model_name फ़ॉर्मेट में कंपोज़िट कुंजियों द्वारा की जाती है। उपलब्ध मॉडल और उनकी कुंजियाँ सूचीबद्ध करने के लिए GET /api/enrichment/options का उपयोग करें।

एनरिचमेंट, स्कीमा जनरेशन और सैंपल जनरेशन पर model पैरामीटर वैकल्पिक है: इसे छोड़ दें (या literal "auto" पास करें) और सर्वर आपके संगठन का डिफ़ॉल्ट मॉडल चुन लेता है — यदि Settings में सेट है तो पिन किया गया प्रति-कार्य डिफ़ॉल्ट, अन्यथा आपके स्कोरिंग-स्रोत बेंचमार्क से सर्वश्रेष्ठ समग्र स्कोर वाला मॉडल। options रिस्पॉन्स का default_models फ़ील्ड दिखाता है कि ऑटो वर्तमान में किसमें रिज़ॉल्व होता है, और model_auto_selected SSE इवेंट हर जॉब पर चयन की रिपोर्ट देता है। ऑटो हमेशा एकल मॉडल में रिज़ॉल्व होता है (यह कभी फ्यूज़न ट्रिगर नहीं करता); पुनरुत्पादनीय पाइपलाइन के लिए, स्पष्ट मॉडल पास करते रहें।

Request विकल्प auto pick को सीमित करते हैं: enable_web_search: true के साथ केवल वेब-सर्च-सक्षम models पर विचार किया जाता है (options response का default_models_web_search फ़ील्ड उस pick का पूर्वावलोकन दिखाता है), और binary attachments के लिए ऐसे model की आवश्यकता होती है जो उन्हें पढ़ सके (PDF, vision, audio)। जब कोई योग्य model इन सीमाओं को पूरा नहीं करता, तो विकल्प को चुपचाप हटाने के बजाय request HTTP 400 no_capable_default_model के साथ विफल हो जाती है।

इंटरैक्टिव API डॉक्युमेंटेशन

एप्लिकेशन में रिक्वेस्ट/रिस्पॉन्स उदाहरणों के साथ इंटरैक्टिव API दस्तावेज़ शामिल हैं। एक्सेस के लिए एडमिन प्रमाणीकरण आवश्यक है: