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

# Die GraphQL-API verwenden

> Finden Sie Operationen, verstehen Sie Argumenttypen und Enums, erstellen Sie Beiträge und laden Sie Medien über die Ayrshare-GraphQL-API hoch.

<h2 id="finding-an-operation">
  Eine Operation finden
</h2>

Das Schema ist maßgeblich für die unterstützte GraphQL-Teilmenge: Operations-Roots, Namen, Argumente, Eingabetypen und Enum-Werte. Beschreibungen liefern Hinweise zur Verwendung, und der [GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) zeigt beides an. Für Funktionen, die nur über REST verfügbar sind, verwenden Sie die [REST-API-Referenz](/docs/apis/overview).

Operationsnamen orientieren sich an den REST-Endpunkten, die sie ansprechen, in camelCase. `GET /history` ist `postHistory`, `GET /analytics/social` ist `socialAnalytics`, `POST /post` ist `createPost`.

<h2 id="queries-read-mutations-write">
  Queries lesen, Mutations schreiben
</h2>

Queries sind Lese- und Validierungsvorgänge, die auf unserer Seite nichts ändern. Mutations veröffentlichen oder ändern einen Zustand, starten Vorgänge oder versenden E-Mails. Weder das REST-HTTP-Verb noch die Kosten eines Aufrufs bestimmen den Root:

<ul class="custom-bullets">
  <li><code>validatePost</code> prüft einen Beitrag, ohne ihn zu veröffentlichen.</li>
  <li><code>validateMedia</code> prüft, ob eine Medien-URL erreichbar ist.</li>
  <li><code>generatePost</code> ist eine Query, weil sich auf unserer Seite nichts ändert. Sie zählt dennoch als API-Aufruf und gibt jedes Mal einen anderen Text zurück. Stellen Sie daher sicher, dass ein Client-Cache oder ein automatisches erneutes Abrufen sie nicht unbemerkt wiederholt.</li>
  <li><code>mediaUploadUrl</code> ist eine Mutation, weil sie eine Upload-URL für Ihr Konto erstellt.</li>
  <li><code>linkAnalytics</code> ist eine Mutation, weil sie einen per E-Mail versendeten Bericht anfordern kann.</li>
  <li><code>userBatch</code> ist eine Mutation, weil sie einen Exportauftrag startet.</li>
</ul>

Verwenden Sie den Explorer oder das Schema, um den Root jeder unterstützten Operation zu bestätigen.

<h2 id="creating-a-post">
  Einen Beitrag erstellen
</h2>

`createPost` nimmt ein einziges `input`-Argument entgegen, sodass der gesamte Beitrag ein Objekt ist:

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

Die Eingabe spiegelt den dokumentierten [REST-Post-Endpunkt](/docs/apis/post/post) wider, einschließlich der netzwerkspezifischen Optionsobjekte und der REST-Formen, die mehr als eine JSON-Struktur akzeptieren:

```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 }
  }
}
```

Ein Beitrag kann in einem Netzwerk erfolgreich sein und in einem anderen fehlschlagen. Das ist kein Fehlschlag der Anfrage – siehe [Fehler](/docs/apis/graphql/errors#partial-success-on-multi-network-posts).

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

Die meisten Argumente sind gewöhnliche Strings, Zahlen und Booleans. Drei Fälle sollten Sie kennen.

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

Viele String-Argumente mit einer abgeschlossenen unterstützten Wertemenge sind GraphQL-Enums und werden **ohne Anführungszeichen und in Großbuchstaben** geschrieben:

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

Nicht `"instagram"`. Der Server ordnet jedes akzeptierte Enum genau dem Wert zu, den der zugrunde liegende REST-Controller erwartet – oft, aber nicht immer, ein String in Kleinbuchstaben. Ein ungültiges Enum wird bei der GraphQL-Validierung abgelehnt, bevor die Operation ausgeführt wird, sodass Sie ein Tippfehler nichts kostet.

Manche Argumente tragen in verschiedenen Operationen denselben Namen, akzeptieren aber unterschiedliche Werte, weil sich die Endpunkte tatsächlich unterscheiden. `reviews(platform:)` akzeptiert nur `GMB` und `FACEBOOK`, da dies die einzigen Netzwerke mit Bewertungen sind. Die Autovervollständigung Ihres Clients zeigt für jede Operation die richtige Wertemenge an.

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

Einige Argumente sind als `JSON` statt als bestimmter Typ typisiert. Das ist dort der Fall, wo ein Wert berechtigterweise mehr als eine Struktur hat und kein einzelner GraphQL-Typ ihn zutreffend beschreiben könnte:

<ul class="custom-bullets">
  <li><code>explainError(code:)</code> akzeptiert <code>215</code> oder <code>"215"</code>, weil Kunden Fehlercodes in beiden Formen vorliegen haben.</li>
  <li><code>createPost(input:)</code> verwendet JSON für Felder wie <code>post</code> und <code>mediaUrls</code>, die gemeinsame Werte oder plattformspezifische Objekte sein können.</li>
  <li><code>createAutomation(triggers:, actions:)</code> nehmen Arrays entgegen, deren Felder vom <code>type</code> des jeweiligen Eintrags abhängen.</li>
  <li><code>boostFacebookPost(interests:)</code> akzeptiert Meta-Interessen-IDs als Strings oder Zahlen.</li>
</ul>

Übergeben Sie denselben Wert, den Sie im entsprechenden REST-Body senden würden. Ein `JSON`-Argument ist kein Schlupfloch: Der Resolver validiert es vor der Weiterleitung, sodass ein ungültiger Wert einen Validierungsfehler zurückgibt und keinen API-Aufruf verbraucht.

<h3 id="optional-arguments-and-nulls">
  Optionale Argumente und Nullwerte
</h3>

Bei optionalen Argumenten und optionalen Feldern innerhalb von Eingabeobjekten wird ein explizites `null` so behandelt, als wäre der Wert weggelassen worden. Null-Elemente innerhalb von Listen bleiben erhalten, wenn der Listentyp sie zulässt.

<h2 id="reading-responses">
  Antworten lesen
</h2>

Die meisten Operationen geben einen `JSON`-Skalar zurück, der den vollständigen REST-Antwort-Envelope enthält. Wählen Sie daher das Root-Feld ohne Unterfelder aus. `createPost` gibt derzeit ein typisiertes `PostResult` zurück, wählen Sie also dessen Felder aus:

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

Typisierte Antworttypen wie `PostResult` enthalten außerdem `raw: JSON!` mit der vollständigen, unveränderten REST-Antwort:

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

`raw` ist dauerhaft vorhanden und sorgt dafür, dass ein neues Feld in der REST-Antwort über GraphQL niemals unerreichbar ist, während wir seine Typisierung nachziehen. Wenn Sie etwas benötigen, das die typisierten Felder nicht bereitstellen, fragen Sie `raw` ab.

<h2 id="uploading-media">
  Medien hochladen
</h2>

**Medien-Bytes können nicht über eine GraphQL-Anfrage übertragen werden.** Eine GraphQL-Anfrage ist ein einzelnes JSON-Dokument mit einem Limit von 64 KB. Es gibt also kein Feld, das eine Datei akzeptiert, und ein als base64 in der Query kodiertes Bild würde dieses Limit bei allem, was größer als ein Thumbnail ist, überschreiten.

Der unterstützte Weg umgeht das Problem vollständig und ist ohnehin schneller als ein Upload über eine API, da Ihre Bytes direkt in den Speicher gehen:

1. Fordern Sie eine Upload-URL an:

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

2. Lesen Sie `data.mediaUploadUrl.uploadUrl`, `accessUrl` und `contentType` aus dem zurückgegebenen JSON.

3. Senden Sie Ihre Datei per `PUT` **direkt an `uploadUrl`**, nicht an die Ayrshare-API, und setzen Sie den `Content-Type`-Header der Anfrage auf den zurückgegebenen `contentType`.

4. Übergeben Sie nach erfolgreichem Upload `accessUrl` in `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 }
     }
   }
   ```

Behandeln Sie `uploadUrl` als kurzlebige Schreibberechtigung und protokollieren oder veröffentlichen Sie sie nicht. `accessUrl` ist die Medien-URL, die beim Erstellen des Beitrags verwendet wird.

Sie können auch weiterhin die [REST-Upload-Endpunkte](/docs/apis/media/upload-media) verwenden und die resultierenden URLs aus GraphQL referenzieren. Beide Schnittstellen teilen sich dieselbe Medienbibliothek.

<h2 id="read-next">
  Weiterlesen
</h2>

<ul class="custom-bullets">
  <li>[Fehler](/docs/apis/graphql/errors) – HTTP-Statuscodes, Fehlerstrukturen und Teilerfolge.</li>
  <li>[Limits und Abrechnung](/docs/apis/graphql/limits) – Obergrenzen für die Abfragegröße und wie Anfragen gezählt werden.</li>
</ul>