दस्तावेज़ों का इम्पोर्ट

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

आपको cards:write स्कोप वाली API कुंजी चाहिए और ऐसा रोल, जो लक्ष्य कलेक्शन में लिख सकता हो (editor या admin)। उदाहरण क्विकस्टार्ट का हेल्पर इस्तेमाल करते हैं।

सही एंडपॉइंट चुनें

जो कुछ भी आप एक से ज़्यादा बार इम्पोर्ट करते हैं, उसके लिए external_id इस्तेमाल करें। इससे हर इम्पोर्ट दोहराया जा सकता है: फिर से चलाने पर वह कॉपी जोड़ने के बजाय अपने बनाए कार्ड अपडेट करता है।

अपनी ID से कार्ड बनाएँ या बदलें

PUT /v1/cards-by-external-id/{external_id} आपके सिस्टम में रिकॉर्ड की ID लेता है। अगर किसी कार्ड का यह external_id नहीं है, तो वह नया कार्ड बनाता है (201)। अगर किसी कार्ड का है, तो वह कार्ड का कंटेंट और विवरण बदल देता है (200)।

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/kb-article-1042 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "folder_id": "0f8e2d7c-4b6a-4e1f-9c3d-2a5b8e7f1c40",
    "title": "Returning a damaged item",
    "content_type": "html",
    "body": "<h2>Damaged items</h2><p>Send a photo within 7 days and we ship a replacement.</p>",
    "tags": ["returns", "shipping"],
    "metadata": {"source": "helpdesk", "article_id": "1042"}
  }'

दोहराने पर क्या होता है:

• कंटेंट नहीं बदला: कोई नया वर्शन नहीं बनता। रिस्पॉन्स "status": "skipped" और "reason": "unchanged" के साथ 200 होता है। रिक्वेस्ट दोहराना हमेशा सुरक्षित है, Idempotency-Key के बिना भी।
• कंटेंट बदला: कार्ड का नया वर्शन बनता है और वह दोबारा इंडेक्स होता है। उसका शीर्षक, टैग, ज़िम्मेदार व्यक्ति, कैटेगरी और metadata आपके भेजे मान ले लेते हैं; metadata पूरा का पूरा बदल दिया जाता है।
• कलेक्शन और फ़ोल्डर सिर्फ़ कार्ड बनते समय लागू होते हैं। बाद में कार्ड को दूसरी जगह ले जाने के लिए उसे PATCH /v1/cards/{card_id} से बदलें।

नया वर्शन कार्ड का सत्यापन हटा देता है, जैसे कंटेंट का कोई भी बदलाव हटाता है: वेरिफ़ायर उसे फिर से सत्यापित करता है।

टेक्स्ट फ़ॉर्मेट

कार्ड का इंतज़ार करें, या नहीं

डिफ़ॉल्ट रूप से रिक्वेस्ट तब लौटती है, जब कार्ड खोज में मिलने के लिए तैयार हो जाता है, "status": "ready" और card में कार्ड के साथ। इसमें छोटे टेक्स्ट के लिए सेकंड के एक हिस्से से लेकर लंबी फ़ाइल के लिए एक मिनट या उससे ज़्यादा समय लगता है।

बड़े इम्पोर्ट के लिए "async": true भेजें। रिस्पॉन्स तुरंत "status": "queued" और job में इंडेक्सिंग जॉब (उसके job_id के साथ) लेकर आता है। जॉब को GET /v1/jobs/{job_id} से जाँचें, या सभी जॉब GET /v1/jobs/stream में देखें। जॉब status done, error या canceled के साथ ख़त्म होता है।

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

फ़ाइल अपलोड करें

फ़ाइलें multipart/form-data रिक्वेस्ट में, file फ़ील्ड में जाती हैं। Sursa PDF, Word, Excel, PowerPoint, OpenDocument स्प्रेडशीट, CSV, Markdown, HTML, AsciiDoc, ई-मेल (.eml), सादा टेक्स्ट और आम इमेज फ़ॉर्मेट पढ़ता है। वह जाँचता है कि फ़ाइल का नाम, बताया गया टाइप और कंटेंट आपस में मेल खाते हैं, और मेल न खाने पर 415 के साथ अस्वीकार करता है।

अपनी ID से फ़ाइल वाला कार्ड बनाने या बदलने के लिए फ़ाइल उसी PUT /v1/cards-by-external-id/{external_id} पर भेजें:

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/handbook-2026 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -F "file=@employee-handbook.pdf" \
  -F "collection_id=3" \
  -F "tags=hr,policies" \
  -F 'metadata={"owner_team":"people"}'

फ़ॉर्म में tags कॉमा से अलग की गई स्ट्रिंग है और metadata स्ट्रिंग के रूप में लिखा JSON ऑब्जेक्ट है। title के बिना नए कार्ड को शीर्षक के रूप में फ़ाइल का नाम मिलता है।

अपनी ID के बिना कोई फ़ाइल एक बार जोड़ने के लिए उसी फ़ॉर्म और Idempotency-Key के साथ POST /v1/cards इस्तेमाल करें। ऐसी फ़ाइल अपलोड करने पर, जो कलेक्शन में पहले से है, "duplicate": true और मौजूदा card_id के साथ "status": "skipped" लौटता है, जब तक आप external_id नहीं भेजते।

एक फ़ाइल का आकार इंस्टॉलेशन से सीमित होता है (डिफ़ॉल्ट रूप से 200 MB)। बड़ी फ़ाइलों के लिए, या अस्थिर नेटवर्क के लिए, पहले फ़ाइल को हिस्सों में अपलोड करें।

कार्ड का कंटेंट बदलें

जब आपके पास कार्ड की Sursa ID पहले से हो, तो PUT /v1/cards/{card_id}/content उसका टेक्स्ट या फ़ाइल बदल देता है और बाक़ी सब वैसा ही रखता है: ज़िम्मेदार व्यक्ति, टैग, वेरिफ़ायर, सत्यापन का अंतराल और हाथ से सेट की गई कैटेगरी।

curl -X PUT https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60/content \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "markdown", "body": "# Refund policy\n\nRefunds are processed within 10 days."}'

• वही कंटेंट फिर से भेजने पर "reason": "unchanged" के साथ "status": "skipped" लौटता है।
• जो कार्ड अभी इंडेक्स हो रहा है, वह कोड cards.indexing_in_progress के साथ 409 लौटाता है। कुछ सेकंड में रीट्राई करें।
• जो कार्ड किसी स्रोत से आता है, जैसे कनेक्टर या कस्टम स्रोत, वह सिर्फ़ अपने स्रोत में बदला जाता है: cards.managed_by_source।
• कुंजी को पूरा कार्ड देखने की अनुमति होनी चाहिए; आंशिक रूप से दिखने वाला कार्ड cards.content_whole_access लौटाता है।

कई दस्तावेज़ इम्पोर्ट करें

आपके रिकॉर्ड पर PUT /v1/cards-by-external-id/… वाला लूप सबसे सरल बल्क इम्पोर्ट है, और इसे किसी भी पल रोककर फिर से चलाना सुरक्षित है। इसे तेज़ और रेट लिमिट के अनुकूल बनाने के लिए:

1. "async": true भेजें, ताकि हर रिक्वेस्ट कार्ड के कतार में लगते ही लौट आए।
2. कुछ रिक्वेस्ट समानांतर चलाएँ (4 से 8), और जब RateLimit हेडर दिखाए कि कुछ ही रिक्वेस्ट बाक़ी हैं, तो रफ़्तार धीमी करें। देखें रेट लिमिट और कोटा।
3. 429 पर Retry-After तक इंतज़ार करें; नेटवर्क एरर या 5xx पर वही रिक्वेस्ट रीट्राई करें। दोहराना नुक़सान नहीं करता।
4. एरर पर ख़त्म होने वाले हर रिकॉर्ड का external_id नोट करें, और आख़िर में उन्हें रीट्राई करें।

import { api } from "./sursa.mjs";

async function importAll(records, concurrency = 6) {
  const failed = [];
  const queue = [...records];
  async function worker() {
    for (let record = queue.shift(); record; record = queue.shift()) {
      try {
        await api("PUT", `/v1/cards-by-external-id/${encodeURIComponent(record.id)}`, {
          collection_id: 3,
          title: record.title,
          content_type: "html",
          body: record.html,
          metadata: { source: "helpdesk" },
          async: true,
        });
      } catch (error) {
        failed.push({ id: record.id, error: String(error) });
      }
    }
  }
  await Promise.all(Array.from({ length: concurrency }, worker));
  return failed;
}

फ़ाइलों के ZIP आर्काइव के लिए POST /v1/cards/archive एक रिक्वेस्ट में अंदर की हर सपोर्टेड फ़ाइल को कार्ड बना देता है। यह तुरंत योजना (कौन-सी फ़ाइलें कार्ड बनेंगी और कौन-सी छोड़ी जाएँगी, और क्यों) और एक जॉब के साथ जवाब देता है; GET /v1/archives/{job_id} नतीजा बताता है।

इम्पोर्ट किए गए कार्ड ढूँढें और हटाएँ

• अपनी ID से कार्ड GET /v1/cards-by-external-id/{external_id} से पढ़ें।
• एक इम्पोर्ट के कार्ड मेटाडेटा फ़िल्टर से देखें: GET /v1/cards?metadata[source]=helpdesk। देखें मेटाडेटा।
• कार्ड DELETE /v1/cards/{card_id} से हटाएँ।

आम एरर