Exploring the Graph

You can run queries on real Scope data using any HTTP compliant client (HTTP Client) or GraphQL integrated development environment (GraphQL IDE). GraphQL IDEs are typically easier to work with because they include docs, syntax highlighting, and validation errors.

If you need help, see Requesting support.

In this article

Recommended HTTP Clients & GraphQL IDEs

HTTP Clients

GraphQL IDEs

The GraphQL endpoint

The REST API has numerous endpoints; the GraphQL API has a single endpoint:

https://cms.scopear.com/api/v3/graphql

The endpoint remains constant no matter what operation you perform.

About the Scope GraphQL Explorer

Scope GraphQL Explorer is an instance of GraphiQL (a GraphQL IDE) that is available in-browser at https://cms.scopear.com/api/v3/graphql/explorer.

Note: The Scope GraphQL Explorer has been temporarily disabled, but you can still explore the graph using a local GraphiQL client, or any other similar client (see below).

Using GraphiQL

To use the GraphiQL app, download and install it from https://www.electronjs.org/apps/graphiql.

Configuring GraphiQL

Get an OAuth token.
Launch GraphiQL.
In the upper-right corner of GraphiQL, click Edit HTTP Headers.
In the upper-right corner of the modal dialog, click + Add Header.
In the Key field, enter Authorization. In the Value field, enter Token token=<token>, where <token> is your generated OAuth token.
Click the checkmark to the right of the token to save it.
In the upper-right corner of the modal dialog, click + Add Header.
In the Key field, enter PrivateAccessCode. In the Value field, enter Token token=YWRtaW4xMjU6c2VjcmV0MTI1, where YWRtaW4xMjU6c2VjcmV0MTI1 is a literal value (used to enable early access to the Scope GraphQL API).
Click the checkmark to the right of the token to save it.
To return to the editor, click outside of the Edit HTTP Headers modal.
In the GraphQL Endpoint field, enter https://cms.scopear.com/api/v3/graphql.
In the Method dropdown menu, select POST.

You can test your access by querying yourself:

query {
  viewer {
    name
  }
}

If everything worked correctly, this will display the name of the currently authenticated user. You're all set to start making queries.

Accessing the sidebar docs

All types in a GraphQL schema include a description field compiled into documentation. The collapsible Docs pane on the right side of the Explorer page allows you to browse documentation about the type system. The docs are automatically updated and will drop deprecated fields.

The Docs sidebar contains the same content that is automatically generated from the schema under "Reference," though it is formatted differently in places.

Using the variable pane

Variables can be injected into queries and mutations like this:

query($my_custom_node_id_var:String!){
  node(id: $my_custom_node_id_var:String) {
    __typename
   }
}
variables {
   "my_custom_node_id_var:String": "6_kJ_XUGDxMDWkwq2bAK-dKknUQ7GPpsI2yfj691f9L2n6N4sAhdU4urWqNG1RVX"
}

This is the correct format to submit the call via a cURL POST (as long as you escape newlines).

If you want to run the call in the Explorer, enter the query segment in the main pane and the variables in the Query Variables pane below it. Omit the word variables from the Explorer:

{
   "my_custom_node_id_var:String": "6_kJ_XUGDxMDWkwq2bAK-dKknUQ7GPpsI2yfj691f9L2n6N4sAhdU4urWqNG1RVX"
}

Troubleshooting errors

Because GraphQL is introspective, the Explorer supports:

Intelligent typeaheads aware of the current schema
Validation error previews as you type

If you enter a query that is not well-formed or does not pass schema validation, a popup warns you of an error. If you run the query, the error returns in the response pane.

A GraphQL response contains several keys: a data hash and an errors array.

{
  "data": null,
  "errors": [
    {
      "message": "Objects must have selections (field 'nodes' returns User but has no selections)",
      "locations": [
        {
          "line": 5,
          "column": 8
        }
      ]
    }
  ]
}

It's possible you might run into an unexpected error that is not related to the schema. If this happens, the message will include a reference code you can use when reporting the issue:

{
  "data": null,
  "errors": [
    {
      "message": "Something went wrong while executing your query. This is most likely a Scope bug. Please include \"7571:3FF6:552G94B:69F45B7:5913BBEQ\" when reporting this issue."
    }
  ]
}

Note: Scope recommends checking for errors before using data in a production environment. In GraphQL, failure is not total: portions of GraphQL queries may succeed while others fail.

If you need help, see Requesting support.

OAuth token

You must obtain a valid OAuth token before attempting to execute queries against, or explore the schema of, the Scope API.

There are two kinds of OAuth tokens:

“Permanent” API tokens that never expire.
“Temporary” Session based tokens that expire after 30 days (or “sign-out”, whichever is earlier).

To obtain a permanent API token:

Contact api.support@scopear.com and request that a Scope Admin create and enable an API token for your organization.

To obtain a temporary session token:

Use your favorite HTTP client to sign in:

curl --request POST \
  --url https://cms.scopear.com/api/v2/users/sign_in.json \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'user[username]=YOUR_EMAIL' \
  --data 'user[password]=YOUR_PASSWORD'

Parse the response as JSON and extract the value for the auth_token key (e.g. the following response should yield the following token):

{
  "id": 1,
  "email": "support@scopear.com",
  "name": "Support Account",
  "permalink": "supportscopearcom",
  "username": "support@scopear.com",
  "guest": false,
  "auth_token": "eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InVzZXJfaWQiOjEsImRldmljZV9pZCI6MX0sImV4cCI6MTYwODI0NDA3MSwianRpIjoiOGY3ODg1NTg2Y2Y4YTdiNjQ1MWIwZTcxMzFhODY1MDE2MmQwZWZhZjc3MTgwYTNhZmU5OTk2N2Y4OTZhNzlhOCIsImlhdCI6MTYwNTY1MjA3MX0.Z4hFOmLlUPolvW3u-2Ssn7LWX_c2y95a1fhID3QJuCg",
  ...

=> eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InVzZXJfaWQiOjEsImRldmljZV9pZCI6MX0sImV4cCI6MTYwODI0NDA3MSwianRpIjoiOGY3ODg1NTg2Y2Y4YTdiNjQ1MWIwZTcxMzFhODY1MDE2MmQwZWZhZjc3MTgwYTNhZmU5OTk2N2Y4OTZhNzlhOCIsImlhdCI6MTYwNTY1MjA3MX0.Z4hFOmLlUPolvW3u-2Ssn7LWX_c2y95a1fhID3QJuCg

You may now use this token wherever an OAuth token is required (until it expires).