# GraphQL setup (/api-playground/graphql-setup)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 995 · updated: 2026-07-30 -->
Related: [API playground overview](/api-playground/overview.md), [OpenAPI setup](/api-playground/openapi-setup.md), [Complex data types](/api-playground/complex-data-types.md), [Add SDK examples](/api-playground/adding-sdk-examples.md), [Manage page visibility](/api-playground/managing-page-visibility.md), [Multiple responses](/api-playground/multiple-responses.md)

## Add a GraphQL schema [#add-a-graphql-schema]

To create pages for your GraphQL API, you need a valid GraphQL schema in SDL (Schema Definition Language) format. Store the schema in your documentation repository or host it at an HTTPS URL that Mintlify can fetch.

```graphql title="schema.graphql"
"An object with a stable identifier."
interface Node {
  id: ID!
}

type Organization implements Node {
  id: ID!
  name: String!
}

type Query {
  organization(id: ID!): Organization
}
```

## Auto-populate GraphQL pages [#auto-populate-graphql-pages]

To automatically generate pages for every query, mutation, and type in your schema, add a `graphql` property to a tab in your `docs.json`. Mintlify parses the schema and creates a page for each operation and named type.

<CodeGroup>
  <CodeBlockTabs defaultValue="Local file" groupId="custom-directory+local-file+remote-url">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Local file">
        Local file
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Remote URL">
        Remote URL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Custom directory">
        Custom directory
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Local file">
      ```json  
      "navigation": {
        "tabs": [
          {
            "tab": "GraphQL API",
            "graphql": "schema.graphql"
          }
        ]
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Remote URL">
      ```json  
      "navigation": {
        "tabs": [
          {
            "tab": "GraphQL API",
            "graphql": "https://example.com/schema.graphql"
          }
        ]
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Custom directory">
      ```json  
      "navigation": {
        "tabs": [
          {
            "tab": "GraphQL API",
            "graphql": {
              "source": "schema.graphql",
              "directory": "api/graphql"
            }
          }
        ]
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

The `graphql` property accepts either a string (a local path or HTTPS URL) or an object with the following fields.

<Note>
  You must declare `graphql` on a [tab](/organize/navigation#tabs). A tab with `graphql` may include `groups`, but no other navigation structures, such as `pages`, `versions`, or `languages`. It also cannot include an `openapi` or `asyncapi` property.
</Note>

<ParamField path="source" type="string">
  A local path to an SDL file in your documentation repository or an HTTPS URL to a hosted SDL file. Does not accept HTTP URLs.
</ParamField>

<ParamField path="directory" type="string">
  The directory to store generated pages. Defaults to `graphql-reference`.
</ParamField>

## Generated pages [#generated-pages]

Mintlify organizes generated pages into three sections under the tab you configured:

* **Queries**: One page per field on your `Query` root type.
* **Mutations**: One page per field on your `Mutation` root type.
* **Types**: One page per named object, input, enum, interface, union, or scalar type.

Each operation page shows the field description, arguments, return type, and links to any referenced types. Query and mutation pages also include a generated example operation, the required variables, and a sample JSON response.

Type pages render the schema definition read-only, with linked field types so readers can navigate the graph.

## Deprecations [#deprecations]

Fields and arguments that you mark with `@deprecated` in your schema display as deprecated on the generated pages. If you provide a deprecation reason, it appears next to the field.

## Update your documentation [#update-your-documentation]

Mintlify regenerates GraphQL reference pages when you run `mint dev` or when you push changes to your documentation repository. If your schema is hosted at an HTTPS URL, updates to the schema regenerate on the next build.