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

# Utiliser l'API GraphQL

> Trouvez les opérations, comprenez les types d'arguments et les enums, créez des publications et téléversez des médias via l'API GraphQL d'Ayrshare.

<h2 id="finding-an-operation">
  Trouver une opération
</h2>

Le schéma fait foi pour le sous-ensemble GraphQL pris en charge : racines des opérations, noms, arguments, types d'entrée et valeurs d'enum. Les descriptions fournissent des conseils d'utilisation, et le [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) expose les deux. Pour les fonctionnalités disponibles uniquement en REST, utilisez la [référence de l'API REST](/docs/apis/overview).

Les noms d'opérations suivent les points de terminaison REST qu'ils atteignent, en camelCase. `GET /history` correspond à `postHistory`, `GET /analytics/social` à `socialAnalytics`, `POST /post` à `createPost`.

<h2 id="queries-read-mutations-write">
  Les queries lisent, les mutations écrivent
</h2>

Les queries sont des lectures et des validations qui ne modifient rien de notre côté. Les mutations publient ou modifient un état, lancent un traitement ou envoient un e-mail. Ni le verbe HTTP REST ni le coût d'un appel ne déterminent la racine :

<ul class="custom-bullets">
  <li><code>validatePost</code> vérifie une publication sans la publier.</li>
  <li><code>validateMedia</code> vérifie qu'une URL de média est accessible.</li>
  <li><code>generatePost</code> est une query car rien ne change de notre côté. Elle compte tout de même comme un appel API et renvoie un texte différent à chaque fois ; assurez-vous donc qu'un cache client ou un refetch automatique ne la répète pas à votre insu.</li>
  <li><code>mediaUploadUrl</code> est une mutation car elle crée une URL de téléversement pour votre compte.</li>
  <li><code>linkAnalytics</code> est une mutation car elle peut demander un rapport envoyé par e-mail.</li>
  <li><code>userBatch</code> est une mutation car elle lance une tâche d'export.</li>
</ul>

Utilisez l'Explorer ou le schéma pour confirmer la racine de chaque opération prise en charge.

<h2 id="creating-a-post">
  Créer une publication
</h2>

`createPost` prend un seul argument `input`, de sorte que la publication entière est un seul objet :

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

L'entrée reproduit le [point de terminaison REST de publication](/docs/apis/post/post) documenté, y compris les objets d'options par réseau et les formes REST qui acceptent plusieurs structures 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 }
  }
}
```

Une publication peut réussir sur un réseau et échouer sur un autre. Il ne s'agit pas d'un échec de la requête : consultez [Erreurs](/docs/apis/graphql/errors#partial-success-on-multi-network-posts).

<h2 id="argument-types">
  Types d'arguments
</h2>

La plupart des arguments sont des chaînes, des nombres et des booléens ordinaires. Trois cas méritent d'être connus.

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

De nombreux arguments de type chaîne dont l'ensemble de valeurs prises en charge est fermé sont des enums GraphQL, écrits **sans guillemets et en majuscules** :

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

Et non `"instagram"`. Le serveur associe chaque enum accepté à la valeur exacte attendue par le contrôleur REST sous-jacent, souvent (mais pas toujours) une chaîne en minuscules. Un enum invalide est rejeté lors de la validation GraphQL avant l'exécution de l'opération ; une faute de frappe ne vous coûte donc rien.

Certains arguments partagent un nom entre plusieurs opérations mais acceptent des valeurs différentes, car les points de terminaison diffèrent réellement. `reviews(platform:)` n'accepte que `GMB` et `FACEBOOK`, car ce sont les seuls réseaux proposant des avis. L'autocomplétion de votre client affichera l'ensemble correct pour chaque opération.

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

Quelques arguments sont typés `JSON` plutôt qu'avec un type spécifique. C'est le cas lorsqu'une valeur peut légitimement avoir plusieurs structures et qu'aucun type GraphQL unique ne pourrait la décrire fidèlement :

<ul class="custom-bullets">
  <li><code>explainError(code:)</code> accepte <code>215</code> ou <code>"215"</code>, car les clients conservent les codes d'erreur sous les deux formes.</li>
  <li><code>createPost(input:)</code> utilise JSON pour des champs tels que <code>post</code> et <code>mediaUrls</code>, qui peuvent être des valeurs partagées ou des objets par plateforme.</li>
  <li><code>createAutomation(triggers:, actions:)</code> prennent des tableaux dont les champs dépendent du <code>type</code> de chaque entrée.</li>
  <li><code>boostFacebookPost(interests:)</code> accepte les identifiants de centres d'intérêt Meta sous forme de chaînes ou de nombres.</li>
</ul>

Transmettez la même valeur que celle que vous enverriez dans le corps REST correspondant. Un argument `JSON` n'est pas une échappatoire : le resolver le valide avant l'envoi, de sorte qu'une valeur invalide renvoie une erreur de validation et ne consomme aucun appel API.

<h3 id="optional-arguments-and-nulls">
  Arguments facultatifs et valeurs null
</h3>

Pour les arguments facultatifs et les champs facultatifs des objets d'entrée, un `null` explicite est traité comme une omission. Les éléments null au sein des listes sont conservés lorsque le type de liste les autorise.

<h2 id="reading-responses">
  Lire les réponses
</h2>

La plupart des opérations renvoient un scalaire `JSON` contenant l'enveloppe de réponse REST complète ; sélectionnez donc le champ racine sans sous-champs. `createPost` renvoie actuellement un `PostResult` typé ; sélectionnez donc ses champs :

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

Les types de réponse typés tels que `PostResult` incluent également `raw: JSON!`, qui contient la réponse REST complète et non modifiée :

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

`raw` est permanent et existe pour qu'un nouveau champ apparaissant dans la réponse REST ne soit jamais inaccessible depuis GraphQL pendant que nous rattrapons son typage. Si vous avez besoin de quelque chose que les champs typés n'exposent pas, demandez `raw`.

<h2 id="uploading-media">
  Téléverser des médias
</h2>

**Les octets des médias ne peuvent pas transiter par une requête GraphQL.** Une requête GraphQL est un document JSON unique soumis à une limite de 64 Ko ; il n'existe donc aucun champ acceptant un fichier, et encoder une image en base64 dans la query dépasserait cette limite pour tout ce qui est plus grand qu'une miniature.

La méthode prise en charge évite entièrement le problème, et elle est de toute façon plus rapide qu'un téléversement via une API, car vos octets vont directement vers le stockage :

1. Demandez une URL de téléversement :

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

2. Lisez `data.mediaUploadUrl.uploadUrl`, `accessUrl` et `contentType` dans le JSON renvoyé.

3. Envoyez votre fichier via `PUT` **directement vers `uploadUrl`**, et non vers l'API Ayrshare, en définissant l'en-tête `Content-Type` de la requête sur le `contentType` renvoyé.

4. Une fois le téléversement réussi, transmettez `accessUrl` dans `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 }
     }
   }
   ```

Traitez `uploadUrl` comme un identifiant d'écriture à courte durée de vie et ne le journalisez ni ne l'exposez. `accessUrl` est l'URL du média utilisée lors de la création de la publication.

Vous pouvez aussi continuer à utiliser les [points de terminaison REST de téléversement](/docs/apis/media/upload-media) et référencer les URL obtenues depuis GraphQL. Les deux interfaces partagent la même médiathèque.

<h2 id="read-next">
  À lire ensuite
</h2>

<ul class="custom-bullets">
  <li>[Erreurs](/docs/apis/graphql/errors) : codes de statut HTTP, structure des erreurs et succès partiel.</li>
  <li>[Limites et facturation](/docs/apis/graphql/limits) : plafonds de taille des requêtes et mode de décompte des requêtes.</li>
</ul>