> ## 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

> Знаходьте операції, розбирайтеся з типами аргументів і enum-ами, створюйте дописи та завантажуйте медіа через Ayrshare GraphQL API.

<h2 id="finding-an-operation">
  Пошук операції
</h2>

Схема є авторитетним джерелом для підтримуваної підмножини GraphQL: кореневих типів операцій, назв, аргументів, вхідних типів і значень enum. Описи містять поради щодо використання, а [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) показує і те, і інше. Для можливостей, доступних лише в REST, використовуйте [довідник REST API](/docs/apis/overview).

Назви операцій відповідають REST-ендпоінтам, до яких вони звертаються, у форматі camelCase. `GET /history` — це `postHistory`, `GET /analytics/social` — це `socialAnalytics`, `POST /post` — це `createPost`.

<h2 id="queries-read-mutations-write">
  Queries читають, mutations записують
</h2>

Queries — це читання та перевірки, які нічого не змінюють на нашому боці. Mutations публікують або змінюють стан, запускають роботу чи надсилають email. Кореневий тип не визначається ні HTTP-методом REST, ні вартістю виклику:

<ul class="custom-bullets">
  <li><code>validatePost</code> перевіряє допис, не публікуючи його.</li>
  <li><code>validateMedia</code> перевіряє, чи доступний URL медіа.</li>
  <li><code>generatePost</code> — це query, тому що на нашому боці нічого не змінюється. Проте він усе одно рахується як виклик API і щоразу повертає інший текст, тож переконайтеся, що клієнтський кеш або автоматичне повторне отримання даних не повторює його непомітно для вас.</li>
  <li><code>mediaUploadUrl</code> — це mutation, тому що він створює URL завантаження для вашого акаунта.</li>
  <li><code>linkAnalytics</code> — це mutation, тому що він може запитати звіт електронною поштою.</li>
  <li><code>userBatch</code> — це mutation, тому що він запускає завдання експорту.</li>
</ul>

Використовуйте Explorer або схему, щоб перевірити кореневий тип кожної підтримуваної операції.

<h2 id="creating-a-post">
  Створення допису
</h2>

`createPost` приймає єдиний аргумент `input`, тож увесь допис — це один об'єкт:

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

Вхідні дані повторюють задокументований [REST-ендпоінт post](/docs/apis/post/post), включно з об'єктами опцій для окремих соцмереж і 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 }
  }
}
```

Допис може бути успішно опублікований в одній соцмережі й завершитися помилкою в іншій. Це не є збоєм запиту — див. [Помилки](/docs/apis/graphql/errors#partial-success-on-multi-network-posts).

<h2 id="argument-types">
  Типи аргументів
</h2>

Більшість аргументів — звичайні рядки, числа та булеві значення. Варто знати про три випадки.

<h3 id="enums">
  Enum-и
</h3>

Багато рядкових аргументів із закритим набором підтримуваних значень є GraphQL enum-ами, які записуються **без лапок і великими літерами**:

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

А не `"instagram"`. Сервер зіставляє кожне прийняте значення enum із точним значенням, яке очікує базовий REST-контролер, — часто, але не завжди, це рядок у нижньому регістрі. Некоректне значення enum відхиляється під час валідації GraphQL ще до виконання операції, тож помилка в написанні вам нічого не коштує.

Деякі аргументи мають однакову назву в різних операціях, але приймають різні значення, бо ендпоінти справді відрізняються. `reviews(platform:)` приймає лише `GMB` і `FACEBOOK`, оскільки лише ці соцмережі мають відгуки. Автодоповнення вашого клієнта покаже правильний набір для кожної операції.

<h3 id="the-json-scalar">
  Скаляр JSON
</h3>

Кілька аргументів мають тип `JSON`, а не конкретний тип. Так буває, коли значення цілком законно може мати кілька структур і жоден окремий тип GraphQL не міг би чесно його описати:

<ul class="custom-bullets">
  <li><code>explainError(code:)</code> приймає <code>215</code> або <code>"215"</code>, тому що клієнти зберігають коди помилок в обох формах.</li>
  <li><code>createPost(input:)</code> використовує JSON для таких полів, як <code>post</code> і <code>mediaUrls</code>, які можуть бути спільними значеннями або об'єктами для окремих платформ.</li>
  <li><code>createAutomation(triggers:, actions:)</code> приймають масиви, поля яких залежать від <code>type</code> кожного елемента.</li>
  <li><code>boostFacebookPost(interests:)</code> приймає id інтересів Meta як рядки або числа.</li>
</ul>

Передавайте те саме значення, яке ви надіслали б у тілі відповідного REST-запиту. Аргумент `JSON` не є лазівкою: резолвер валідує його перед відправленням, тому некоректне значення повертає помилку валідації й не витрачає виклик API.

<h3 id="optional-arguments-and-nulls">
  Необов'язкові аргументи та null
</h3>

Для необов'язкових аргументів і необов'язкових полів усередині вхідних об'єктів явне `null` нормалізується до пропуску. Елементи `null` усередині списків зберігаються, якщо тип списку їх допускає.

<h2 id="reading-responses">
  Читання відповідей
</h2>

Більшість операцій повертають скаляр `JSON`, що містить повну REST-обгортку відповіді, тому вибирайте кореневе поле без підполів. `createPost` наразі повертає типізований `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`, також містять `raw: JSON!` з повною незміненою REST-відповіддю:

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

`raw` — постійне поле, і воно існує для того, щоб нове поле, яке з'являється в REST-відповіді, ніколи не було недоступним із GraphQL, поки ми додаємо для нього типізацію. Якщо вам потрібне щось, чого не надають типізовані поля, запитуйте `raw`.

<h2 id="uploading-media">
  Завантаження медіа
</h2>

**Байти медіа не можуть передаватися через GraphQL-запит.** GraphQL-запит — це єдиний JSON-документ з лімітом 64 KB, тому немає поля, яке приймало б файл, а кодування зображення в base64 усередині запиту перевищило б цей ліміт для всього, що більше за мініатюру.

Підтримуваний спосіб повністю уникає цієї проблеми і в будь-якому разі швидший, ніж завантаження через API, тому що ваші байти потрапляють безпосередньо в сховище:

1. Запитайте URL завантаження:

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

2. Прочитайте `data.mediaUploadUrl.uploadUrl`, `accessUrl` і `contentType` з поверненого JSON.

3. Надішліть файл через `PUT` **безпосередньо на `uploadUrl`**, а не до Ayrshare API, встановивши заголовок запиту `Content-Type` у повернене значення `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` як короткочасні облікові дані для запису і не записуйте його в логи та не розкривайте. `accessUrl` — це URL медіа, який використовується під час створення допису.

Ви також можете й надалі використовувати [REST-ендпоінти завантаження](/docs/apis/media/upload-media) і посилатися на отримані URL з GraphQL. Обидва інтерфейси використовують ту саму медіатеку.

<h2 id="read-next">
  Що читати далі
</h2>

<ul class="custom-bullets">
  <li>[Помилки](/docs/apis/graphql/errors) — коди HTTP-статусів, структура помилок і частковий успіх.</li>
  <li>[Ліміти та білінг](/docs/apis/graphql/limits) — обмеження розміру запитів і як рахуються запити.</li>
</ul>


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