API Authentication & Formatting

General Format

The Instrumental API follows a basic RESTful design. You are required to provide an authentication token with each request. All requests are returned in strict JSON format.

Authentication

User vs Project Token

The metrics endpoint uses project API tokens. All other endpoints use your user API token.

Authentication Format

Supply the project or your user token in the X-Instrumental-Token header:

"curl -H 'X-Instrumental-Token: ' "

API Responses

The response format for each endpoint is detailed on that endpoint's documentation page.

Response HTTP status codes other than 200 OK, 201 Created, 204 No Content, or 304 Not Modified should be interpreted as errors.

Time Format

All time values returned by the Instrumental API are expressed as a Unix timestamp (seconds since 1970).

Cross Domain Access via JavaScript

Access-Control-Allow-Origin: *
Access-Control-Request-Method: GET, OPTIONS
Access-Control-Allow-Headers: X-Instrumental-Token

Conditional Get

HTTP Conditional Get is partially supported. Returned JSON data will include an ETag: <content-id> header to use in an If-Not-Modified header of future requests. Last-Modified / If-Modified-Since is not currently supported.

GZIP Responses

You may specify Content-Encoding: gzip to receive GZIP compressed responses.