डेवलपर API

अवलोकन

डेवलपर API एक REST API है जो /api/v1के अंतर्गत है। सभी अनुरोध और प्रतिक्रियाएं JSON हैं। पूरा, इंटरैक्टिव कॉन्ट्रैक्ट यहां है API संदर्भ; यह पेज आपको आपकी पहली सफल कॉल तक पहुंचाता है।

प्रमाणीकरण

एक वर्कस्पेस API कुंजी के साथ प्रमाणित करें जो Bearer टोकन के रूप में भेजी जाती है। एक उत्पन्न करें Studio → डेवलपर API में (सशुल्क प्लान)। सीक्रेट केवल एक बार दिखाया जाता है। इसे कहीं सुरक्षित रखें; यदि आप इसे खो देते हैं, तो कुंजी रद्द करें और एक नई बनाएं।

Authorization: Bearer $POLLSLIVE_KEY

कुंजियां अपने वर्कस्पेस के भीतर एडमिन अधिकार के साथ कार्य करती हैं। कभी भी क्लाइंट-साइड कोड में कुंजी उजागर न करें। API को अपने सर्वर से कॉल करें।

You can also authenticate using an OAuth 2.0 Client Credentials access token for machine-to-machine integrations.

क्विकस्टार्ट

एक पोल बनाएं, इसे प्रकाशित करें, फिर परिणाम पढ़ें:

curl -X POST https://pollslive.com/api/v1/polls \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lunch vote",
    "content": {
      "questions": [{
        "id": "q1", "kind": "multiple_choice", "text": "Where to?",
        "type": "single",
        "options": [
          { "id": "a", "label": "Tacos" },
          { "id": "b", "label": "Sushi" }
        ]
      }]
    }
  }'

curl -X PATCH https://pollslive.com/api/v1/polls/POLL_ID \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "publish": true }'

curl https://pollslive.com/api/v1/polls/POLL_ID/results \
  -H "Authorization: Bearer $POLLSLIVE_KEY"

प्रश्न प्रकार

एक पोल टाइप की गई स्लाइड्स का एक डेक है। प्रत्येक स्लाइड पर kind सेट करें। इनमें से हर प्रकार API के माध्यम से बनाया जा सकता है:

• multiple_choice: type (single/multiple), options[]। एसिंक्रोनस रूप से वोट करने योग्य।
• quiz: options[], correctOptionIds[], timeLimitSec, points, speedBonus।
• quiz_typed: acceptedAnswers[], timeLimitSec, points, speedBonus (केवल लाइव सत्रों में; 1-10 स्वीकृत उत्तर, हर एक 60 अक्षर तक, बड़े-छोटे अक्षर और अतिरिक्त खाली जगह अनदेखी करके मिलाए जाते हैं; खिलाड़ी 40 अक्षर तक टाइप करते हैं)।
• quiz_order: items[], timeLimitSec, points, speedBonus (केवल लाइव सत्रों में; id और label वाली 3-6 चीज़ें, सही क्रम में सहेजी गई; खिलाड़ी उन्हें मिली-जुली देखते हैं और अंक केवल ठीक उसी क्रम पर मिलते हैं)।
• scale: min, max, minLabel, maxLabel, statements[]।
• ranking: options[] (उत्तरदाता उन्हें क्रमबद्ध करते हैं)।
• open_ended: maxLength, render (list/cloud)।
• qa: moderated, allowUpvotes।
• estimation: cards[], deckPreset (Planning Poker; केवल लाइव सत्रों में, जब तक आप प्रकट न करें तब तक वोट छिपे रहते हैं)।
• brainstorm: maxLength, moderated, groups[], votesPerPerson (केवल लाइव सत्रों में; दर्शक उन समूहों पर वोट देते हैं जो आप विचारों से बनाते हैं)।
• content - केवल प्रदर्शन।

{
  "questions": [
    {
      "id": "s1", "kind": "scale", "text": "How likely are you to recommend us?",
      "min": 0, "max": 10, "minLabel": "Not likely", "maxLabel": "Very likely"
    },
    {
      "id": "q2", "kind": "quiz", "text": "Capital of France?",
      "options": [{ "id": "a", "label": "Paris" }, { "id": "b", "label": "Rome" }],
      "correctOptionIds": ["a"], "timeLimitSec": 20, "points": 100, "speedBonus": true
    },
    {
      "id": "q3", "kind": "ranking", "text": "Rank these features by importance",
      "options": [
        { "id": "r1", "label": "Speed" },
        { "id": "r2", "label": "Reliability" },
        { "id": "r3", "label": "Price" }
      ]
    },
    {
      "id": "q4", "kind": "open_ended", "text": "Any other feedback?",
      "maxLength": 300, "render": "list"
    },
    {
      "id": "q5", "kind": "qa", "text": "Questions for the presenter",
      "moderated": true, "allowUpvotes": true
    }
  ]
}

छवियां, वीडियो और लिंक

कोई भी स्लाइड और कोई भी विकल्प mediaले जा सकता है। एक URL अपलोड करें या पास करें POST /media और लौटाए गए ऑब्जेक्ट को एम्बेड करें। छवियां डाउनलोड की जाती हैं, WebP में फिर से एन्कोड की जाती हैं और फिर से होस्ट की जाती हैं (छोटे पेलोड)। YouTube वीडियो और वेब लिंक अपनी URL रखते हैं और क्लाइंट-साइड रेंडर होते हैं, इसलिए आप वीडियो होस्ट करने के लिए कभी भुगतान नहीं करते। आप media: { type, url } को स्लाइड/विकल्प पर इनलाइन भी पास कर सकते हैं और सहेजते समय API इसे हल कर देता है।

# 1) Ingest an image (returns { data: { type, url, storedUrl, width, height } })
curl -X POST https://pollslive.com/api/v1/media \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/cat.jpg" }'

# 2) Embed the storedUrl on a slide option
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://pollslive.com/media/abc.webp" } }

# Or pass the original URL inline - the API resolves it on save:
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://example.com/cat.jpg" } }

# YouTube on a question slide
{ "id": "q1", "kind": "content", "text": "Watch this first",
  "media": { "type": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ" } }

प्रतिक्रियाएं और परिणाम

multiple_choice स्लाइड्स वोट लेती हैं POST /polls/{id}/votesके माध्यम से। हर दूसरा प्रकार एसिंक्रोनस प्रतिक्रियाएं लेता है POST /polls/{id}/responses के माध्यम से: स्लाइड से मेल खाने वाला फ़ील्ड भेजें (scaleValue, rankingOrder, text, या optionIds)। प्रति-स्लाइड एग्रीगेट पढ़ें GET /polls/{id}/resultsसे।

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "s1", "scaleValue": 9 }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voterId": "user-123",
    "slideId": "q3",
    "rankingOrder": ["r2", "r1", "r3"]
  }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "q4", "text": "Great product!" }'

लाइव सत्र और सत्र नियंत्रण

लाइव सत्र आपको दर्शकों के सामने रियल टाइम में पोल चलाने देता है। API के ज़रिए एक सत्र बनाएँ, अपने दर्शकों के साथ PIN या QR कोड शेयर करें, फिर control एंडपॉइंट से गति और परिणामों की दृश्यता नियंत्रित करें।

curl -X POST https://pollslive.com/api/v1/sessions \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pollId": "POLL_ID" }'
# Response includes: id, pin, status, currentSlideIndex, hostToken (once)

curl -X POST https://pollslive.com/api/v1/sessions/SESSION_ID/control \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "next" }'

सभी सत्र नियंत्रण कार्रवाइयाँ

Bearer के साथ /api/v1/sessions/{id}/control पर इनमें से किसी एक action स्ट्रिंग के साथ POST करें.

{ "action": "goto", "slideIndex": 2 }

परिणाम एक्सपोर्ट करना

समेकित पोल परिणाम UTF-8 RFC-4180 CSV फ़ाइल के रूप में, या ?format=pdf के साथ PDF रिपोर्ट के रूप में डाउनलोड करें। प्रत्येक पंक्ति में स्लाइड संख्या, प्रश्न पाठ, प्रकार, उत्तर लेबल और गणना या मान होता है। Excel, Google Sheets और किसी भी CSV टूल के साथ संगत। केवल सशुल्क प्लान पर।

curl https://pollslive.com/api/v1/polls/POLL_ID/export \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  --output results.csv

# CSV structure:
# Slide, Question, Type, Answer / Label, Count / Value
# 1, "Where to?", multiple_choice, Tacos, 12
# 1, "Where to?", multiple_choice, Sushi, 8
# 2, "Rate your experience", scale, Average, 8.50
# 2, "Rate your experience", scale, Rating 10, 5

एंडपॉइंट

• पोल: GET/POST /polls, GET/PATCH/DELETE /polls/{id}
• परिणाम: GET /polls/{id}/results, GET/POST /polls/{id}/responses
• वोट: GET/POST /polls/{id}/votes
• मीडिया: POST /media
• सेशन: POST /sessions, GET /sessions/{id}, POST /sessions/{id}/control
• Export: GET /polls/{id}/export

अनुरोध/प्रतिक्रिया प्रारूप देखें और लाइव कॉल आज़माएं API संदर्भमें।

त्रुटियां और रेट लिमिट

त्रुटियां एक स्थिर लिफ़ाफ़े का उपयोग करती हैं:

{ "error": { "code": "not_found", "message": "Poll not found." } }

सामान्य कोड: 401 अमान्य/अनुपस्थित कुंजी, 402 प्लान अपग्रेड आवश्यक, 404 नहीं मिला, 409 विरोध (जैसे पहले ही वोट किया, पोल बंद), 422 सत्यापन विफल, 429 रेट लिमिट।,

रेट लिमिट

API सभी एंडपॉइंट के लिए प्रति कुंजी प्रति मिनट 120 अनुरोधों की अनुमति देता है। मीडिया इनजेस्शन (POST /media) की सीमा अलग से 30 अनुरोध प्रति मिनट है। सीमा पार होने पर HTTP 429 लौटाया जाता है। रुकें और फिर से कोशिश करें।

OAuth2 (Pro और उससे ऊपर)

कोई भी सशुल्क कार्यस्थान (Pro और उससे ऊपर) स्थिर कुंजियों के बजाय OAuth2 client-credentials का उपयोग कर सकता है। क्लाइंट Studio में बनाएँ; पूरा तरीका OAuth गाइड में बताया गया है।

डेवलपर API के बदलाव

डेवलपर API के बदलाव, सबसे नए पहले। प्रोडक्ट के बदलाव चेंजलॉग में हैं।

API वर्ज़निंग नीति

REST API का वर्ज़न URL स्तर पर है (/api/v1/)। संगतता तोड़ने वाले बदलाव केवल नए वर्ज़न उपसर्ग के साथ और कम से कम 90 दिनों के समानांतर संचालन की सूचना के साथ आते हैं। जोड़ने वाले बदलाव (नए फ़ील्ड, नए एंडपॉइंट, नए webhook इवेंट) कुछ नहीं तोड़ते और कभी भी जारी हो सकते हैं।