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.

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.

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.

{
  "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.

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:

{
  "page": 1,
  "perPage": 25,
  "total": 10,
  "extra": {},
  "data": [
  ]
}

Filtering¶

The Awaretrain API supports a wide range of filters that can be applied to most of our API endpoints. Please note that support for given operators and fields is highly specific to each endpoint. You can refer to the filter query parameter in the API reference documentation for which operators are supported for each field.

Filter operators¶

Below are the filter operators supported by our filter syntax. The documentation for each endpoint will indicate on the filter field which fields are enabled for filtering and which filter operators they support.

curl -X 'GET' \
  'https://api.awaretrain.com/public/v1/report/progress/dump.csv?completedAt=>=2024-10-01' \
  -H 'Authorization: Bearer 6652....383ef1d01'

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.

{
  "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.