Using the Highnote API

This guide uses a simple cURL command to demonstrate how to query the Highnote API. It sends a ping query to the Highnote API where \ represents a newline:

Copy code snippet

You can also use the short single-dash options:

Copy code snippet

If successful, it returns the following JSON payload:

Copy code snippet

The Highnote API requires the following headers:

• Content-Type
• Authorization

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

Copy code snippet

Highnote API requests are authenticated with Basic auth. Basic auth sets your API Key as the username and does not require a password.

1. Create an API key in the Dashboard. See Creating and Managing API Keys.

2. Convert your API key, which is in ASCII format, to base64:

   Copy code snippet
   

3. Make a request by passing the Authorization header with the Basic scheme and your base64 encoded API key:

   Copy code snippet
   

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

The Highnote API accepts POST requests with JSON payloads. Requests must contain a string named query, but can also contain variables and operationName.

In our ping query example, the request body is on line 4 -- Ping is the operation name and ping is the actual GraphQL field being queried:

Copy code snippet

Our cURL command is making the following GraphQL call:

To make a more complex call using variables, try requesting a list of your first 10 API keys:

Copy code snippet

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.

Note: To output the response in pretty colorized JSON format, you can install jq and edit the URL in your cURL command as follows: https://api.us.test.highnote.com/graphql | jq -C '.'

Unlike REST, GraphQL often returns a 200 OK status code even when there are errors. 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:

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. A response body contains the following:

For help, see Troubleshooting with request ID.