PATCH/v1/collections/{name}

कलेक्शन बदलें

update_collection

ऑथेंटिकेशन

Authorization हेडर में API कुंजी भेजें: Authorization: Bearer <कुंजी>।

पाथ पैरामीटर

namestringज़रूरी
कलेक्शन का नाम, या id:<number> रूप में उसका id (id:3)। सिर्फ़ अंकों वाला सेगमेंट नाम माना जाता है।

हेडर पैरामीटर

Idempotency-Keystring
लिखने वाली रिक्वेस्ट के सुरक्षित रीट्राई के लिए कुंजी: 1 से 255 प्रिंट होने वाले ASCII कैरेक्टर; हर लॉजिकल ऑपरेशन के लिए एक UUID v4 की सलाह दी जाती है। उसी कुंजी के साथ 24 घंटे के अंदर रीट्राई ऑपरेशन को दोबारा नहीं चलाता: वह सेव किया गया रिस्पॉन्स (स्टेटस, हेडर और बॉडी) Idempotency-Replayed: true हेडर के साथ लौटाता है। वही कुंजी, पर अलग मेथड, पाथ, Content-Type या बॉडी हो, तो 409 api.idempotency_mismatch लौटता है; जब तक पहली रिक्वेस्ट चल रही है, तब तक 409 api.idempotency_in_progress और Retry-After: 1। 5xx या 429 रिस्पॉन्स के बाद कुंजी छोड़ दी जाती है, और रीट्राई ऑपरेशन को फिर से चलाता है। कुंजी संगठन और कॉल करने वाले (API कुंजी, यूज़र या कस्टम स्रोत की कुंजी) के दायरे में होती है।
length ≥ 1, length ≤ 255
X-View-Asstring
सिर्फ़ admin रोल वाली API कुंजियों के लिए। रिक्वेस्ट को डेटा प्रोफ़ाइल <profile>[:viewer|verifier|editor] की ओर से चलाता है, जैसे employee:viewer। इंस्टॉलेशन कुंजी इस हेडर का इस्तेमाल नहीं कर सकती (403)।

कुकी पैरामीटर

kb_view_asstring
सेशन के लिए “View as” मोड की कुकी। POST /auth/view-as इसे सेट करता है और DELETE /auth/view-as हटाता है।

रिक्वेस्ट बॉडी

application/json

ऑब्जेक्ट: CollectionUpdate

titlestring | null
descriptionstring | null
aclobject | null
sensitiveboolean | null
default_owner_idinteger | null
default_verify_intervalinteger | null
≥ 1, ≤ 3650
default_categorystring | null
upgrade_indexboolean
कलेक्शन के खोज इंडेक्स को इंस्टॉलेशन के मौजूदा वर्शन पर अपग्रेड करें (सिर्फ़ एडमिन)। कलेक्शन दोबारा इंडेक्स होता है, और रिस्पॉन्स दोबारा इंडेक्सिंग के प्लान के साथ कलेक्शन है (IndexUpgradeResult)। अगर कलेक्शन पहले से अप-टू-डेट है, तो कुछ नहीं बदलता।
publishing_enabledboolean | null
कलेक्शन में ड्राफ़्ट के प्रकाशन की मंज़ूरी। अनुमति की वही जाँच (COLLECTION_MANAGE_SETTINGS) और वही सेटिंग इस्तेमाल होती है, जो PUT /v1/collections/{name}/publishing में है।
metadataMetadataPatch

रिस्पॉन्स

200कलेक्शन। जब बदलाव कलेक्शन का इंडेक्स अपग्रेड करता है, तो रिस्पॉन्स में दोबारा इंडेक्सिंग का प्लान (`IndexUpgradeResult`) भी होता है।

रिस्पॉन्स हेडर

RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।
Idempotency-Replayed
true का मतलब है कि रिस्पॉन्स इस Idempotency-Key के लिए सेव किए गए रिस्पॉन्स से दोहराया गया: ऑपरेशन दोबारा नहीं चला।

application/json

इनमें से एक

400रिक्वेस्ट अमान्य है: पैरामीटर का मान या ऑब्जेक्ट की स्थिति यह कार्रवाई करने नहीं देती (`detail` एक संदेश है)।

रिस्पॉन्स हेडर

RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

401कोई क्रेडेंशियल नहीं भेजा गया (न सेशन कुकी, न API कुंजी), या कुंजी नहीं मिली।

रिस्पॉन्स हेडर

RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

403कार्रवाई की अनुमति नहीं है: रोल काफ़ी नहीं है, कलेक्शन या कार्ड तक ऐक्सेस नहीं है, रिक्वेस्ट “View as” मोड में चल रही है, या संगठन निलंबित है या हटा दिया गया है (`detail` एक ऑब्जेक्ट है, जिसमें `code: org_suspended | org_deleted` है)।

रिस्पॉन्स हेडर

RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

404ऑब्जेक्ट मौजूद नहीं है या आपके लिए उपलब्ध नहीं है। API यह पुष्टि नहीं करता कि प्रतिबंधित ऑब्जेक्ट मौजूद है।

रिस्पॉन्स हेडर

RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

409ऑब्जेक्ट की स्थिति यह कार्रवाई करने नहीं देती, जैसे डुप्लिकेट, चल रही इंडेक्सिंग या पहले से प्रोसेस हो चुका जॉब।

रिस्पॉन्स हेडर

RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

422वैलिडेशन एरर: बॉडी या पैरामीटर स्कीमा से मेल नहीं खाते (`detail` वैलिडेशन एरर की सूची है), या पैरामीटर का मान सीमा से बाहर है (`detail` एक संदेश है)।

रिस्पॉन्स हेडर

RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

429बहुत ज़्यादा रिक्वेस्ट (`api.rate_limited`), संगठन का मिनट, दिन या महीने का कोटा ख़त्म हो गया है (`api.quota_exceeded`; `error.details` में `quota`, `limit` और `reset_at` होते हैं), संगठन की सीमा पूरी हो गई है, या जवाब देने वाली सर्विस व्यस्त है (`answers.engine_busy`)। `Retry-After` हेडर में दिए गए समय तक इंतज़ार करें।

रिस्पॉन्स हेडर

Retry-After
रिक्वेस्ट का रीट्राई करने से पहले कितने सेकंड इंतज़ार करना है।
RateLimit-Policy
लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।
RateLimit
RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।
X-RateLimit-Limit
RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।
X-RateLimit-Remaining
सबसे सख़्त सीमा में बची रिक्वेस्ट।
X-RateLimit-Reset
सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

एरर कोड

हर रिक्वेस्ट के सामान्य कोड के अलावा वे कोड, जो यह एंडपॉइंट एरर होने पर error.code में लौटा सकता है।

सुरक्षित रीट्राई

हर POST और PATCH के साथ Idempotency-Key हेडर भेजें (उदाहरण के लिए, UUID)। 24 घंटे के अंदर उसी कुंजी के साथ रीट्राई करने पर रिक्वेस्ट दोबारा नहीं चलती, बल्कि सेव किया गया रिस्पॉन्स लौटता है।

रेट लिमिट

रिस्पॉन्स में RateLimit और RateLimit-Policy हेडर होते हैं, और पहले वाले X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset भी। 429 रिस्पॉन्स में Retry-After सेकंड में होता है: उतना इंतज़ार करें और रीट्राई करें।

← collections · API रेफ़रेंस

curl -X PATCH 'https://api.sursa.com/v1/collections/support' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","description":"Customer support articles","acl":{}}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

आज़माएँ

API कुंजी

कुंजी सिर्फ़ इस टैब की मेमोरी में रहती है और सिर्फ़ https://api.sursa.com को भेजी जाती है।

रिक्वेस्ट आपके संगठन के असली डेटा पर काम करती हैं।

Idempotency-Key header

X-View-As header

name path *

Idempotency-Key

यह फ़ील्ड ख़ाली हो, तो हर रिक्वेस्ट के लिए नई कुंजी बनाई जाती है।

रिक्वेस्ट बॉडी (JSON)