Introduction & Guide to Automox API Standards

Welcome to the Automox Developer Portal!

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

If you're new to working with APIs, please see our Newbie's Guide to the 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
Copied
/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 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 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/{id}/packages and GET /servers/{id}/packages endpoints. This table shows what the values for this parameter denote.

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

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 unauthentciated 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
Copied
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
HeaderDescrption
x-ratelimit-limitThe maximum number of requests permitted in a given time window.
x-ratelimit-remainingThe number of requests remaining before the rate limiter begins blocking requests.
x-ratelimit-resetThe time at which the current rate limit window resets as a UTC epoch timestamp.
retry-afterThe 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
Copied
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 backoff as well as some jitter built in to safeguard against a thundering herd situation.