मेटाडेटा

metadata किसी ऑब्जेक्ट पर आपके अपने कुंजी-मान जोड़ों का सेट है: आपके CRM में रिकॉर्ड की ID, वह टीम जो उसकी ज़िम्मेदार है, सिंक का वह रन जिसने उसे लिखा। Sursa इसे सेव करता है, ऑब्जेक्ट के साथ और इवेंट में लौटाता है, और आपको इससे कार्ड, कलेक्शन और फ़ोल्डर की सूचियाँ फ़िल्टर करने देता है। वह इसका कोई मतलब नहीं निकालता।

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "metadata": {"crm_id": "A-1042", "team": "support"}
}

metadata वाले ऑब्जेक्ट: कार्ड, कलेक्शन और फ़ोल्डर। कस्टम स्रोत के दस्तावेज़ में भी metadata होता है; वह दस्तावेज़ के कार्ड का metadata बन जाता है।

सीमाएँ

किसी सीमा को तोड़ने वाली रिक्वेस्ट कोड api.metadata_invalid के साथ 400 लौटाती है। error.details.key उस कुंजी का नाम बताता है, और error.details.reason बताता है कि क्या ग़लत है: too_many_keys, key_invalid, value_too_long, too_large या value_invalid (मान स्ट्रिंग नहीं है)।

मान स्ट्रिंग होते हैं। संख्याएँ और तारीख़ें भी स्ट्रिंग के रूप में सेव करें, उदाहरण के लिए "2026-10-24"।

मेटाडेटा सेट करें

जब आप कोई ऑब्जेक्ट बनाते या बदलते हैं (POST, PUT), तो metadata पूरा का पूरा सेट होता है:

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 '{
    "title": "Refund policy",
    "body": "Refunds are processed within 14 days.",
    "metadata": {"crm_id": "A-1042", "team": "support"}
  }'

multipart/form-data रिक्वेस्ट में, जैसे फ़ाइल अपलोड में, metadata को फ़ॉर्म फ़ील्ड के रूप में भेजें, जिसका मान JSON ऑब्जेक्ट हो: metadata={"crm_id":"A-1042"}।

मेटाडेटा अपडेट करें

PATCH आपकी भेजी कुंजियों को मौजूदा कुंजियों के साथ मिला देता है। "" या null मान वाली कुंजी हटा दी जाती है; जो कुंजियाँ आप नहीं भेजते, वे जैसी हैं वैसी रहती हैं:

curl -X PATCH https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "billing", "legacy_flag": null}}'

{"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "metadata": {"crm_id": "A-1042", "team": "billing"}}

"metadata": {} कुछ नहीं बदलता। सभी जोड़े हटाने के लिए हर कुंजी को null के साथ भेजें।

मेटाडेटा से फ़िल्टर करें

ये सूचियाँ metadata[<key>]=<value> स्वीकार करती हैं:

• कार्ड: GET /v1/cards और GET /v1/cards/count;
• कलेक्शन: GET /v1/collections;
• फ़ोल्डर: GET /v1/folders और GET /v1/collections/{name}/folders।

यह मान से हूबहू मेल खाता है। आप 3 शर्तों तक जोड़ सकते हैं, और ऑब्जेक्ट को उन सभी से मेल खाना चाहिए:

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "metadata[team]=support" \
  --data-urlencode "metadata[crm_id]=A-1042"

फ़िल्टर के साथ फ़ोल्डर ट्री सपाट सूची के रूप में आता है: हर कलेक्शन के folders में मेल खाने वाले फ़ोल्डर ख़ाली children के साथ होते हैं, और parent_id बताता है कि हर फ़ोल्डर कहाँ है। तब GET /v1/folders उन कलेक्शन को छोड़ देता है, जिनमें मेल खाने वाले फ़ोल्डर नहीं हैं। 3 से ज़्यादा शर्तें या अमान्य कुंजी कोड api.metadata_invalid के साथ 400 लौटाती हैं।

मेटाडेटा क्या नहीं है

• यह कंटेंट नहीं है। खोज और असिस्टेंट के जवाब इसका इस्तेमाल नहीं करते। लोगों को जो मिलना चाहिए, उसे कार्ड के टेक्स्ट, उसके शीर्षक या उसके टैग में रखें।
• यह निजी नहीं है। जो भी ऑब्जेक्ट देख सकता है, वह उसका मेटाडेटा भी देख सकता है। इसमें कभी सीक्रेट, टोकन या ऐसा निजी डेटा न रखें, जो ऑब्जेक्ट के पाठकों को नहीं दिखना चाहिए।
• यह external_id की जगह नहीं ले सकता। अपने रिकॉर्ड की ID से कार्ड ढूँढने के लिए कार्ड को external_id दें; वह यूनिक होता है, जबकि मेटाडेटा के मान नहीं।