GraphQL Support in Curlex

Curlex provides first-class GraphQL support — you don't need a separate tool for GraphQL APIs. Everything from queries to real-time subscriptions is handled natively, with schema intelligence and error highlighting built in.

Getting Started

1. Create a new request or open an existing one.
2. Set the HTTP method to POST (GraphQL APIs always use POST).
3. Enter your GraphQL endpoint URL (e.g. https://api.example.com/graphql).
4. In the Body tab, open the body type selector and choose GraphQL.

The body panel changes to the GraphQL editor with a query editor on top and a variables panel below.

Body Type: GraphQL

Query Editor

The full-width editor at the top is where you write your GraphQL operations:

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

Keyboard & toolbar actions:

• Prettify (Braces icon, top-right of query editor): formats and re-indents the query using the official GraphQL parser.
• Syntax highlighting and autocompletion are available when a schema is loaded (see Schema Intelligence below).

Variables Panel

Click Variables at the bottom of the body panel to expand the JSON variables editor:

{
  "id": "42"
}

• Variables support {{environment_variable}} placeholder substitution — the same syntax used in headers and URL parameters.
• The Braces button (top-right of the variables panel) formats the JSON.
• A blue dot on the Variables label indicates that variables are currently set.

Serialisation

Curlex automatically serialises your query + variables into the correct GraphQL-over-HTTP wire format before sending:

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

Content-Type: application/json is injected automatically if you haven't set it yourself.

Schema Intelligence

When a schema is available, the query editor gains full autocompletion and inline validation.

Fetching a Schema via Introspection

1. Enter your endpoint URL in the URL bar.
2. In the GraphQL body editor, click Fetch Schema (top status bar).
3. Curlex sends an introspection query to the endpoint using your current auth headers and TLS settings.
4. On success, the status bar shows Schema loaded — autocomplete active and the Schema Explorer becomes available.

Schema is cached in-memory for 5 minutes. Click Fetch Schema again to refresh.

Note: Introspection must be enabled on the server. Some production APIs disable it. If introspection fails, check the error message in the status bar — common causes are auth (add an Authorization header first), CORS, or server-side introspection disabled.

Schema Explorer

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

• Queries / Mutations / Subscriptions sections list all available operations.
• Filter by typing in the search box at the top.
• Click ▶ to expand an operation and see its return type's sub-fields.
• Click Insert next to any operation to inject a stub query into the editor — arguments are pre-filled with $variable references and scalar return fields are auto-selected.

Autocompletion

With a schema loaded, the editor provides:

• Field completion — type { and see available fields for the current type context.
• Argument completion — type ( inside a field call to see argument names and types.
• Type completion — fragment type conditions and variable types are completed from the schema.
• Inline validation — unknown fields, wrong argument types, and missing required arguments are underlined in real time.

GraphQL Error Highlighting

GraphQL APIs frequently return HTTP 200 with { errors: [...] } alongside partial data. Curlex detects this pattern and shows a collapsible error banner above the response body:

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

• Click the banner header to collapse/expand the error details.
• The response data field is still shown normally below the banner — you get both the partial data and the errors simultaneously.
• The banner is amber-coloured to distinguish it from network-level errors (which are red).

GraphQL Subscriptions

Curlex detects when your operation is a subscription and automatically switches the response panel to a real-time message stream view.

Setup

1. Write a subscription operation in the query editor:

subscription OnMessageAdded {
  messageAdded {
    id
    body
    sender
  }
}

2. The response panel automatically switches to the Subscription Stream view.
3. Click Subscribe to open a WebSocket connection.

Message Stream

Once connected:

• Incoming messages appear in reverse-chronological order (newest at top).
• Each message is collapsible — click to expand/collapse the JSON payload.
• The status badge shows: Connecting… → Connected → Disconnected.
• A message counter shows the number of data events received.
• Click Clear to empty the message list without disconnecting.
• Click Stop to disconnect.

Protocol

Curlex uses the graphql-transport-ws subprotocol (graphql-ws) — the modern standard adopted by Apollo Server 3+, graphql-ws, and most contemporary GraphQL servers.

The WebSocket URL is derived from the request URL automatically (http:// → ws://, https:// → wss://).

Auth with GraphQL

All existing Curlex auth types work transparently with GraphQL:

For subscriptions, auth headers set in the Headers tab are included in the WebSocket handshake.

Pre-request & Test Scripts

GraphQL requests support the same pre-request and test scripts as REST requests.

Example test script for GraphQL:

// Assert no GraphQL errors in response
const body = response.json();
fx.test("No GraphQL errors", () => {
  fx.expect(body.errors).to.be.undefined;
});

// Assert data is present
fx.test("Response has data", () => {
  fx.expect(body.data).to.not.be.null;
});

// Assert specific field value
fx.test("User name is correct", () => {
  fx.expect(body.data.user.name).to.equal("Alice");
});

Collection Runner with GraphQL

GraphQL requests work in the Collection Runner just like REST requests:

• Include them in a collection and run them in sequence.
• Use collection variables as GraphQL variables: {{userId}} in the variables panel maps to collection variable userId.
• Test assertions are evaluated for each GraphQL request in the run.
• Pass/fail results appear in the runner output alongside REST requests.

Public GraphQL APIs for Testing

Use these free, publicly available APIs to try out Curlex's GraphQL features end-to-end:

1. Countries API (no auth)

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

Test query:

{
  countries {
    code
    name
    emoji
    currency
  }
}

With variables:

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

{ "code": "US" }

Schema introspection: Click Fetch Schema — this endpoint has introspection enabled. You'll see Query.countries, Query.country, Country, Language, Continent types in the explorer.

2. SpaceX API (no auth)

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

Test query:

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

3. GitHub GraphQL API (requires auth)

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

Add a Bearer token in the Auth tab (Personal Access Token from GitHub → Settings → Developer settings → Personal access tokens).

Test query:

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

4. Rick and Morty API (no auth)

Endpoint: https://rickandmortyapi.com/graphql

Test query:

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

With pagination variables:

query GetEpisodes($page: Int!) {
  episodes(page: $page) {
    info {
      count
      pages
      next
    }
    results {
      name
      air_date
      characters {
        name
      }
    }
  }
}

{ "page": 1 }

5. GraphQL Jobs API (no auth — good for subscriptions testing)

Endpoint: https://api.graphql.jobs/

Test query:

{
  jobs {
    title
    company {
      name
      websiteUrl
    }
    cities {
      name
    }
    remotes {
      type
    }
  }
}

Testing GraphQL Error Highlighting

To see the error banner in action, send a query with a field that doesn't exist:

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

{
  countries {
    code
    name
    nonExistentField
  }
}

Curlex will show the amber GraphQL returned 1 error banner above the response body with the exact field and line number.

Keyboard Shortcuts

Tips

• Method: Always use POST for GraphQL queries and mutations. The Send button and method selector work the same as for REST.
• Endpoint URL: GraphQL APIs typically have a single endpoint like /graphql that handles all operations.
• Introspection errors: If the schema fetch fails with a 4xx error, set up auth first (the introspection request uses the same auth as your regular requests).
• Large responses: Very large GraphQL responses trigger the same 5 MB truncation banner as REST — click "Load full response" to stream the complete payload.
• History: GraphQL requests appear in History just like REST requests, with the full query and variables stored.
• Code generation: Use Generate code (Send → Generate code) to get cURL, Axios, fetch, and other code snippets for your GraphQL request.