Skip to content

Getting started

The Awaretrain API is a REST API for interacting with the Awaretrain platform, primarily using JSON data in requests and responses. Each API resource has its own URL (called an endpoint) and depending on the request method ( e.g. GET, POST, PUT etc.) an action is performed.

On this page, you will find the necessary information on how to get started with the Awaretrain API.

Versioning

The API is versioned, in which we take great care to ensure changes to the API are backwards compatible and will not break any existing integrations.

The version is denoted in the URL: https://api.awaretrain.com/public/<version>.

An OpenAPI specification is available for each version.

Version OpenAPI specification Release date
v1 HTML, JSON, YAML -

Authentication

All endpoints of the API require authentication and therefore a valid API key. See API keys on how to create and manage API keys for your organisation.

Each request is required to contain an Authorization header with its value set to Bearer <api token here>.

curl -X 'GET' \
  'https://api.awaretrain.com/public/v1/users' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer 6652....383ef1d01'

Scopes

Every API key has one or more scopes assigned, granting access to specific API resources and operations. See scopes for an overview of all available scopes.

Warning

Make sure to keep the assigned scopes to an absolute minimum of what is required for its intended purpose and set an expiry date of around a year. This minimises potential damage in case the API key falls in the hands of attackers.

Rate limits

Rate limits are enforced on the Awaretrain API to prevent abuse and keep the systems operational. These limits are enforced per API key, not per IP address.

In case you exceed the allowed number of requests, an HTTP 429 Too Many Requests response will be returned with a Retry-After header containing the number of seconds after which to try again.

Currently, we allow up to 1 request per second (60 / minute) using a sliding window approach, but this may change in the future.

Handling errors

In case of an error, a JSON response is returned that is formatted according to RFC7807.

Though the status code should be the primary indication of what went wrong, the response can contain useful details as to what caused the problem.

Example response
{
  "type": "https://api.awaretrain.com/errors/6b7454c2-78ce-4623-9301-f62dd3f27d3e",
  "title": "Example error",
  "detail": "This is an example error.",
  "status": 403
}

Pagination

Some endpoints return paginated data. Those endpoints accept a few query parameters to control, for example, what page and how many results are returned.

Parameter Type Default Description
page integer 1 Page number (starting from 1).
perPage integer 25 The number of results returned per page. The maximum value is 1000.
curl -X 'GET' \
  'https://api.awaretrain.com/public/v1/users?page=1&perPage=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 6652....383ef1d01'

The response will contain the following properties:

Property Type Optional Description
page integer Current page number.
perPage integer Displayed number of items per page.
total integer Total number of items (over all pages).
extra object Optional object containing extra data.
data array Array of objects containing the page data.
Example response
{
  "page": 1,
  "perPage": 25,
  "total": 10,
  "extra": {},
  "data": [
  ]
}

Common problems

HTTP 400 Bad Request response

This response indicates that there is something wrong with the request.

  • Check if the response contains a message that might help you locate the problem.
  • In the case of query parameters in the URL, make sure they have correct values and its values are encoded properly.
  • In case of a request body, make sure the request data is valid JSON and the request has the Content-Type: application/json header set.
  • In case of a multipart request. Make sure the Content-Type: multipart/form-data header is set and contains a valid boundary. Also make sure that the contents of each part have the correct Content-Type header.

HTTP 401 Unauthorized response

This response indicates that the request is missing the Authorization header or that its value is not formatted correctly.

  • Check that the Authorization header value starts with Bearer

See authentication for more information.

HTTP 403 Forbidden response

This response can indicate several things:

  • Your IP address is not whitelisted
  • The API key used in the request has expired
  • The API key used in the request is not valid
  • The API key used in the request does not have the required scopes to access the requested resource

If the API key is valid, has not expired and has the correct scopes; make sure the Authorization header is sent correctly. See authentication for more details.

HTTP 422 Unprocessable Entity response

This response indicates that the request contents did not pass validation.

In most cases, the response should contain a list of violations that were found during validation.

Example response
{
  "type": "https://api.awaretrain.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "violations": [
    {
      "propertyPath": "name",
      "title": "Name cannot be blank.",
      "template": "Name cannot be blank.",
      "parameters": []
    }
  ]
}

HTTP 429 Too Many Requests response

You have made too many requests in a short period of time. Please see rate limits for more information about how we apply rate-limiting.