GraphQL API Overview

The GraphQL API exposes a supported subset of Ayrshare’s REST capabilities through a single endpoint. Each exposed field calls the same underlying controller as its REST counterpart, so authentication, entitlements, quotas, and response data follow the REST behavior. REST remains the broader API; use the schema or Explorer to see exactly which operations GraphQL supports. What it adds is the ability to ask for several things in one request and to discover the currently supported GraphQL surface from the schema itself, without reading documentation page by page. The schema describes every supported request field and the typed selections available on structured responses; operations that return the REST envelope as JSON preserve that complete payload.

https://api.ayrshare.com/graphql

Send a POST with a JSON body containing a query, exactly as with any GraphQL endpoint. GET and DELETE return 405 Method Not Allowed — queries over GET are optional in the GraphQL specification and are not supported here.

Your first query

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

The response is the same JSON envelope the REST history endpoint returns, wrapped in GraphQL’s data field:

{
  "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"
    }
  }
}

Asking for several things at once

The reason to reach for GraphQL is a request like this, which would be four REST calls:

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

One round trip returns all four. Note that these are four root operation fields and four API calls for billing purposes, not one. Selecting nested response fields does not add calls — see Limits and Billing.

Authentication

Identical to REST. Send your API key as a bearer token:

Authorization: Bearer YOUR_API_KEY

If your account uses User Profiles, operations that expose profileKey can select a profile in either of two ways:

Send Profile-Key as the request-wide default.
Pass profileKey on an individual field to override that default, allowing one request to act on more than one profile.

The field argument wins when both are present. Account-level or primary-account-only fields do not expose profileKey and may reject a Profile-Key header; for example, createProfile must use the primary API key without that header. Check each field’s schema definition for its scope, and see Managing multiple users for how profile keys work.

Try it without writing code

The GraphQL Explorer is an interactive browser for the current schema. It lists every available GraphQL operation with its arguments and descriptions, autocompletes as you type, and runs queries against your account. You do not need an API key to browse the schema — the schema is public, the same way this documentation is. You do need one to run a query, because every operation goes through the same authentication as REST.

Should you use GraphQL or REST?

REST remains the primary interface and the one most of our documentation, SDKs, and integrations are built around. Reach for GraphQL when:

You need several unrelated pieces of data and want them in one round trip.
You want machine-readable operation names, arguments, input objects, enums, and typed response selections. Most responses remain JSON so they preserve the complete REST envelope; createPost currently returns a typed PostResult.
You are exploring the API and want to see what exists without moving between documentation pages.

Stay with REST when:

You are uploading files. Media bytes cannot travel through a GraphQL request — see Uploading media for the supported path.
You are using one of our SDKs or no-code integrations, which speak REST.
You want the smallest possible dependency footprint. A REST call needs nothing but an HTTP client.

Both interfaces are supported side by side, and you can mix them freely in the same integration.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Your first query

Asking for several things at once

Authentication

Try it without writing code

Should you use GraphQL or REST?

Read next

​Your first query

​Asking for several things at once

​Authentication

​Try it without writing code

​Should you use GraphQL or REST?

​Read next

Your first query

Asking for several things at once

Authentication

Try it without writing code

Should you use GraphQL or REST?

Read next