Introduction & Guide to Automox API Standards

Here, you will find useful information to help you work with the Automox APIs A method for programmatic platform access..

If you're new to working with APIs, please see our Newbie's Guide to Getting Started with Automox API that explains how to get started with our API using Postman.

Automox API Standards

The Automox API is a powerful interface that allows you to integrate Automox reporting data into your applications and control your devices A subset of Assets, a general term denoting anything that runs the Automox Agent and is registered with the system., policies Represents a set of logic statements that define the desired target state of a device, the allowed remediation schedule, and configuration parameters around how that remediation should take place., and configurations. All endpoints are only accessible via HTTPS and are located at https://console.automox.com/api/....

Pagination

For API endpoints that list results (like events and servers A subset of Assets. Denotes any Device or Asset that supports multiple clients for designated computing tasks.) there is a limit on the number of results returned per request. This is done for performance reasons. These endpoints have two parameters you should use to navigate your data:

Limit

A limit on the number of results to be returned, between 1 and 500 with a default of 500. A validation error will be returned if you attempt a request with a limit value that is outside this range.

Page

The page of results you wish to be returned with page numbers starting at 0.

Examples

For example, if you have 145 servers and wish to fetch them in chunks of 50 you would have to make three requests:

/api/servers?o=<org_id>&limit=50&page=0
/api/servers?o=<org_id>&limit=50&page=1
/api/servers?o=<org_id>&limit=50&page=2

Since the Automox API does not return pagination information with all of its endpoints, you may need to compare the number of returned results to the limit requested. When the limit and number of results returned are equal, you may need to make an additional request with a higher page number to ensure you have all of your data.

See our Community page example: Example API call with pagination limits

Automox Terminology

Note that servers, devices, and endpoints Endpoint is used interchangably with Device and Servers, to denote a device running the Automox Agent and registered with the system. We refer to endpoints as devices within the Automox product. Device is the preferred terminology. Endpoint is also used to describe functionality exposed via the Automox Public API. are currently used interchangeably.

Authentication

The API key is a unique identifier that authenticates requests. You can find your API key from the console.

Go to Settings → Keys to find and manage your API key. Refer to Managing Keys in our documentation.

See also Newbie's Guide to Getting Started with Automox API.

Default Group ID

You can determine an organization's A subset of an account. An Automox customer account can be tied to multiple organizations, and users can be invited to, and access multiple organizations. An organization contains users, devices, and policies. Default Group Represents a concrete grouping of devices. Every device must be assigned to a single group. A group contains settings for the following: - refresh interval - OS auto-update ID by listing the groups and looking for the group with a blank name: "name": ""

Patch Classification Category ID Mapping

The table below lists the values for patch_classification_category_id. This parameter is returned with queries to the GET /orgs/packages and GET /servers/packages endpoints. This table shows what the values for this parameter denote.

Rate Limiting

Automox makes use of a number of rate limiting configurations to safeguard our APIs against bursts of traffic to maximize the stability and reliability of the platform.

How rate limits are applied

Automox associates all authenticated API requests to the user's Represents a set of login credentials and contact information for an external user. A user is associated with an account. Once created a user should get privileges granted to act: - at an account level - at an organization level account The account acts as the main object to store and manage all of the organizations under the account, including specifying the enabled modules, features, billing settings, etc for each organization. - Organization - Users - Privileges User / Role / Organization - Billing & contact information - Card details - Payment mode and not to individual API keys. For most APIs, Automox allows 100 authenticated requests per second and 15 unauthenticated requests per second. For unauthenticated requests, the rate limits are tracked per client IP address and are not associated to a user account.

Specific endpoints may have different limits depending on how resource intensive the requests are. For example, /servers/batch has a limit of 5 requests per minute.

How to handle rate limiting gracefully

All responses from the Automox API will include rate limit status headers. For example:

curl -I https://console.automox.com/api/users/self
HTTP/2 200
date: Mon, 28 Mar 2022 15:52:47 GMT
content-type: application/json
x-ratelimit-limit: 100
x-ratelimit-remaining: 99
x-ratelimit-reset: 1648484793
x-request-id: 43ef3dc6c5b9c3a869eb354036f32f23

If you exceed the rate limit, then a 429 error response is returned:

curl -I https://console.automox.com/api/users/self
HTTP/2 429
date: Mon, 28 Mar 2022 15:52:47 GMT
content-type: application/json
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: 1648484793
retry-after: 1
x-request-id: 43ef3dc6c5b9c3a869eb354036f32f23

A basic approach to gracefully handling rate limiting is to check for 429 status codes and build in a retry mechanism. The retry mechanism should ideally have an exponential back-off as well as some jitter built in to safeguard against a thundering herd situation.