GraphQL

Schema Loading & Caching

API Studio fetches and caches your GraphQL schema to power autocomplete, lint, and the docs panel. Four schema operations are available:

Introspection

Click Fetch Schema to send the standard introspection query to the endpoint. The result is cached with a timestamp and displayed with an introspection source badge.

SDL Import

Paste or browse a .graphql / .gql file. The schema is parsed locally without a network request. Shows an sdl source badge.

Schema URL Override

Point the introspection fetch at a different endpoint than the one used for request execution. Set via the schemaUrlOverride field in the request body settings.

Clear Schema

Reset the cached schema for the current URL. Useful when the server schema has changed and you want a fresh introspection.

Cache details: Schemas are stored in graphql-schemas.json, keyed by normalized URL (lowercase host, no default port, no trailing slash). Each entry records the source (introspection or sdl) and a fetchedAt timestamp.

CodeMirror 6 Editor

The query editor is powered by CodeMirror 6 with the cm6-graphql extension for full language support.

Syntax highlighting — GraphQL keywords, types, fields, and arguments are color-coded

Schema-aware autocomplete — press Ctrl+Space to complete field names, arguments, types, and directives against the fetched schema

Inline lint — red squiggles under invalid fields, wrong argument types, and missing required arguments

Prettify — one-click formatting for both query and variables (idempotent)

Separate editors — Query uses # comments; Variables uses // and /* */ comments

Zoom controls — A- / A+ / ↺ buttons per editor instance (12px default, session-only)

Variable decoration — {{variable}} tokens are decorated with per-source colors (global-env, vault, local-env, collection, unresolved)

Visual Query Builder

Build queries visually without writing GraphQL by hand. The builder generates the full operation string in real-time as you check fields.

Checkbox field tree — grouped by Query / Mutation / Subscription root types

Auto-generated variables — argument variable declarations are created automatically with names like {dotPath}_{argName}

Value preservation — manually-entered variable values are preserved when switching between operations

Real-time sync — selecting fields instantly generates the query in the editor

Variable naming: For a field at path countries.name with argument filter, the variable is named $countries_name_filter. Dots in the path are replaced with underscores.

Docs Panel

A searchable type browser built from the fetched schema — navigate types, fields, and arguments without leaving the editor.

Full-text search — find any type, field, or description by keyword

Clickable types — click any type reference to navigate to its definition

Breadcrumb navigation — navigate back through the type hierarchy via the breadcrumb trail

Inline details — field descriptions and argument signatures displayed directly

Multi-Operation Support

Work with multiple named operations in a single document. API Studio handles operation selection and cleanup automatically.

Operation picker — when the document contains more than one named operation, a dropdown appears above the editor

Selective execution — only the selected operation is sent; operationName is included in the request body

Auto-cleanup — switching to a single-operation document clears stale operationName automatically

cURL export — operationName is included in generated cURL commands

Subscriptions (graphql-transport-ws)

Subscribe to real-time data streams using the modern graphql-transport-ws subprotocol.

Auto-detection — when the active operation is a subscription, the Send button becomes Subscribe

WebSocket transport — uses the graphql-transport-ws subprotocol over WebSocket

Protocol flow — connection_init → connection_ack → subscribe → next / error / complete

Live event panel — shows connection status, elapsed time, event count, and each next payload pretty-printed as JSON

Unsubscribe — click Unsubscribe to send a complete frame and close the stream

Keep-alive — ping / pong frames handled automatically

Auth injection — auth headers are injected into the WebSocket handshake request

GraphQL Variables

The variables editor sits below the query editor and accepts JSON with full comment support.

JSON editor — dedicated CodeMirror instance below the query with JSON syntax highlighting

Comment support — use // single-line and /* */ multi-line comments; stripped before sending

Error handling — invalid JSON shows a descriptive error: Invalid JSON in GraphQL variables: …

Environment interpolation — {{env_var}} placeholders are resolved before JSON parsing

Example with comments and variables:

{
  // User ID from environment
  "userId": "{{user_id}}",
  /* Pagination */
  "first": 10,
  "after": null
}

Tips & Troubleshooting

Autocomplete not working?

Check that the schema has been fetched — look for the green source badge next to the URL. Without a schema, autocomplete and lint are disabled.

Schema URL override

Use when the introspection endpoint differs from the runtime endpoint (e.g., gateway vs. service URL, or schema only exposed on a dev port).

Large schemas

Initial introspection fetch may take a few seconds for very large schemas. Results are cached afterward — subsequent loads are instant.

Subscriptions not connecting?

The server must support the graphql-transport-ws subprotocol (the modern standard). The legacy subscriptions-transport-ws protocol is not supported.