---
title: "GraphQL query/mutation"
method: POST
path: "/v1/graphql"
tags: ["graphql"]
---

# GraphQL query/mutation

`POST /v1/graphql`

Execute a GraphQL operation. Accepts the standard GraphQL request envelope (`query`, optional `variables`, `operationName`, `extensions`). Authentication is optional: an admin secret grants admin role; a valid JWT bearer grants the user's role; anonymous requests are served with the public role.

## Request body

- GraphQLRequest
  - `query` string, required — GraphQL document text
  - `operationName` string, nullable — Operation to execute when the document defines more than one
  - `variables` object, nullable — Variable bindings referenced by the document
  - `extensions` object, nullable — Protocol extensions (persisted queries, tracing toggles, ...)

## Response `200`

GraphQL response envelope (may carry partial data + errors)

- GraphQLResponse — GraphQL response envelope. `data` and `errors` may both be present for partially-successful operations.
  - `data` unknown
  - `errors` GraphQLError[]
    - `message` string, required
    - `path` union[] — Response-path of the error
      - union
        - string
        - integer
    - `locations` object[]
      - `line` integer
      - `column` integer
    - `extensions` object
  - `extensions` object — Protocol extensions (tracing, persisted-query acks, ...)

## Other responses

- `400` — Malformed request (invalid JSON, missing query, etc.)
- `401` — Invalid admin secret or bearer token

---

[API](https://skmtc.dev/nhost/apis/nhost-constellation-api.md) · [All operations](https://skmtc.dev/nhost/apis/nhost-constellation-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhost/nhost-constellation-api/revisions/d676467fb711/schema)