Home / Basics / Highnote API

Using the Highnote API

Before you start

As mentioned in Intro to GraphQL, an example ping query to the Highnote API looks like this:

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: <base64_encoded_api_key>' \
--data '{"query":"query Ping {\n  ping\n}"}' \

and will return a JSON payload with the following format:

  "data": {
    "ping": "pong"
  "extensions": {
    "requestId": "REQUEST_ID"

This guide uses this example query and its response to provide guidance on using the Highnote API.


Lines 2 and 3 of our example ping query are headers. The Highnote API requires the following headers:

  • Authorization
  • Content-Type

Content type

The Highnote API accepts and returns JSON. To call the Highnote API, you must pass a Content-Type header with the value of application/json:

'Content-Type: application/json'


Highnote API requests are authenticated using Basic auth. Using Basic auth, your API Key is provided as the username, and a password is not required. API Keys are created in the Dashboard. To obtain an API Key, see Creating and Managing API Keys.

Once you have obtained an API Key, to make a request, pass an Authorization header with your base64 encoded API key:

'Authorization': 'Basic <base64_encoded_api_key>'

Requests with missing or invalid credentials will receive a 401 Unauthorized response code.

Alternatively, you can use a client like Postman for authorization using the following steps:

  1. In Postman, create a new request.
  2. Select the Authorization section.
  3. Select Basic and pass your API key.

Request body

In our ping query example, the request body is displayed on line 4. The Highnote API accepts POST requests with JSON payloads. Requests must contain a string named query, but can also contain variables and operationName.

The query is the GraphQL operation that you are calling:

  "query": "{ ping }"

You can make multiple GraphQL requests in a single call. In this case, you would still provide a single query value with multiple calls as a string.

Request URLs

Our example ping query has a request URL on line 5. Request URLs used for the Highnote API differ depending on whether you use the live or test environments.

The live and test environment both use a graphql endpoint, with a different subdomain:

Test Environment Request URL
Live Environment Request URL

Status codes

In GraphQL, unlike REST APIs, you'll often receive a 200 OK status code even for error situations. For error handling, the response includes an errors object with detailed information for troubleshooting. For mutations, request the userError type on the union type for specific details about the failure. See error handling for more information.

There are a few non 200 status codes that Highnote’s GraphQL API returns for the following cases:

Status CodeScenario
200 OKGraphQL request was successful or validation/logic errors occurred. See error handling for more information.
400 Bad RequestGraphQL validation failed. This is generally because of malformed input or selection sets. In this case, the errors collection will be on the response body.
401 UnauthorizedReturned when invalid credentials are present.
5xxSomething is wrong on the Highnote side.

Response bodies

Read more about GraphQL responses and formats in the spec.

The response body of a query contains the data requested from the API endpoint. The Highnote API returns JSON response bodies. Response bodies contain the following:

Response BodyDescription
dataThe result of the given operation(s). This data will reflect the shape of your selection on the query.
errorsThe errors collection will be present if the GraphQL engine failed to parse or validate the given request.
extensionsThe extensions field is a map of data custom to a GraphQL implementation. For the Highnote API, the extensions field will contain a requestId for use in debugging or support scenarios.

If you need help with a response, see troubleshooting with request IDs in the Highnote API.

Provide Feedback

Was this content helpful?