POST/v1/drafts

ड्राफ़्ट बनाएँ

create_draft

नए कार्ड का ड्राफ़्ट (collection, COLLECTION_CREATE_CARDS चाहिए) या मौजूदा कार्ड के एडिट का ड्राफ़्ट (card_id, CARD_EDIT चाहिए; शीर्षक, टैग और टेक्स्ट न दिए जाएँ, तो नवीनतम वर्शन से लिए जाते हैं) बनाता है। लेखक पहला सह-लेखक होता है। एक यूज़र का एक कार्ड पर एक सक्रिय ड्राफ़्ट हो सकता है: दोहराई गई रिक्वेस्ट details में draft_id के साथ 409 drafts.exists लौटाती है (PATCH से उसी ड्राफ़्ट में जारी रखें)। scheduled_publish_at प्रकाशन का समय तय करता है। API कुंजी ड्राफ़्ट के लेखक का नाम author_id में देती है (1.62.0 से)।

ऑथेंटिकेशन

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

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

application/json

ऑब्जेक्ट: DraftCreate

card_idstring | null
collectionstring | null
नए कार्ड के लिए कलेक्शन का नाम (card_id के बिना ज़रूरी)।
titlestring | null
length ≤ 200
body_markdownstring | null
length ≤ 500000
tagsarray of string | null
items ≤ 30
revision_notestring | null
length ≤ 1000
verify_on_publishboolean
डिफ़ॉल्ट: false
notify_followersboolean
डिफ़ॉल्ट: false
scheduled_publish_atstring (date-time) | null
author_idinteger
API कुंजी से कॉल होने पर ड्राफ़्ट का लेखक (1.62.0 से): कुंजी के संगठन का सक्रिय यूज़र; यह यूज़र created_by और पहला सह-लेखक बनता है। कुंजी के लिए ज़रूरी (नहीं तो 422 validation.failed); दूसरे संगठन का यूज़र या निष्क्रिय यूज़र 404 users.not_found लौटाता है। कलेक्शन और कार्ड पर अनुमतियाँ कुंजी के लिए जाँची जाती हैं, लेखक के लिए नहीं। सेशन में लेखक साइन-इन किया हुआ यूज़र होता है: अलग author_id देने पर 422 validation.failed लौटता है।
≥ 1

रिस्पॉन्स

201बनाया गया

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

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

ऑब्जेक्ट: Draft

idintegerज़रूरी
org_idintegerज़रूरी
card_idstring | nullज़रूरी
वह कार्ड, जिसे ड्राफ़्ट एडिट करता है; null: नए कार्ड का ड्राफ़्ट।
collection_idintegerज़रूरी
collectionstringज़रूरी
titlestringज़रूरी
body_markdownstringज़रूरी
tagsarray of stringज़रूरी
base_versioninteger | null
कार्ड का वह वर्शन, जिससे ड्राफ़्ट शुरू हुआ।
scheduled_publish_atstring (date-time) | null
workflow_stateDraftWorkflowStateज़रूरी
revision_notestring | null
verify_on_publishbooleanज़रूरी
notify_followersbooleanज़रूरी
created_byintegerज़रूरी
updated_byinteger | null
created_atstring (date-time)ज़रूरी
updated_atstring (date-time)ज़रूरी
publish_requested_byinteger | null
publish_requested_atstring (date-time) | null
approved_byinteger | null
approved_atstring (date-time) | null
collaboratorsarray of DraftCollaboratorज़रूरी
conflictstring | null
card_published: ड्राफ़्ट शुरू होने के बाद कार्ड प्रकाशित हुआ या बदला गया; card_deleted: कार्ड हटा दिया गया; सूची बढ़ सकती है।

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

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

curl -X POST 'https://api.sursa.com/v1/drafts' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"collection":"support","title":"Refund policy","body_markdown":"# Refund policy\n\nRefunds are processed within 14 days.","author_id":1}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

आज़माएँ

API कुंजी

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

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

Idempotency-Key header

Idempotency-Key

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

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