These conventions apply to every endpoint in this API. Individual endpoint pages describe only what is specific to that resource.
The API uses OAuth 2.0. Obtain an access token from the token endpoint using the client_credentials grant, then send it on every request in the HTTP Authorization header as a bearer token:
Authorization: Bearer <your-access-token>
The client_id is the configured OAuth client and the client_secret is the matching user's password; they may be sent in the request body or as HTTP Basic credentials. While a token is valid a licenced user session is held, so release it when you are finished by calling the logoff endpoint. A request with a missing, invalid or expired token is rejected with 401 Unauthorized; a valid token that lacks the required scope or licence is rejected with 403 Forbidden. See the token endpoint page for the supported scopes and a worked example.
When a request fails, the HTTP status code carries the outcome and the response body is a JSON:API error document: a top-level errors array. Each entry may contain a status (the HTTP status code as a string), a title (a short summary) and a detail (a human-readable explanation). Fields that are empty are omitted.
{
"errors": [
{
"status": "400",
"title": "Bad Request",
"detail": "The attribute 'DateDue' is not a valid ISO date/time."
}
]
}
The status codes you are most likely to encounter are:
| Status | Meaning | |
|---|---|---|
| 200 OK | The request succeeded. | |
| 400 Bad Request | The request body or a query parameter was malformed or failed validation. | |
| 401 Unauthorized | The bearer token is missing, invalid or expired. | |
| 403 Forbidden | Authenticated, but the token lacks the required scope or no licence is available. | |
| 404 Not Found | The endpoint or the requested resource id does not exist. | |
| 405 Method Not Allowed | The HTTP method is not supported by this endpoint. | |
| 406 Not Acceptable | The Accept header does not allow a supported media type. |
This API does not currently support the JSON:API page, sort or fields query parameters. A list (collection) endpoint returns every record that matches, and the response is not paged. To keep responses manageable, narrow the result set with filters (see Resource Filtering) rather than relying on paging, and request only the includes you need — the include parameter is not supported on list endpoints at all (it is ignored there; use the single-resource endpoint to embed related resources).