> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL API का उपयोग करना

> Ayrshare GraphQL API के माध्यम से ऑपरेशन्स ढूँढें, argument types और enums को समझें, पोस्ट बनाएँ, और मीडिया अपलोड करें।

<h2 id="finding-an-operation">
  ऑपरेशन ढूँढना
</h2>

समर्थित GraphQL उपसमूह के लिए schema ही आधिकारिक स्रोत है: operation roots, नाम, arguments, input types, और enum values। विवरण उपयोग संबंधी मार्गदर्शन देते हैं, और [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) दोनों को दिखाता है। केवल REST वाली क्षमताओं के लिए [REST API reference](/docs/apis/overview) का उपयोग करें।

ऑपरेशन नाम उन REST endpoints के अनुसार होते हैं जिन तक वे पहुँचते हैं, camelCase में। `GET /history` `postHistory` है, `GET /analytics/social` `socialAnalytics` है, `POST /post` `createPost` है।

<h2 id="queries-read-mutations-write">
  Queries पढ़ती हैं, mutations लिखते हैं
</h2>

Queries पढ़ने और validation के लिए होती हैं जो हमारी ओर कुछ नहीं बदलतीं। Mutations प्रकाशित करते हैं या state बदलते हैं, कोई कार्य शुरू करते हैं, या email भेजते हैं। Root का निर्धारण न तो REST HTTP verb से होता है और न ही किसी call की लागत से:

<ul class="custom-bullets">
  <li><code>validatePost</code> किसी पोस्ट को प्रकाशित किए बिना जाँचता है।</li>
  <li><code>validateMedia</code> जाँचता है कि कोई media URL पहुँच योग्य है।</li>
  <li><code>generatePost</code> एक query है क्योंकि हमारी ओर कुछ नहीं बदलता। फिर भी यह एक API call के रूप में गिना जाता है और हर बार अलग टेक्स्ट लौटाता है, इसलिए सुनिश्चित करें कि कोई client cache या automatic refetch आपकी जानकारी के बिना इसे दोहराए नहीं।</li>
  <li><code>mediaUploadUrl</code> एक mutation है क्योंकि यह आपके खाते के लिए एक upload URL बनाता है।</li>
  <li><code>linkAnalytics</code> एक mutation है क्योंकि यह email द्वारा भेजी जाने वाली रिपोर्ट का अनुरोध कर सकता है।</li>
  <li><code>userBatch</code> एक mutation है क्योंकि यह एक export job शुरू करता है।</li>
</ul>

प्रत्येक समर्थित ऑपरेशन का root पुष्टि करने के लिए Explorer या schema का उपयोग करें।

<h2 id="creating-a-post">
  पोस्ट बनाना
</h2>

`createPost` एक ही `input` argument लेता है, इसलिए पूरी पोस्ट एक object होती है:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}
```

Input प्रलेखित [REST post endpoint](/docs/apis/post/post) को प्रतिबिंबित करता है, जिसमें प्रति-नेटवर्क option objects और वे REST रूप शामिल हैं जो एक से अधिक JSON आकार स्वीकार करते हैं:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}
```

कोई पोस्ट एक नेटवर्क पर सफल और दूसरे पर विफल हो सकती है। यह request की विफलता नहीं है — [त्रुटियाँ](/docs/apis/graphql/errors#partial-success-on-multi-network-posts) देखें।

<h2 id="argument-types">
  Argument types
</h2>

अधिकांश arguments सामान्य strings, numbers और booleans होते हैं। तीन मामले जानने योग्य हैं।

<h3 id="enums">
  Enums
</h3>

सीमित समर्थित सेट वाले कई string arguments GraphQL enums होते हैं, जिन्हें **बिना quotes के और upper case में** लिखा जाता है:

```graphql theme={"system"}
{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }
```

`"instagram"` नहीं। Server प्रत्येक स्वीकृत enum को अंतर्निहित REST controller द्वारा अपेक्षित सटीक मान में मैप करता है — अक्सर, लेकिन हमेशा नहीं, एक lowercase string। अमान्य enum को ऑपरेशन चलने से पहले GraphQL validation के दौरान ही अस्वीकार कर दिया जाता है, इसलिए किसी typo की आपको कोई कीमत नहीं चुकानी पड़ती।

कुछ arguments का नाम विभिन्न ऑपरेशन्स में एक जैसा होता है लेकिन वे अलग-अलग मान स्वीकार करते हैं, क्योंकि endpoints वास्तव में भिन्न हैं। `reviews(platform:)` केवल `GMB` और `FACEBOOK` स्वीकार करता है, क्योंकि केवल इन्हीं नेटवर्क्स पर reviews होते हैं। आपके client का autocomplete प्रत्येक ऑपरेशन के लिए सही सेट दिखाएगा।

<h3 id="the-json-scalar">
  JSON scalar
</h3>

कुछ arguments किसी विशिष्ट type के बजाय `JSON` के रूप में typed होते हैं। ऐसा वहाँ होता है जहाँ किसी मान के वास्तव में एक से अधिक आकार हो सकते हैं और कोई एक GraphQL type उसका सही-सही वर्णन नहीं कर सकता:

<ul class="custom-bullets">
  <li><code>explainError(code:)</code> <code>215</code> या <code>"215"</code> स्वीकार करता है, क्योंकि ग्राहक error codes को दोनों रूपों में रखते हैं।</li>
  <li><code>createPost(input:)</code> <code>post</code> और <code>mediaUrls</code> जैसे फ़ील्ड्स के लिए JSON का उपयोग करता है, जो साझा मान या प्रति-प्लेटफ़ॉर्म objects हो सकते हैं।</li>
  <li><code>createAutomation(triggers:, actions:)</code> ऐसे arrays लेते हैं जिनके फ़ील्ड्स प्रत्येक entry के <code>type</code> पर निर्भर करते हैं।</li>
  <li><code>boostFacebookPost(interests:)</code> Meta interest ids को strings या numbers के रूप में स्वीकार करता है।</li>
</ul>

वही मान पास करें जो आप संबंधित REST body में भेजते। `JSON` argument कोई खामी नहीं है: resolver dispatch से पहले इसे validate करता है, इसलिए अमान्य मान validation error लौटाता है और कोई API call खर्च नहीं करता।

<h3 id="optional-arguments-and-nulls">
  वैकल्पिक arguments और nulls
</h3>

वैकल्पिक arguments और input objects के अंदर के वैकल्पिक फ़ील्ड्स के लिए, स्पष्ट `null` को छोड़ दिए जाने के समान माना जाता है। Lists के अंदर के null सदस्य तब सुरक्षित रखे जाते हैं जब list type उनकी अनुमति देता है।

<h2 id="reading-responses">
  Responses पढ़ना
</h2>

अधिकांश ऑपरेशन्स एक `JSON` scalar लौटाते हैं जिसमें पूरा REST response envelope होता है, इसलिए root फ़ील्ड को बिना subfields के चुनें। `createPost` वर्तमान में एक typed `PostResult` लौटाता है, इसलिए उसके फ़ील्ड्स चुनें:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}
```

`PostResult` जैसे typed response types में `raw: JSON!` भी शामिल होता है, जिसमें पूरा, अपरिवर्तित REST response होता है:

```graphql theme={"system"}
mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}
```

`raw` स्थायी है और इसलिए मौजूद है ताकि REST response में दिखने वाला कोई नया फ़ील्ड GraphQL से कभी अप्राप्य न रहे, जब तक हम उसकी typing पूरी करते हैं। यदि आपको कुछ ऐसा चाहिए जो typed फ़ील्ड्स उपलब्ध नहीं कराते, तो `raw` माँगें।

<h2 id="uploading-media">
  मीडिया अपलोड करना
</h2>

**मीडिया bytes GraphQL request के माध्यम से नहीं भेजे जा सकते।** GraphQL request 64 KB सीमा के भीतर एक ही JSON document होती है, इसलिए कोई ऐसा फ़ील्ड नहीं है जो फ़ाइल स्वीकार करे, और query के अंदर किसी image को base64 के रूप में encode करना thumbnail से बड़ी किसी भी चीज़ के लिए उस सीमा को पार कर जाएगा।

समर्थित तरीका इस समस्या से पूरी तरह बचता है, और किसी भी स्थिति में API के माध्यम से अपलोड करने से तेज़ है, क्योंकि आपके bytes सीधे storage में जाते हैं:

1. एक upload URL माँगें:

   ```graphql theme={"system"}
   mutation { mediaUploadUrl(contentType: "image/jpeg") }
   ```

2. लौटाए गए JSON से `data.mediaUploadUrl.uploadUrl`, `accessUrl`, और `contentType` पढ़ें।

3. अपनी फ़ाइल को Ayrshare API पर नहीं, बल्कि **सीधे `uploadUrl` पर** `PUT` करें, और request के `Content-Type` header को लौटाए गए `contentType` पर सेट करें।

4. अपलोड सफल होने के बाद, `accessUrl` को `createPost.input.mediaUrls` में पास करें:

   ```graphql theme={"system"}
   mutation {
     createPost(input: {
       post: "With a photo"
       platforms: [INSTAGRAM]
       mediaUrls: ["https://the-returned-access-url"]
       idempotencyKey: "instagram-photo-001"
     }) {
       status
       postIds { platform postUrl }
     }
   }
   ```

`uploadUrl` को एक अल्पकालिक write credential मानें और इसे log या उजागर न करें। `accessUrl` वह media URL है जिसका उपयोग पोस्ट बनाते समय किया जाता है।

आप [REST upload endpoints](/docs/apis/media/upload-media) का उपयोग जारी रख सकते हैं और परिणामी URLs को GraphQL से संदर्भित कर सकते हैं। दोनों इंटरफ़ेस एक ही media library साझा करते हैं।

<h2 id="read-next">
  आगे पढ़ें
</h2>

<ul class="custom-bullets">
  <li>[त्रुटियाँ](/docs/apis/graphql/errors) — HTTP status codes, error आकार, और आंशिक सफलता।</li>
  <li>[सीमाएँ और Billing](/docs/apis/graphql/limits) — query आकार की सीमाएँ और requests की गिनती कैसे होती है।</li>
</ul>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.