Introduction & Guide to Automox API Standards

Welcome to the Automox Developer Documentation!

Here, you will find useful information to help you work with the Automox APIs.

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, policies, 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) 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:

Copy 
/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 API 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 are currently used interchangeably.

Keep API Keys Secure!

Depending on your role, your API key may be able to modify users, devices, and policies. API keys should be kept secure and not shared to prevent unforeseen changes or potential security issues. Never email or write down your API key.

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 Default Group 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.

ID Name
1 Application
2 Connectors
3 Critical Updates
4 Definition Updates
5 Developer Kits
6 Feature Packs
7 Guidance
8 Security Updates
9 Service Packs
10 Tools
11 Update Rollups
12 Updates
13 Upgrades

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 account 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:

Copy 
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
Header Description
x-ratelimit-limit The maximum number of requests permitted in a given time window.
x-ratelimit-remaining The number of requests remaining before the rate limiter begins blocking requests.
x-ratelimit-reset The time at which the current rate limit window resets as a UTC epoch timestamp.
retry-after The number of seconds the user agent should wait before making a follow-up request.

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

Copy 
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.