CapaGraphQL 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, 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);
- 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.
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.