GraphQL is the advanced, lower-level surface. For most integrations the REST API is simpler and gives you a stable, versioned contract. Reach for GraphQL when you specifically need its flexibility.
Endpoint
Introspection is enabled, so you can explore the full schema from any GraphQL client (GraphiQL, Apollo Sandbox, Insomnia) pointed at the endpoint.
Making a request
Schema shape
The schema is generated from the data model, so it follows consistent Relay conventions:- Connections for lists —
first/afterarguments and{ totalCount, pageInfo { hasNextPage, endCursor }, edges { node { … } } }results. (The REST API flattens these into{ data, page }.) whereinputs for filtering andorderByfor sorting on list fields.- A
Cursorscalar for pagination positions.
Errors
A refusal is an entry of the top-levelerrors array. Its extensions has the shape of the schema’s ApiError type: code is a value of the ErrorCode enum, and some codes add a reason or a cause. Branch on code, never on the message.
ErrorCode for the full list with a one-line description each.
Deprecation
A retiring field or argument is marked@deprecated(reason: "…") with what replaces it, and stays for at least 90 days. Introspection shows the mark (includeDeprecated: true), and the conventions page lists what is retiring and when. Additions never break a query that worked.
Choosing GraphQL vs REST vs MCP
REST
Stable, versioned, simplest to call. The default choice for scripts and servers.
MCP
For AI agents — the same operations exposed as tools over OAuth.
GraphQL
Maximum control over fields, filtering, and relationships. Advanced clients.