GraphQL

Curlex treats GraphQL as a first-class request type, not an afterthought. You get a dedicated query editor, automatic schema loading from your API, intelligent field autocomplete, real-time subscription streams, and clear error highlighting for partial failures — all without installing any plugins or switching to another tool.

Getting Started

Creating a GraphQL Request

There are two ways to start a new GraphQL request:

1. Click the + button in the sidebar rail and choose New GraphQL Request from the menu.
2. Or open any existing request, go to the Body tab, open the body type dropdown, and select GraphQL.

Once you have a GraphQL body type selected, the body panel changes to show a query editor at the top and a variables panel below.

Setting the Endpoint

Type your GraphQL API's URL in the URL bar at the top of the request. GraphQL APIs always use POST — make sure the method selector shows POST.

Most GraphQL APIs have a single endpoint, typically something like:

https://api.example.com/graphql

Writing Your Query

The Query Editor

The main editor area is where you write your GraphQL operation. It works like any code editor — you can type freely, and if a schema has been loaded (see below), it will offer autocompletion as you go.

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    createdAt
  }
}

The Prettify button (braces icon, top-right corner of the query editor) reformats and re-indents your query using the official GraphQL parser with one click.

Variables

Click Variables at the bottom of the body panel to expand the JSON variables editor. This is where you supply the values for any $variables used in your query:

{
  "id": "42"
}

A few things to know about variables:

• They fully support {{environmentVariable}} substitution — use the same {{...}} syntax you use everywhere else in Curlex to pull values from your active environment.
• The Braces button (top-right of the variables panel) formats the JSON automatically.
• When variables are set, a small blue dot appears on the Variables label so you can tell at a glance.

How Curlex Sends Your Request

Curlex automatically serialises your query and variables into the standard GraphQL-over-HTTP format:

{
  "query": "query GetUser($id: ID!) { ... }",
  "variables": { "id": "42" },
  "operationName": "GetUser"
}

It also sets Content-Type: application/json automatically — you do not need to set it manually.

Schema Intelligence

Loading your API's schema unlocks the best part of working with GraphQL in Curlex: you get field suggestions as you type, instant error highlighting for invalid queries, and a visual explorer that shows the entire API structure.

Loading the Schema

1. Enter your endpoint URL in the URL bar.
2. Set up any authentication your API requires (in the Auth tab).
3. Click Fetch Schema in the status bar at the top of the GraphQL editor.

Curlex sends a standard GraphQL introspection query to your API. If it succeeds, the status bar changes to Schema loaded — autocomplete active. The schema is cached for 5 minutes; click Fetch Schema again whenever you want a fresh copy.

If schema loading fails: Many production APIs disable introspection for security. If you get an error, double-check that your auth headers are set correctly first — the introspection request uses the same auth as your regular requests. If the API truly has introspection disabled, you will not be able to load the schema automatically.

Using the Schema Explorer

Once a schema is loaded, click Explorer in the status bar to open a sidebar showing the complete API structure:

• Queries, Mutations, and Subscriptions are listed by name.
• Type in the search box to filter by operation name.
• Click the arrow next to any operation to expand it and see its fields, arguments, and return types.
• Click Insert next to any operation to add a starter query to the editor — all arguments are pre-filled with $variable placeholders and the common scalar fields are automatically selected.

This explorer is invaluable when you are working with an unfamiliar API — you can discover all available operations and understand what data each one returns without reading through external documentation.

Autocompletion

With a schema loaded, the query editor suggests field names and argument names as you type:

• Type { inside a type and see all available fields for that type.
• Type ( after a field name and see all available arguments.
• Invalid fields, wrong argument types, and missing required arguments are underlined in red in real time — no need to send the request to find out it will fail.

Understanding GraphQL Errors

GraphQL is unusual compared to REST: the server usually returns HTTP 200 even when something went wrong, and puts the error details inside the response body. Curlex detects this and shows you both the errors and the data clearly.

When a response contains GraphQL errors, an amber warning banner appears at the top of the response body:

⚠ GraphQL returned 2 errors
┌────────────────────────────────────────────────────────┐
│ 1. Cannot query field "unknownField"                    │
│    Path: data.user.unknownField                         │
│    Location: line 4, column 5                          │
│ 2. Unauthorized to view private data                   │
│    Path: data.sensitiveField                           │
└────────────────────────────────────────────────────────┘

• Click the banner to expand or collapse the error list.
• The response data field is still shown normally below the banner — you get the partial data and the errors at the same time.
• The banner is amber (not red) to distinguish it from network errors like connection refused, which show in red.

Real-Time Subscriptions

Curlex supports GraphQL subscriptions — queries that maintain an open connection and push new data whenever something changes on the server.

Writing a Subscription

Write your subscription operation in the query editor:

subscription OnNewMessage($channelId: ID!) {
  messageAdded(channelId: $channelId) {
    id
    body
    author {
      name
    }
    timestamp
  }
}

As soon as Curlex detects that the operation is a subscription, the response panel switches automatically to a real-time message stream view — you do not need to change any settings.

Connecting and Receiving Messages

Click Subscribe to open the WebSocket connection.

Once connected:

• The status badge shows Connecting… → Connected.
• Incoming messages appear at the top of the list as they arrive (newest first).
• Click any message to expand or collapse its full JSON payload.
• A counter in the header shows the total number of messages received.
• Click Clear to empty the message list without disconnecting.
• Click Stop to close the connection.

Protocol

Curlex uses the graphql-transport-ws protocol — the modern standard used by Apollo Server 3+, Yoga, Strawberry, and most contemporary GraphQL servers.

The WebSocket URL is derived automatically from your HTTP endpoint: http:// becomes ws:// and https:// becomes wss://. You do not need to change anything.

Authentication headers you have set in the Headers tab or the Auth tab are included in the WebSocket connection handshake, so your subscriptions work with the same auth as your queries.

Authentication

All of Curlex's authentication options work with GraphQL — the auth tab works exactly the same for GraphQL requests as for REST:

For subscription connections specifically, auth headers are sent as part of the WebSocket upgrade request.

Test Scripts with GraphQL

GraphQL requests support the same pre-request and test scripts as REST requests. Here are some GraphQL-specific patterns:

// Check that the response contains no errors
fc.test("No GraphQL errors", function () {
    var body = fc.response.json();
    fc.expect(body.errors).to.be.undefined;
});

// Check that the data object is present
fc.test("Response has data", function () {
    var body = fc.response.json();
    fc.expect(body.data).to.exist;
});

// Check a specific field value
fc.test("User name is correct", function () {
    var user = fc.response.json().data.user;
    fc.expect(user.name).to.equal("Alice");
});

// Save a value from the response to use in the next request
fc.test("Store user ID", function () {
    var id = fc.response.json().data.createUser.id;
    fc.environment.set("newUserId", id);
});

GraphQL in the Collection Runner

GraphQL requests work in the Collection Runner exactly like REST requests. Mix them freely in a collection — you can have a login REST request that stores a token, followed by GraphQL queries that use it, all in one automated run.

• Use {{collectionVariable}} placeholders in the variables panel — they are substituted per iteration.
• Test assertions run on each GraphQL response.
• Pass/fail results appear in the runner output alongside REST results.

Public GraphQL APIs to Explore

These free APIs are great for trying out Curlex's GraphQL features. No signup or API key required.

Countries API

Endpoint: https://countries.trevorblades.com/graphql

Introspection is enabled — click Fetch Schema to load the schema and explore available types in the Explorer.

{
  countries {
    code
    name
    emoji
    currency
  }
}

query GetCountry($code: ID!) {
  country(code: $code) {
    name
    capital
    currency
    languages {
      name
    }
  }
}

Variables: { "code": "US" }

SpaceX API

Endpoint: https://spacex-production.up.railway.app/

{
  launches(limit: 5, sort: "launch_date_local", order: "desc") {
    mission_name
    launch_date_utc
    rocket {
      rocket_name
    }
  }
}

GitHub GraphQL API

Endpoint: https://api.github.com/graphql

Requires a Bearer token — create a Personal Access Token in GitHub Settings → Developer settings → Personal access tokens, then paste it in the Auth tab.

{
  viewer {
    login
    name
    repositories(first: 5, orderBy: { field: UPDATED_AT, direction: DESC }) {
      nodes {
        name
        stargazerCount
        primaryLanguage { name }
      }
    }
  }
}

Rick and Morty API

Endpoint: https://rickandmortyapi.com/graphql

{
  characters(filter: { species: "Human" }) {
    results {
      id
      name
      status
      image
    }
  }
}

Seeing the Error Banner in Action

Send a query with a field that does not exist to trigger the amber error banner:

Endpoint: https://countries.trevorblades.com/graphql

{
  countries {
    code
    name
    nonExistentField
  }
}

Curlex will show the error banner with the exact field name, query line, and column number.

Tips

• Always use POST. GraphQL APIs use a single POST endpoint for all operations — queries, mutations, and subscriptions all go to the same URL.
• Set auth before fetching the schema. The introspection request uses your current auth settings. If your API requires a token to query, it also requires one for introspection.
• Use the Explorer for unfamiliar APIs. Instead of reading through external documentation, load the schema and use the Explorer to browse available operations and their fields interactively.
• Large responses are handled gracefully. Very large GraphQL responses trigger the same streaming behaviour as REST — a notice appears with a "Load full response" button.
• GraphQL requests appear in History just like REST requests, with the full query and variables saved.
• Generate code for any GraphQL request using More → Generate Code in the request toolbar — get cURL, Fetch, Axios, Python, and other snippets.