Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

...

The GraphQL endpoint

...

About the Scope GraphQL Explorer

...

Using GraphiQL

...

Requesting support

...

Troubleshooting errors

...

Table of Contents

Recommended HTTP Clients & GraphQL IDEs

...

GraphQL IDEs

...

...

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

The endpoint remains If you are not a super admin, the endpoint can remain constant no matter what operation you perform. If you are a super admin, you must include the company permalink name in the URL.

About the Scope GraphQL Explorer

Scope GraphQL Explorer is an instance of GraphiQL (a GraphQL IDE) that is available in-browser at In this example, the company permalink name is scope

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

...

?permalink=scope

Note that users other than super/company admins can now use GraphQL to run queries.

Using GraphiQL

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

Configuring GraphiQL

...

  1. Getting an OAuth token can be done thru CMS

    1. Log in to CMS as your authorized user and open the Developers Console (F12 usually does this)

    2. Open the Application tab and copy the Auth token from Cookies

      Image Added

  2. Ensure the authenticated user has the Access Control Rights required by the query to be executed (See Authorization Errors & Reporting Admins).

  3. Launch GraphiQL.

  4. In the upper-right corner of GraphiQL, click Edit HTTP Headers.

  5. If you don’t already have GraphiQL setup with Headers, do the following;

    1. In the upper-right corner of the modal dialog, click + Add Header.

    2. In the Key field, enter Authorization. In the Value field, enter Token token=<token>, where <token> is your generated OAuth token.

      Image Modified
    3. Click

...

    1. Save to save the token.

    2. If you hold an analyst license, you can obtain your token thru your user profile on CMS

      1. Login and navigate to Edit Profile

      2. The API Key on the bottom right is your token

    3. In the upper-right corner of the modal dialog, click + Add Header.

    4. In the Key field, enter PrivateAccessCode. In the Value field, enter Token token=YWRtaW4xMjU6c2VjcmV0MTI1, where YWRtaW4xMjU6c2VjcmV0MTI1 is a literal value (used to

...

    1. enable early access to

...

    1. the Scope GraphQL API).

      Image Modified
    2. Click

...

    1. Save to save the token

...

    1. .

    2. To return to the editor, click outside of the Edit HTTP Headers modal.

  1. In the GraphQL Endpoint field,

...

  1. enter the following (include company permalink if necessary)

    1. Image Added
  2. In the Method dropdown menu, select 

...

  1. POST

...

  1. .

...

You can test your access by querying yourself:

Code Block
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.

...

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

Some example calls include variables written Variables can be injected into queries and mutations like this:

Code Block
query($number_of_repos:Int$my_custom_node_id_var:String!){
  viewer {
    name
     repositories(last: $number_of_reposnode(id: $my_custom_node_id_var:String) {
       nodes {
         name
       }
     }__typename
   }
}
variables {
   "number_of_reposmy_custom_node_id_var:String": 3"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:

Code Block
{
   "number_of_reposmy_custom_node_id_var:String": 3
}

Requesting support

For questions, bug reports, and discussions about Scope Apps, OAuth Apps, and API development, email api.support@scopear.com. This email group is moderated and maintained by Scope staff, but questions posted to the group are not guaranteed to receive a reply from Scope staff.

Consider reaching out to your Scope representative for:

...

guaranteed response from Scope staff

...

support requests involving sensitive data or private concerns

...

feature requests

...

"6_kJ_XUGDxMDWkwq2bAK-dKknUQ7GPpsI2yfj691f9L2n6N4sAhdU4urWqNG1RVX"
}

Troubleshooting errors

Because GraphQL is introspective, the Explorer supports:

...

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

Authorization errors

Authorization errors indicate that the current user does not have sufficient privileges to access a requested node (or nodes).

Unauthorized nodes that are part of many-to-one relationships (aka “Connections”) are automatically pruned from the response without triggering an error, whereas unauthorized nodes that belong to one-to-one relationships trigger an error.

If you receive an authorization error, contact your internal administrator to request that additional privileges be added to your user account (see “Managing Access Control Rights”).

...

By way of example, the following query will trigger the following authorization error response when the user executing the query isn’t authorized to read the node identified by id YQLXlUig57gDr1aAak2ojlH98qqDttCUIUwR_Y-MPJRWrdX0sgvvjiOj6fXusYeG:

Code Block
query {
  node(id:"YQLXlUig57gDr1aAak2ojlH98qqDttCUIUwR_Y-MPJRWrdX0sgvvjiOj6fXusYeG") {
   ... on ScenarioSession {
      createdAt
    }
  }
}
Code Block
{
  "data": {
    "node": null
  },
  "errors": [
    {
      "message": "Not authorized to read object",
      "locations": [
        {
          "line": 23,
          "column": 3
        }
      ],
      "path": [
        "node"
      ]
    }
  ]
}

But, the node in the previous example will be silently removed from the response to the following query without triggering an error:

Code Block
query {
  viewer {
    organization {
      scenarios {
        nodes {
          sessions {
            nodes {
              id
            }
          }
        }
      }
    }
  }
}  

Unexpected errors

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 to support:

Code Block
{
  "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 additional 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.To obtain

Refreshing an OAuth token

...

Use your favorite HTTP client to sign in:

Code Block
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):

Code Block
{
  "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

...

Scope OAuth tokens currently expire after 30 days (or “sign-out”, whichever is earlier). Repeat steps 1-5 to obtain a fresh token thru the developers console.