मुख्य कंटेंट पर जाएँ
Sursa Developers

क्विकस्टार्ट

यह गाइड आपको पाँच मिनट में शून्य से काम करते इंटीग्रेशन तक ले जाती है: आप API कुंजी बनाएँगे, उसे जाँचेंगे, नॉलेज बेस में एक दस्तावेज़ जोड़ेंगे, उसे खोजेंगे और उसके बारे में सवाल पूछेंगे। हर स्टेप एक HTTP रिक्वेस्ट है। किसी भी उदाहरण में एक बार अपनी भाषा चुनें; पेज के सभी उदाहरण उसके साथ बदल जाते हैं।

भाषा चुनने वाले उदाहरण इस पोर्टल के API का पता इस्तेमाल करते हैं: Sursa क्लाउड में https://api.sursa.com, या आपके अपने इंस्टॉलेशन के API का पता। जहाँ उदाहरण में https://api.example.com दिखे, वहाँ अपने API का पता डालें। अगर पक्का नहीं है कि आपका पता कौन-सा है, तो API का पता और एनवायरनमेंट देखें।

1. API कुंजी बनाएँ

संगठन का एडमिन Sursa में Administration → API keys (एडमिनिस्ट्रेशन → API कुंजियाँ) में कुंजियाँ बनाता है। कुंजी को ऐसा नाम दें, जिससे पता चले कि उसका इस्तेमाल कहाँ होता है (उदाहरण के लिए, “CRM सिंक”), उसका रोल चुनें और, अगर ऐक्सेस को और सीमित करना हो, तो उसके स्कोप भी। कुंजी वह सब कर सकती है, जो उस रोल वाला यूज़र कर सकता है, पर उससे ज़्यादा नहीं, जितना उसके स्कोप अनुमति देते हैं। इस गाइड के लिए editor रोल काफ़ी है।

कुंजी सिर्फ़ एक बार दिखाई जाती है। उसे अपने सिस्टम के सीक्रेट स्टोर में रखें और अपने कोड को एनवायरनमेंट वेरिएबल के ज़रिए दें:

export SURSA_API_KEY="kb_…"

हर रिक्वेस्ट कुंजी को Authorization हेडर में bearer टोकन के रूप में भेजती है। रोल, स्कोप, मियाद और कुंजी रोटेट करने के बारे में API कुंजियाँ और स्कोप में बताया गया है।

2. क्लाइंट तैयार करें

किसी लाइब्रेरी की ज़रूरत नहीं है: API साधारण HTTPS और JSON है। इस गाइड के उदाहरण हर भाषा में एक छोटा हेल्पर फ़ंक्शन इस्तेमाल करते हैं। अपनी भाषा वाला हेल्पर कॉपी करें; आगे की गाइड भी यही हेल्पर इस्तेमाल करती हैं। आधिकारिक क्लाइंट लाइब्रेरी SDK सेक्शन में दी गई हैं।

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. कुंजी जाँचें

GET /v1/me कॉल करने वाले का विवरण देता है: संगठन, कुंजी, उसका रोल और स्कोप, और उस पर लागू रेट लिमिट। यह किसी भी मान्य कुंजी के साथ काम करता है, इसलिए हर इंटीग्रेशन की पहली रिक्वेस्ट के लिए यही सबसे अच्छा है।

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

कोड auth.not_authenticated के साथ 401 का मतलब है कि कुंजी भेजी नहीं गई, रद्द कर दी गई है या उसमें टाइपिंग की ग़लती है; api_keys.expired का मतलब है कि उसकी मियाद ख़त्म हो गई है।

4. कलेक्शन ढूँढें

कार्ड कलेक्शन में रहते हैं। GET /v1/collections वे कलेक्शन दिखाता है, जो आपकी कुंजी को दिखते हैं:

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

जिस कलेक्शन के साथ आप काम करना चाहते हैं, उसका id और name नोट कर लें। नीचे के उदाहरण कलेक्शन 3 इस्तेमाल करते हैं, जिसका नाम support है।

5. दस्तावेज़ जोड़ें

PUT /v1/cards-by-external-id/{external_id} आपकी अपनी ID के साथ कार्ड बनाता है, या अगर कार्ड पहले से मौजूद है, तो उसे बदल देता है। रिक्वेस्ट को दो बार चलाना सुरक्षित है: दूसरी बार कंटेंट नहीं बदला होता, और जवाब skipped होता है, कारण unchanged के साथ। external_id के रूप में अपने सिस्टम में रिकॉर्ड की ID इस्तेमाल करें।

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

रिक्वेस्ट तब लौटती है, जब कार्ड खोज में मिलने के लिए तैयार हो जाता है: नए कार्ड के लिए "status": "ready" के साथ 201, बदले गए कार्ड के लिए 200। HTML और सादा टेक्स्ट भी इसी तरह काम करते हैं, "content_type": "html" या "text" के साथ। फ़ाइलें (PDF, Word, Excel और दूसरी) इसी एंडपॉइंट से multipart/form-data के रूप में जाती हैं; फ़ाइलें, फ़ोल्डर, मेटाडेटा और कई दस्तावेज़ों का इम्पोर्ट दस्तावेज़ों का इम्पोर्ट में बताया गया है।

POST /v1/search कार्ड के वे अंश ढूँढता है, जो क्वेरी से मेल खाते हैं, सबसे अच्छे मिलान से शुरू करके:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection में कलेक्शन का नाम दिया जाता है। इसके बिना खोज default नाम वाले कलेक्शन में होती है।

7. सवाल पूछें

POST /v1/ask सामान्य भाषा में पूछे गए सवाल का जवाब देता है और जवाब के स्रोत लौटाता है। असिस्टेंट ज़रूरी जानकारी ढूँढता है और सिर्फ़ उन कार्ड से जवाब देता है, जिन्हें पढ़ने की अनुमति कुंजी के पास है।

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

जब कुछ भी प्रासंगिक नहीं मिलता, तब भी रिस्पॉन्स 200 होता है, "empty": "no_hits" और answer में छोटी-सी व्याख्या के साथ। ऐसे में यूज़र को क्या दिखाना है, यह आपका कोड तय करता है।

आगे क्या करें