APIs

Last updated 13 days ago

The HyperTrack APIs is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

Authentication

Authenticate your account by including your secret key in API requests. You can manage your API keys on the HyperTrack Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

HyperTrack uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • Codes in the 2xxrange indicate success

  • Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted); some of these errors could be handled programmatically

  • Codes in the 5xxrange indicate an error with HyperTrack's servers (these are rare)

HTTP status code summary

Status

Description

200 - OK

Everything worked as expected

400 - Bad Request

The request was unacceptable, often due to missing a required parameter

401 - Unauthorized

No valid API key provided

402 - Request Failed

The parameters were valid but the request failed

404 - Not Found

The requested resource doesn't exist

409 - Conflict

The request conflicts with another request (perhaps due to using the same idempotent key)

429 - Too Many Requests

Too many requests hit the API too quickly; we recommend an exponential backoff of your requests

500, 502, 503, 504 - Server Errors

Something went wrong on HyperTrack's end; these are rare