Introduction

What is GraphQL?

GraphQL is an API query language, originally created by Facebook as an alternative to REST. If you're new to GraphQL, the best place to start is the official documentation.

How do I make a query?

It depends on what kind of environment you are making the query from. Check out this list of GraphQL client libraries to see some tools already available in multiple languages, including C#/.NET, Go, Java, JavaScript, and Python. These client libraries can make writing queries easier and may provide built-in support for features like caching.

However, GraphQL is just a query language served over HTTP, so you can also make a request without using any GraphQL-specific libraries or packages. Here's an example using cURL (you'd need to replace the API key and test ID to try it yourself):

curl 'https://app.codesignal.com/graphql' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer MY_API_KEY' --data-binary '{"query":"{ companyTest(id: \"MY_TEST_ID\") { title } }"}'

This returns data that looks like this:

{"data":{"companyTest":{"title":"My Company Test"}}}

How can I test my queries during development?

Although you'll likely want to consume our API programmatically using a library in your language of choice, as you work on your integration, you may find it helpful to have a readily available UI for writing and running queries. For that, try out our GraphQL Playground, which is connected to our real API and provides a helpful interface that will make it easier for you to quickly spot and resolve syntax or schema issues in your queries.

To use the GraphQL Playground, you need to first generate an API key (see below) and then provide that in the HTTP Headers section in the bottom-left:

{ "Authorization": "Bearer YOUR_API_KEY" }

As long as you provide a valid API key, you can write and execute queries here and see the result immediately. If there are errors in your query syntax, red highlighting will appear on the left side of lines with errors, and you can hover over the query to learn more about what is wrong.

You can also explore the GraphQL schema and documentation live from the GraphQL Playground, as well as copy your query to a cURL command like the one from the previous section.

What kinds of queries can I make?

Take a look at our schema. All read-only queries can be found under RootQuery, and all mutations can be found under RootMutation.

Here's an example of a query that you could run to fetch the answers from a company test session:

query AnswerQuery {
  companyTestSession(id: "MY_TEST_SESSION_ID") {
    id
    result {
      taskResults {
        solution {
          id
          ... on CodingSolution {
            sources {
              source
              language
              path
            }
          }
          ... on FreeFormSolution {
            freeTextAnswer: answer
          }
          ... on QuizSolution {
            quizAnswer: answer
          }
        }
      }
    }
  }
}

In this case, we're using the graph-based nature of the API to make the following request: Look up a given company test session. For that session, return the ID and the result. For the result, return the result for each task, including the solution. For each solution, return the ID of the solution and more information depending on what kind of solution it is (using inline fragment syntax to query different fields based on type, and aliases to make sure the "answer" field does not conflict, since it has different types for free-text and quiz answers.

That might return something that looks like this:

{
  "data": {
    "companyTestSession": {
      "id": "MY_TEST_SESSION_ID",
      "result": {
        "taskResults": [
          {
            "solution": {
              "id": "MY_CODING_SOLUTION_ID",
              "sources": [
                {
                  "source": "console.log('hello world');",
                  "language": "js",
                  "path": "main.js"
                }
              ]
            },
          },
          {
            "solution": {
              "id": "MY_FREE_TEXT_SOLUTION_ID",
              "freeTextAnswer": "Hello, world!",
            },
          },
          {
            "solution": {
              "id": "MY_QUIZ_SOLUTION_ID",
              "quizAnswer": [
                "All of the above"
              ]
            },
          }
        ]
      }
    }
  }
}

Authentication

How do I get an API key?

If you're not already using CodeSignal, start a conversation with us by requesting a demo.

If you're an existing customer, reach out to support@codesignal.com to learn more.

How do I make an authenticated request?

When making a GraphQL request, pass an "Authorization" header with a value of "Bearer YOUR_API_KEY" with the HTTP request. You can see a simple example of this in the cURL command above.

Some queries or mutations may require specific permissions to be assigned to your API key. If you receive Access Denied errors that you believe to be in error, please contact support.