Introduction
Airbotics is an API-first product and exposes the majority of its functionalities through a RESTful API.
Base URL
HTTPS is enforced on every request, requests over HTTP are not supported.
The base URL for all endpoints is:
https://api.airbotics.io
Versions
The current version of the REST API is 2023-07-18. Any breaking changes will bump the version, all non-breaking changes will be added to the current version.
Versions are specified on a per-request basis by setting the air-api-version header. If no header is provided the most recent version of the API is used.
HTTP methods
Airbotics uses the following methods:
| Value | Description |
|---|---|
POST | Create a resource. |
PATCH | Configure a resource. |
GET | Retrieve a resource. |
DELETE | Delete a resource. |
Headers
The following headers may be sent with every request:
| Name | Value | Required | Description |
|---|---|---|---|
content-type | application/json | Yes | Used to specify the content type. |
air-api-key | <string> | Yes | Your API key. Used for authentication. |
air-api-version | <string> | No | The version of the API to use. |
Auth
Authentication
All requests must be authenticated by including a valid API key in the air-api-key header, like so:
curl -H "air-api-key: <aak_000...>" https://api.airbotics.io
Requests that do not include an air-api-key header, or include one that is not valid, will return a 401 - Unauthorized HTTP status code and an error.
Authorisation
Each API key has a set of permissions associated with it that determine which actions the bearer can perform in Airbotics. You can see the list of available permissions in API keys.
Requests that include valid API keys but that do not have the required permissions will return a 403 - Forbidden HTTP status code and an error.
Responses
All responses will be returned in JSON format.
Status codes
The following status codes are used:
| Value | Description |
|---|---|
200 - OK | The request succeeded. |
401 - Unauthorized | There was no valid API key provided. |
403 - Forbidden | The API key provided doesn’t have the required permission. |
404 - Not Found | The resource could not be found. |
500 - Internal Server Error | Something went wrong with the request. |
Errors
Any error will return a HTTP status code in the range 4xx or 5xx. The response body for an error will always be in the form of:
{
"error_code": "some_error_code",
"message": "A description of the error."
}
The error_code will depend on the endpoint that was called and what error occurred.