POST/v1/cards/bulk

कार्ड पर बल्क कार्रवाई चलाएँ

bulk_cards

चुने गए कार्ड पर बल्क कार्रवाई चलाता है। अनुमतियाँ हर कार्ड के लिए जाँची जाती हैं: कलेक्शन में रोल और डेटा प्रोफ़ाइल (मिटाने वाली कार्रवाइयों के लिए दस्तावेज़ के हर हिस्से तक ऐक्सेस चाहिए)। जिन कार्ड पर आप कार्रवाई नहीं कर सकते, वे कारण के साथ छोड़ दिए जाते हैं। हर बदलाव कार्ड के ऑडिट लॉग में दर्ज होता है, और साथ में नतीजे के साथ एक cards.bulk रिकॉर्ड।

फ़ोल्डर की कार्रवाइयाँ:
- params.folder_id (ज़रूरी) के साथ folder_move कार्ड को फ़ोल्डर में रखता है और, अगर params.from_folder_id दिया गया है, तो उसे उस फ़ोल्डर से हटाता है (खुले फ़ोल्डर से बाहर ले जाना)।
- params.folder_id के साथ folder_remove कार्ड को फ़ोल्डर से हटाता है; कार्ड कलेक्शन में रहता है।

फ़ोल्डर हर रिक्वेस्ट में एक बार जाँचे जाते हैं: न मिलने वाला या न दिखने वाला फ़ोल्डर 404 folders.not_found लौटाता है, फ़ोल्डर पर COLLECTION_EDIT_CARDS अनुमति न हो तो 403 authz.forbidden, और folder_id न हो या from_folder_id दूसरे कलेक्शन का हो तो 400 cards.bulk_invalid। हर कार्ड के लिए: CARD_EDIT के बिना कार्ड no_write के रूप में छोड़ा जाता है; फ़ोल्डर से अलग कलेक्शन का कार्ड collection_mismatch के रूप में छोड़ा जाता है; जो कार्ड पहले से अपनी जगह पर है, वह unchanged के रूप में बताया जाता है।

ऑथेंटिकेशन

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

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

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

ऑब्जेक्ट: BulkRequest

idsarray of stringज़रूरी
items ≥ 1, items ≤ 500
actionBulkActionज़रूरी
paramsobject

रिस्पॉन्स

200सफल रिस्पॉन्स

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

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

ऑब्जेक्ट: BulkResult

countsobjectज़रूरी
फ़ील्ड
- doneintegerज़रूरी
- reasonsobjectज़रूरी
  फ़ील्ड
  - admin_onlynumber
  - collection_mismatchinteger
  - connectornumber
  - failedinteger
  - needs_usernumber
  - no_verifynumber
  - no_writenumber
  - not_foundnumber
  - partial_accessnumber
  - processinginteger
  - same_collectionnumber
  - sensitive_lowernumber
  - target_needs_reindexnumber
  - unchangedinteger
- skippedintegerज़रूरी
donearray of stringज़रूरी
fileAttachment
jobsarray of integer
skippedarray of BulkSkippedज़रूरी

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

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 सेकंड में होता है: उतना इंतज़ार करें और रीट्राई करें।

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

curl -X POST 'https://api.sursa.com/v1/cards/bulk' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ids":["string"],"action":"verify"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

आज़माएँ

API कुंजी

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

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

Idempotency-Key header

X-View-As header

Idempotency-Key

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

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