SosoAPI प्रकाशन API: प्रमाणीकरण, अनुरोध और परिणाम

1. अपने सर्वर से प्रमाणित करें

SosoAPI App → Settings → Agents & API Access में API key बनाएँ। सर्वर एनवायरनमेंट में SOSOAPI_API_KEY के रूप में रखें। अनुरोध Authorization: Bearer <your-key> और Content-Type: application/json इस्तेमाल करते हैं। वेबसाइट, मोबाइल ऐप बंडल, URL या सार्वजनिक रिपॉज़िटरी में key कभी एम्बेड न करें।

नीचे के सभी एंडपॉइंट JSON बॉडी के साथ POST इस्तेमाल करते हैं। keys और प्रत्यायोजित एजेंट अधिकार अपनी क्षमताओं, अनुमत Workspaces और मालिक की वर्तमान सदस्यता से सीमित हैं। पढ़ने के लिए agent:operate व कम से कम viewer एक्सेस; प्रकाशन बदलाव के लिए agent:publish व कम से कम editor एक्सेस चाहिए। प्राधिकरण मालिक के अधिकार बढ़ा नहीं सकता।

ऐप का वर्तमान वर्कस्पेस और जुड़े खाते इस्तेमाल करें, या इस्तेमाल के लिए अधिकृत IDs खोजने को /identity-api/workspace/list और /identity-api/user/social-accounts/list कॉल करें। ग्राहक के वर्कस्पेस या खाते की ID का अनुमान न लगाएँ।

// Node.js 20+; run only on your server.
const apiKey = process.env.SOSOAPI_API_KEY;
if (!apiKey) throw new Error("Set SOSOAPI_API_KEY on your server");
const apiBase = "https://gqeshlawtcexsapabaui.supabase.co/functions/v1";

async function sosoPost(path, body) {
  const response = await fetch(apiBase + path, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) {
    const requestId = result.request_id ?? response.headers.get("x-request-id");
    // Handler errors use code/message; schema-validation 400s instead use
    // success:false and error:{name:"ZodError",message:...}.
    // Preserve status, available code and requestId in server diagnostics.
    // Never log the key or an Authorization header.
    throw new Error("SosoAPI " + response.status + " (" +
      (requestId ?? "no request id") + ")");
  }
  return result;
}

2. प्रकाशन एंडपॉइंट का नक्शा

ये पाथ सर्वर हेल्पर के API base के सापेक्ष हैं। वर्तमान संस्करण, उपलब्ध कार्रवाइयाँ और प्रकाशन परिणाम के लिए Scheduled Post विवरण पढ़ें।

3. दायरा बनाए रखते हुए सूची देखें और पेज बदलें

limit का डिफ़ॉल्ट 50 है और स्वीकार्य सीमा 1–200 है। वैकल्पिक status का मान scheduled, publishing, published, failed, expired, needs_reschedule, cancelled या deleted में से एक है। scheduled_from और scheduled_to दोनों ऑफ़सेट सहित ISO-8601 समय के रूप में साथ देने होंगे; समाप्ति शुरुआत के बाद होनी चाहिए।

next_cursor या तो null है या scheduled_at और id वाला ऑब्जेक्ट। पूरा ऑब्जेक्ट cursor के रूप में उसी Workspace और फ़िल्टर के साथ वापस भेजें। यह एंडपॉइंट page, offset, platform या social_account_id फ़िल्टर नहीं लेता।

await sosoPost("/studio-api/scheduled-posts/list", {
  "workspace_id": "<workspace-uuid>",
  "limit": 50
});

const first = await sosoPost("/studio-api/scheduled-posts/list", {
  workspace_id: "<workspace-uuid>", limit: 50
});
if (first.next_cursor) {
  const next = await sosoPost("/studio-api/scheduled-posts/list", {
    workspace_id: "<workspace-uuid>", limit: 50, cursor: first.next_cursor
  });
  // Consume next.posts; continue only while next_cursor is not null.
}

4. समीक्षा की गई एक पोस्ट सत्यापित करें और बनाएँ

हर प्लेसहोल्डर को अपने अधिकृत दायरे के मानों और भविष्य के समय से बदलें। चलाने पर यह उदाहरण वास्तविक Threads टेक्स्ट पोस्ट निर्धारित करता है। create कॉल से पहले व्यक्ति से खाते, कंटेंट और समय की पुष्टि लें।

provider_payload.platform और उसी प्लेटफ़ॉर्म के publish_options सेट करें। सर्वर चुने खाते से उनका मेल जाँचता है। पोस्ट का स्रोत दर्ज करने के लिए project_id दे सकते हैं; प्रोजेक्ट प्रकाशन एक्सेस या निर्धारण का नियंत्रण नहीं देता।

await sosoPost("/studio-api/scheduled-posts/eligibility", {
  "workspace_id": "<workspace-uuid>",
  "include_quota": true,
  "targets": [
    {
      "social_account_id": "<threads-account-uuid>",
      "media": [],
      "provider_payload": {
        "platform": "threads",
        "publish_options": {
          "post_type": "TEXT"
        }
      },
      "draft": {
        "caption": "A reviewed update from our team.",
        "hashtags": [],
        "scheduled_at": "<future-ISO-8601-instant-with-offset>",
        "display_timezone": "Asia/Hong_Kong"
      }
    }
  ]
});

await sosoPost("/studio-api/scheduled-posts/create", {
  "workspace_id": "<workspace-uuid>",
  "social_account_id": "<threads-account-uuid>",
  "caption": "A reviewed update from our team.",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<future-ISO-8601-instant-with-offset>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<stable-key-for-this-one-intent>"
});

5. परिणाम पढ़ें और सुरक्षित रूप से रद्द करें

Create, { post, deduped } लौटाता है। List, { posts, next_cursor, returned_count } लौटाता है। Get, { post, delivery, actions, attempts, outcomes } लौटाता है। post में id, status, version, destination, schedule और उपलब्ध प्रोवाइडर पहचान/परमालिंक हैं; delivery और actions वर्तमान प्रगति व अनुमत अगले कदम समझाते हैं।

status scheduled या publishing वाली पोस्ट अभी लंबित है। status published वाला अंतिम प्रकाशन परिणाम पुष्टि करता है और उपलब्ध प्रोवाइडर प्रमाण देता है; परमालिंक न हो सकता है। क्लाइंट डिस्कनेक्ट या रिस्पॉन्स देर से आए, तो परिणाम बताने से पहले मौजूदा पोस्ट पढ़ें।

रद्द करने से पहले पोस्ट विवरण पढ़ें और वर्तमान संख्यात्मक version दें। प्रोवाइडर का निर्धारण SosoAPI द्वारा रद्द होते समय परिणाम cancellation_pending हो सकता है। निर्धारण रद्द करने से पहले से प्रकाशित पोस्ट नहीं मिटती।

await sosoPost("/studio-api/scheduled-posts/get", {
  "id": "<scheduled-post-uuid>"
});

const detail = await sosoPost("/studio-api/scheduled-posts/get", {
  id: "<scheduled-post-uuid>"
});
// Run only after the person confirms cancelling this unpublished post.
await sosoPost("/studio-api/scheduled-posts/cancel", {
  id: detail.post.id, expected_version: detail.post.version
});

6. इडेम्पोटेंसी, टकराव और अनिश्चित राइट

वही create अनुरोध दोहराते समय समान idempotency_key इस्तेमाल करें। मेल खाने वाला पुनः अनुरोध deduped=true के साथ मौजूदा पोस्ट लौटाता है। वही key रखकर कंटेंट बदलने पर टकराव होता है। इससे SosoAPI में डुप्लिकेट निर्माण रुकता है; प्रोवाइडर द्वारा ठीक एक बार डिलीवरी की गारंटी नहीं मिलती।

अपडेट और कार्रवाइयों में नवीनतम विवरण रिस्पॉन्स का expected_version दें। टकराव हो, तो पोस्ट फिर पढ़ें और नए संस्करण के अनुसार बदलाव जाँचें। रिस्पॉन्स खोने पर मौजूदा स्थिति जाँचें, नई key से दूसरी पोस्ट न बनाएँ।

डुप्लिकेट-कंटेंट नियंत्रण समान सामान्यीकृत सार्वजनिक कंटेंट, खाते और नज़दीकी प्रकाशन समय वाले अलग अनुरोध को अस्वीकार कर सकता है। पढ़ने के लिए अधिकृत होने पर मौजूदा पोस्ट का संदर्भ देखें और अनुरोध बदलने से पहले यूज़र से पूछें। बल्क अनुरोध हर गंतव्य का परिणाम लौटाते हैं; कुछ सफल और कुछ विफल हो सकते हैं।

7. त्रुटियाँ, दर सीमाएँ और इंटीग्रेशन सीमाएँ

हैंडलर त्रुटियों के एन्वलप में error, message, वैकल्पिक code, retryable, request_id, वैकल्पिक details और retry_after_seconds होते हैं। स्कीमा वैलिडेशन के 400 रिस्पॉन्स की संरचना अलग है: { success: false, error: { name: "ZodError", message: "…" } }। वैलिडेशन संदेश में फ़िलहाल फ़ील्ड की सीरियलाइज़ की गई समस्याएँ और उनके पाथ होते हैं; हैंडलर एन्वलप के फ़ील्ड मौजूद होने का अनुमान न लगाएँ।

विफलता जाँचते समय HTTP स्टेटस, त्रुटि कोड और result.request_id ?? response.headers.get("x-request-id") की correlation ID रखें। वैलिडेशन फ़ील्ड पाथ से अनुरोध ठीक करें। प्रमाणीकरण या अनुमति त्रुटि में फिर प्रयास से पहले क्रेडेंशियल या प्राधिकरण ठीक करें।

studio-api की वर्तमान सीमा हर मानव यूज़र के लिए प्रति मिनट 240 अनुरोध और उसी यूज़र के अलग मशीन-क्रेडेंशियल बकेट में 480 प्रति मिनट है। ये अनुरोध सीमा हैं, प्रकाशन थ्रूपुट या प्लान कोटा नहीं। दूसरे एंडपॉइंट और सोशल प्रोवाइडर की अलग सीमाएँ हैं। 429 या पुनः प्रयास योग्य 503 पर लाइव Retry-After हेडर मानें; लगातार लूप न चलाएँ।

यूज़र पोस्ट देख रहा हो, तो सीमित अंतरालों पर स्थिति पढ़ें या ऐप का लाइव स्थिति दृश्य इस्तेमाल करें। यह API आउटबाउंड webhooks, सब्सक्राइबर SLA, सभी प्लेटफ़ॉर्म पर समान फ़ीचर या निश्चित प्रकाशन समय का वादा नहीं करता।

• प्लेटफ़ॉर्म क्षमता तालिका
• अपना AI एजेंट सेट अप करें