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

> 単一の GraphQL エンドポイントを通じて、サポートされている Ayrshare のソーシャルメディア操作をクエリできます。

GraphQL API は、Ayrshare の REST 機能のうちサポートされているサブセットを単一のエンドポイントで公開します。公開されている各フィールドは対応する REST と同じ内部コントローラーを呼び出すため、認証、利用権限、クォータ、レスポンスデータは REST の動作に従います。REST は引き続きより広範な API です。GraphQL がどの操作をサポートしているかを正確に確認するには、スキーマまたは Explorer を使用してください。

GraphQL によって追加されるのは、1 回のリクエストで複数のものを要求できる機能と、ドキュメントを 1 ページずつ読まなくても、現在サポートされている GraphQL の範囲をスキーマ自体から把握できる機能です。スキーマには、サポートされているすべてのリクエストフィールドと、構造化されたレスポンスで利用可能な型付きの選択項目が記述されています。REST のエンベロープを `JSON` として返す操作は、そのペイロード全体をそのまま保持します。

```
https://api.ayrshare.com/graphql
```

他の GraphQL エンドポイントとまったく同じように、`query` を含む JSON ボディを付けて `POST` を送信します。`GET` と `DELETE` は `405 Method Not Allowed` を返します。`GET` によるクエリは GraphQL 仕様ではオプションであり、ここではサポートされていません。

<h2 id="your-first-query">
  最初のクエリ
</h2>

```bash theme={"system"}
curl -X POST https://api.ayrshare.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ postHistory(lastDays: 7) }"}'
```

レスポンスは、[REST の履歴エンドポイント](/docs/apis/history/get-history)が返すものと同じ JSON エンベロープを、GraphQL の `data` フィールドで包んだものです:

```json theme={"system"}
{
  "data": {
    "postHistory": {
      "history": [
        { "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }
      ],
      "refId": "9d2a7c41f0b8e6d35a1c",
      "count": 1,
      "lastUpdated": "2026-09-24T12:00:00.000Z",
      "nextUpdate": "2026-09-24T12:00:00.000Z"
    }
  }
}
```

<h2 id="asking-for-several-things-at-once">
  複数のものを一度に要求する
</h2>

GraphQL を使う理由は、REST なら 4 回の呼び出しが必要になる次のようなリクエストです:

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

1 回のラウンドトリップで 4 つすべてが返されます。ただし、これは 1 回ではなく、**4 つのルート操作フィールドであり、課金上は 4 回の API 呼び出し**となる点に注意してください。ネストされたレスポンスフィールドを選択しても呼び出し回数は増えません。[制限と課金](/docs/apis/graphql/limits)を参照してください。

<h2 id="authentication">
  認証
</h2>

REST と同じです。API キーを Bearer トークンとして送信します:

```
Authorization: Bearer YOUR_API_KEY
```

アカウントで User Profiles を使用している場合、`profileKey` を公開している操作では、次の 2 つの方法のいずれかでプロファイルを選択できます:

<ul class="custom-bullets">
  <li><code>Profile-Key</code> をリクエスト全体のデフォルトとして送信する。</li>
  <li>個々のフィールドで <code>profileKey</code> を渡してそのデフォルトを上書きし、1 回のリクエストで複数のプロファイルを操作する。</li>
</ul>

両方が指定されている場合は、フィールドの引数が優先されます。アカウントレベルまたはプライマリアカウント専用のフィールドは `profileKey` を公開しておらず、`Profile-Key` ヘッダーを拒否する場合があります。たとえば、`createProfile` はそのヘッダーを付けずにプライマリの API キーで使用する必要があります。各フィールドのスコープについてはスキーマ定義を確認し、Profile Key の仕組みについては[複数ユーザーの管理](/docs/multiple-users/business-plan-overview)を参照してください。

<h2 id="try-it-without-writing-code">
  コードを書かずに試す
</h2>

[GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) は、現在のスキーマを対話的に閲覧できるブラウザです。利用可能なすべての GraphQL 操作を引数や説明とともに一覧表示し、入力中に自動補完を行い、あなたのアカウントに対してクエリを実行できます。

スキーマの閲覧に API キーは必要ありません。このドキュメントと同様に、スキーマは公開されています。ただし、クエリを実行するには API キーが必要です。すべての操作は REST と同じ認証を通過するためです。

<h2 id="should-you-use-graphql-or-rest">
  GraphQL と REST のどちらを使うべきか
</h2>

REST は引き続き主要なインターフェースであり、ほとんどのドキュメント、[SDK](/docs/packages-guides/overview)、インテグレーションは REST を中心に構築されています。次のような場合は GraphQL を使用してください:

<ul class="custom-bullets">
  <li>関連のない複数のデータが必要で、それらを 1 回のラウンドトリップで取得したい場合。</li>
  <li>機械可読な操作名、引数、入力オブジェクト、列挙型、型付きのレスポンス選択を利用したい場合。ほとんどのレスポンスは REST のエンベロープ全体を保持するため引き続き <code>JSON</code> ですが、<code>createPost</code> は現在、型付きの <code>PostResult</code> を返します。</li>
  <li>API を調べていて、ドキュメントのページを行き来せずに何が存在するかを確認したい場合。</li>
</ul>

次のような場合は REST を使い続けてください:

<ul class="custom-bullets">
  <li>ファイルをアップロードする場合。メディアのバイトデータは GraphQL リクエストでは送信できません。サポートされている方法については <a href="/docs/apis/graphql/using-the-api#uploading-media">メディアのアップロード</a> を参照してください。</li>
  <li>REST を使用する <a href="/docs/packages-guides/overview">SDK やノーコードインテグレーション</a> のいずれかを使用している場合。</li>
  <li>依存関係を可能な限り最小限にしたい場合。REST 呼び出しに必要なのは HTTP クライアントだけです。</li>
</ul>

どちらのインターフェースも並行してサポートされており、同じインテグレーション内で自由に組み合わせることができます。

<h2 id="read-next">
  次に読む
</h2>

<ul class="custom-bullets">
  <li>[API の使用](/docs/apis/graphql/using-the-api) — 操作の探し方、引数の型、メディアのアップロード。</li>
  <li>[エラー](/docs/apis/graphql/errors) — HTTP ステータスが変わる失敗の種類、失敗した操作でも HTTP 200 が返る理由、部分的な成功の扱い方。</li>
  <li>[制限と課金](/docs/apis/graphql/limits) — クエリサイズの上限と、リクエストのカウント方法。</li>
</ul>