Introduction
A feature or set of features is only useful if you know how to use it. That’s why we place so much emphasis on our Support documentation at Automox, from User Guides to Knowledge Base, to our Developer Portal. Within the Developer Portal lives our API documentation. To help you harness the full power of the documentation and our API, we’ll review how to get the most out of the Developer Portal.
How is the Documentation Organized?
First thing’s first, you need to know how to get to the Developer Portal. If you’re planning to use the API frequently, just bookmark this page.
At a high level, our API documentation is laid out like this:
-
What’s New: this is where we meticulously document anything/everything new with the API and our API documentation
-
Errors: this page provides a high level overview of errors you may run into throughout your API journey
-
Getting Started: start here for some basic information about the Automox API. If you’ve never used an API before, or if you could use a refresher, pay special attention to the Newbie’s Guide
-
API Resources: here, we provide an overview of how filtering and time work in the API
-
Developer Resources: This isn’t API-related, but rather an overview of the Automox Software Development Kit (SDK) and Worklets
-
Community Resources: what the Automox Community is, and how to join. Although, if you are reading this, you’re likely already a member. If not, join us!
-
Automox Console API: this is the bread and butter of the Developer Portal. If you need to know how to do (or see) something with the API you can access through the console, start here.
-
Automox Tasks API: this section details using Vulnerability Sync via the API
How do I use the API Documentation?
First, determine what you need to do with the API, are you trying to create a new policy, tweak an existing group, or add devices? Each API section is a functional area, so first determining what you need to accomplish will reduce search time. For example, there are sections for endpoint, group, and policy management (and much more).
Functional areas are further parsed. For example, Endpoint Management is broken into a subsection for Commands, Devices, Packages, and Worklets. Within each of the subsections are the most common use cases, labelled by method (think the “verb” of the API). Below, we see an example of the structure.
Within a specific submenu, we detail what the example will accomplish in a sentence or less (e.g. Returns a specific device (server object) for the authenticated user). Every use case also includes the request details such as the request parameters (path, query, and header) as well as the Request Body Schema (in JSON) if applicable. We also include a list of potential errors you may encounter with each example call.
On the right half of the API call documentation, request and response samples are provided in PowerShell, curl, JavaScript, Python, and C#. You can toggle between each and copy the code for use in your own API calls. Below are the code samples for updating a device using the API:
Can I Submit a Call from the Developer Portal?
You can put our documentation into practice directly from the support page, with “Try it.”
Try it will allow you to make calls with the API by adding your API key as well as the parameters for the call you’re going to execute. This will send real API calls to your Automox organization, so do not use this to test your API calls. Once you hit Send, a real API call will be sent with your key, and a response will be received on the Response menu directly in the developer portal.
Conclusion
The Automox API is a powerful tool that enables rich automation and integration capabilities without using the console. Properly utilizing our API documentation will help you to unlock the power of the API, and understand how to use it properly.