Skip to main content
View as Markdown

Learn GraphQL

Swapcard's Content and Leads APIs are GraphQL APIs. Here is what you need to know to use them well.

Why GraphQL​

  • Ask for exactly what you need. A request lists the fields it wants, and the response has the same shape, with nothing more.
  • One endpoint. Every operation goes to the same URL; what changes is the query you send.
  • A typed, self-describing schema. Every field has a type, invalid input is rejected before anything runs, and tools like the API Explorer can autocomplete the whole API.
  • Works with any language. GraphQL is plain JSON over HTTP, and client libraries exist for every major stack.

Why GraphQL works well with AI coding tools​

If you build with an AI assistant (Claude Code, Cursor, Copilot or your own agent), GraphQL gives it more to work with than a typical REST API:

  • The schema is a machine-readable contract. Through introspection, an assistant can discover every type, field and argument at runtime instead of guessing endpoints and parameter shapes from prose.
  • Mistakes are caught before anything runs. If a model invents a field or passes the wrong type, the server rejects the operation with a precise validation error, which the assistant can read and fix on its own.
  • Smaller responses, less context. Asking only for the fields you need keeps responses short, so more of the model's context window stays available for your code.

This works best when the schema is descriptive: clear names and field descriptions are what the model actually reads. Much of the writing on this comes from GraphQL tooling vendors, so treat it as practical guidance rather than measured benchmarks. See GraphQL: Supercharging AI on graphql.org for a broader take.

Tips for using Swapcard's APIs with an assistant:

  1. Give it the docs: use Copy for LLM on any page, or point it at /llms.txt for an index of every guide in Markdown.
  2. Let it check its work: paste generated operations into the API Explorer, which validates them against the live schema.
  3. Keep operations in .graphql files and generate types from the schema, so mistakes surface at build time rather than in production.

Core concepts​

Queries and mutations​

A query reads data, and a mutation changes it. Both are sent as a POST with a JSON body containing the operation and its variables:

{
  "query": "query EventById($eventId: ID!) { event(id: $eventId) { title } }",
  "variables": { "eventId": "<EVENT_ID>" }
}

Variables​

Keep operations static and pass values through variables, as above. This avoids string-building bugs and makes operations reusable.

Pagination​

List fields are paginated. Request a page with pageSize (maximum 200; 100 is recommended), or use cursors: query with first, then pass the returned endCursor as after to get the next page.

Errors​

A GraphQL response can return HTTP 200 and still contain an errors array. Always check errors as well as the HTTP status. Many mutations also return their own errors field with validation messages.

Further reading​

Agents

View as Markdown