Atmos Cloud API: Connectors
The Atmos Cloud API allows administrators to have programmatic control over connectors and connector zones. Click here to learn more about generating an API token.
Create a new connector
The management API allows administrators to create new connector.
A successful response will return a 201 response with the installation command.
Request Details
- Request URL: “admin-api.axissecurity.com/api/v1/connectors”
- Request Method: POST
- Request Headers: Authorization: “Bearer {API Token}”
- Request Body (JSON):
Field | Type | Description |
---|---|---|
Name | Mandatory | The connector name |
ConnectorZoneID | Optional | Connector zone ID |
NOTE
The ID parameter is NOT required when adding a new connector via the API
Request Format:
{
"name":"myconnector",
"connectorZoneID":"string",
}
Successful Response Format:
{
"id":"string",
"name":"string",
"enabled": true,
"connectorZoneID": "string",
"command": "sudo bash < <(curl -fskSL https://ops.stg.axissecurity.com/2wn5m0Cn/install)"
}
Response Codes:
Code | Description |
---|---|
201 | Connector created successfully |
400 | Bad request |
401 | Unauthorized access. Make sure the API token includes writing permissions. Click here for more information. |
409 | Conflict - Connector already exists with the same name |
500 | Internal server error |
Get the details of an existing connector
To get the details of an existing connector, the connector ID should be added to the request URL.
Request Details
- Request URL: “admin-api.axissecurity.com/api/v1/connectors/<connector ID>”
- Request Method: GET
- Request Headers: Authorization: “Bearer {API Token}”
- Request Body: empty
Successful Response Format:
{
"name":"myconnector",
"enabled": true,
"connectorZoneID":"string"
}
Response Codes:
Code | Description |
---|---|
200 | Connector information retrieved successfully |
400 | Bad request |
401 | Unauthorized access. Make sure the API token includes writing permissions. Click here for more information. |
404 | Connector not found |
500 | Internal server error |
Get a list of existing connectors
Request Details
- Request URL: “admin-api.axissecurity.com/api/v1/connectors?pageSize=100&pageNumber=1”
- Request Method: GET
- Request Headers: Authorization: “Bearer {API Token}”
- Query params:
Query Param | Description |
---|---|
PageSize | Specify the maximum number of connectors to retrieve. |
PageNumber | Page number 1 will retrieve the first connectors. |
Successful Response Format:
{
"pageNumber":1,
"pageSize":100,
"firstPage":"<URL to retrieve first page>",
"lastPage":"<URL to retrieve last page>",
"totalPages":1,
"totalRecords":50,
"nextPage":"<URL to retrieve next page>",
"previousPage":"<URL to retrieve previous page>",
"data":[
{
"name":"myconnector",
"enabled": true
"connectorZoneID":"string"
}
]
Response Codes:
Code | Description |
---|---|
200 | Connector retrieved successfully |
400 | Bad request |
401 | Unauthorized access. Make sure the API token includes writing permissions. Click here for more information. |
500 | Internal server error |
Update an existing connector
To update an existing connector, the connector's ID should be added to the request URL.
A successful response will return a 204 response with the connector details.
Request Details:
Request URL: “admin-api.axissecurity.com/api/v1/connectors/<connector ID>”
Request Method: PUT
Request Headers: Authorization: “Bearer {API Token}”
Request Format:
{
"name":"string",
"enabled": true,
"connectorZoneID": "string",
}
Successful Response Format:
{
"id":"string",
"name":"string",
"enabled": true,
"connectorZoneID": "string"
}
Response Codes:
Code | Description |
---|---|
204 | Connector updated successfully |
400 | Bad request |
401 | Unauthorized access. Make sure the API token includes writing permissions. Click here for more information. |
404 | Connector not found |
500 | Internal server error |
Delete a connector
To delete an existing connector, the connector's ID should be added to the request URL.
A successful response will return a 204 response with an empty body.
Request Details
- Request URL: “admin-api.axissecurity.com/api/v1/connectors/<connector ID>”
- Request Method: Delete
- Request Headers: Authorization: “Bearer {API Token}”
- Request Body: empty
Response Codes:
Code | Description |
---|---|
204 | Connector deleted successfully |
400 | Bad request |
401 | Unauthorized access. Make sure the API token includes writing permissions. Click here for more information. |
404 | Connector not found |
500 | Internal server error |
Get the status of an existing connector
To get a connector's status, the connector's ID should be added to the request URL.
Request Details
- Request URL: “admin-api.axissecurity.com/api/v1/connectors/<connector ID>/status”
- Request Method: GET
- Request Headers: Authorization: “Bearer {API Token}”
- Request Body: empty
Connector Statuses (For regular connector)
Pending | Connector is not ready to serve apps |
Available | Connector is available to serve apps |
Unavailable | Connector is unavailable to serve apps |
AgentOnly | Connector is available to serve only agent apps |
AgentlessOnly | Connector is available to serve only agentless apps |
Connector Statuses (For log streaming connector)
Pending | Connector is not ready to serve log streaming |
Available | Connector is available to serve log streaming |
Unavailable | Connector is unavailable to serve log streaming |
TcpOnly | Connector is available to serve only log streaming over TCP |
UdpOnly | Connector is available to serve only log streaming over UDP |
Successful Response Format:
{
"id":"string"
"status":"string"
"systemStatusCheckTime": timestamp
"version": "string",
"networkStatus":
{
"incomingKB": 789808718,
"outgoingKB": 794884322
},
"memoryStatus": {
"totalKB": 3818848,
"usedKB": 1125732,
"freeKB": 2192452,
"totalSwapKB": 0,
"usedSwapKB": 0,
"freeSwapKB": 0
},
"diskSpaceStatus": {
"totalKB": 52417516,
"usedKB": 9760332,
"freeKB": 42657184
},
"cpuStatus": {
"numOfCpus": 2,
"totalUsedPercentage": 3
},
"machineStatus": {
"hostname":"string",
"operationSystem": "string"
},
}
Response Codes:
Code | Description |
---|---|
200 | Connector status retrieved successfully |
400 | Bad request |
401 | Unauthorized access. Make sure the API token includes writing permissions. Click here for more information. |
404 | Connector not found |
500 | Internal server error |
Optimizing Connector Health Monitoring Through Connectors API
The Connectors API delivers real-time status updates. Due to network dynamics, brief disruptions in traffic (often milliseconds) are normal.
For accurate monitoring, avoid relying solely on instant checks, as the real-time nature of the API may lead to false positives. Instead, observe your connector's status over time for a more reliable assessment.
A best practice is to sample the connector's status every 30 seconds . If the connector status is not Available for more than 10 samples, trigger an alert.
Regenerate installation command for an existing connector
To regenerate a connector, the connector's ID should be added to the request URL.
Request Details
- Request URL: “admin-api.axissecurity.com/api/v1/connectors/<connector ID>/regenerate”
- Request Method: POST
- Request Headers: Authorization: “Bearer {API Token}”
- Request Body: empty
Successful Response Format:
{
"id":"string",
"command": "sudo bash < <(curl -fskSL https://ops.stg.axissecurity.com/2wn5m0Cn/install)"
}
Response Codes:
Code | Description |
---|---|
200 | Connector installation command regenerated and retrieved successfully |
400 | Bad request |
401 | Unauthorized access. Make sure the API token includes writing permissions. Click here for more information. |
404 | Connector not found |
500 | Internal server error |
Updated about 1 month ago