# GraphQL Explorer

Source: https://capacms.com/docs/api/graphql-explorer

Write and run GraphQL queries in the Capa admin, as one of your API keys, and copy them into your site.

The GraphQL Explorer is in the Capa admin under **Developers > GraphQL**. You pick an API key, write a query with autocomplete, run it, and copy it out as cURL, fetch or a URL. Admins and developers on the project can open it.

Everything here is a real request to [`/api/graphql`](https://capacms.com/docs/api/graphql), sent from your browser with the key, version and headers you choose, as your site would send it.

## Runs as a key

The key picker lists your project's active API keys. The line under it says what a run will see:

> Runs as Website build, a production key with 1 scope. Published entries only. It can read 1 model.

* **A production key** reads published entries only. **Any other environment** includes drafts.
* **A legacy key** (`pk_`, `sk_`) is ready to use as listed.
* **A `cap_` key** asks you to paste its secret, because Capa stores only a hash of it. The pasted secret stays in the page's memory and is gone when you close the tab.

The editor, the autocomplete and the docs know exactly the models and fields the chosen key can read, and nothing else. Switch keys to see what a different key sees.

## Write and run

The query editor completes fields and arguments as you type, marks problems as you go, and shows the docs for the name at the cursor. Below it are the **Variables** and **Headers** panes. Press `⌘ Enter` (`Ctrl Enter` on Windows) to run.

The toolbar picks the **Version**, sent as `Capa-Version`, from the versions the API serves, and the method, **POST** or **GET**. A GET whose URL would be too long goes as a POST, as the SDK does, and the response says which method went.

Each tab holds one document. Open more tabs to keep several queries side by side.

## The side panel

| Tab         | What it does                                                                                                                |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Builder** | Pick a model, a list or a single entry, then tick fields. Set `first`, filters and sorts. The query text is written for you |
| **Docs**    | Every type and field the key can read, with a search. Each type has an example query you can run in a new tab               |
| **History** | Your saved operations, and your last 20 runs in this project with what each read and how it went. Open one to run it again  |

## The response

The response pane shows the status, the time and the size, then:

* the errors, each with its hint, whatever the status;
* what the query cost (see [Limits](https://capacms.com/docs/api/graphql#limits));
* the REST request each root field ran as on `/api/entries`;
* the cache headers.

A refused query answers `200` with `errors` and no `data`, as it does for your site. The Explorer reads the errors, so a refusal shows as a failure.

The **REST** popover shows the same read as `/api/entries` URLs before you run anything.

## Save and share

**Save** keeps the open tab under a name, up to 100 per project. Saved operations, history and open tabs are kept in this browser, per project. They hold your query, variables and headers text, never a key's secret and never a response.

**Copy share link** makes a link that opens the Explorer on the same query, variables and operation name. It never carries a key or your headers: whoever opens it runs it as a key of their own.

## Copy into your site

The **Copy** menu writes code that reads the API's address from `CAPA_API_URL` and the key from `CAPA_KEY`. The key itself is never copied.

| Item                   | What you get                                                                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Copy environment lines | the lines that set `CAPA_API_URL` and `CAPA_KEY`                                                                                         |
| Copy as cURL           | the request as a shell command                                                                                                           |
| Copy as fetch          | the request as a `fetch` call                                                                                                            |
| Copy GET URL           | the query as a GET URL, which the CDN can cache                                                                                          |
| Copy persisted GET URL | a GET URL that sends only the query's hash. The Explorer registers the query first, with a development key, so the URL answers with data |
| Download SDL           | the schema the key can read, as SDL                                                                                                      |

A persisted query belongs to the project, not the key that registered it, so the URL works with your site's production key. See [Persisted queries](https://capacms.com/docs/api/graphql#persisted-queries).

## Shortcuts

Press `?` outside the editor for the full list. The ones you will use most:

| Keys           | Does                         |
| -------------- | ---------------------------- |
| `⌘ Enter`      | run the query                |
| `Ctrl Shift P` | prettify                     |
| `⌘ S`          | save the operation           |
| `Ctrl Space`   | suggest fields and arguments |
| `/`            | search the docs              |

On Windows and Linux, `⌘` is `Ctrl`.