Skip to main content

​
Finding an operation

The schema is authoritative for the supported GraphQL subset: operation roots, names, arguments, input types, and enum values. Descriptions provide usage guidance, and the GraphQL Explorer exposes both. For REST-only capabilities, use the REST API reference. Operation names follow the REST endpoints they reach, in camelCase. GET /history is postHistory, GET /analytics/social is socialAnalytics, POST /post is createPost.

​
Queries read, mutations write

Queries are reads and validations that change nothing on our side. Mutations publish or change state, start work, or send email. Neither the REST HTTP verb nor the cost of a call decides the root:
  • validatePost checks a post without publishing it.
  • validateMedia checks that a media URL is reachable.
  • generatePost is a query because nothing on our side changes. It still counts as an API call and returns different text each time, so make sure a client cache or automatic refetch does not repeat it without you noticing.
  • mediaUploadUrl is a mutation because it creates an upload URL for your account.
  • linkAnalytics is a mutation because it can request an emailed report.
  • userBatch is a mutation because it starts an export job.
Use the Explorer or schema to confirm the root for each supported operation.

​
Creating a post

createPost takes a single input argument, so the whole post is one object:
The input mirrors the documented REST post endpoint, including per-network option objects and the REST forms that accept more than one JSON shape:
A post can succeed on one network and fail on another. That is not a request failure — see Errors.

​
Argument types

Most arguments are ordinary strings, numbers and booleans. Three cases are worth knowing about.

​
Enums

Many string arguments with a closed supported set are GraphQL enums, written unquoted and upper case:
Not "instagram". The server maps each accepted enum to the exact value expected by the underlying REST controller — often, but not always, a lowercase string. An invalid enum is rejected during GraphQL validation before the operation runs, so a typo costs you nothing. Some arguments share a name across operations but accept different values, because the endpoints genuinely differ. reviews(platform:) accepts only GMB and FACEBOOK, since those are the only networks with reviews. Your client’s autocomplete will show the correct set for each operation.

​
The JSON scalar

A few arguments are typed as JSON rather than a specific type. This happens where a value legitimately has more than one shape and no single GraphQL type could describe it honestly:
  • explainError(code:) accepts 215 or “215”, because customers hold error codes as both.
  • createPost(input:) uses JSON for fields such as post and mediaUrls, which can be shared values or per-platform objects.
  • createAutomation(triggers:, actions:) take arrays whose fields depend on each entry’s type.
  • boostFacebookPost(interests:) accepts Meta interest ids as strings or numbers.
Pass the same value you would send in the corresponding REST body. A JSON argument is not a loophole: the resolver validates it before dispatch, so an invalid value returns a validation error and consumes no API call.

​
Optional arguments and nulls

For optional arguments and optional fields inside input objects, explicit null is normalized to omission. Null members inside lists are preserved when the list type permits them.

​
Reading responses

Most operations return a JSON scalar containing the complete REST response envelope, so select the root field without subfields. createPost currently returns a typed PostResult, so select its fields:
Typed response types such as PostResult also include raw: JSON!, containing the complete unmodified REST response:
raw is permanent and is there so a new field appearing in the REST response is never unreachable from GraphQL while we catch up on typing it. If you need something the typed fields do not expose, ask for raw.

​
Uploading media

Media bytes cannot travel through a GraphQL request. A GraphQL request is a single JSON document under a 64 KB limit, so there is no field that accepts a file, and encoding an image as base64 inside the query would exceed that limit for anything larger than a thumbnail. The supported path avoids the problem entirely, and is faster than uploading through an API in any case, because your bytes go straight to storage:
  1. Ask for an upload URL:
  2. Read data.mediaUploadUrl.uploadUrl, accessUrl, and contentType from the returned JSON.
  3. PUT your file directly to uploadUrl, not to the Ayrshare API, setting the request’s Content-Type header to the returned contentType.
  4. After the upload succeeds, pass accessUrl in createPost.input.mediaUrls:
Treat uploadUrl as a short-lived write credential and do not log or expose it. accessUrl is the media URL used when creating the post. You can also keep using the REST upload endpoints and reference the resulting URLs from GraphQL. The two interfaces share the same media library.
  • Errors — HTTP status codes, error shapes, and partial success.
  • Limits and Billing — query size caps and how requests are counted.