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):
FieldTypeDescription
NameMandatoryThe connector name
ConnectorZoneIDOptionalConnector 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:

CodeDescription
201Connector created successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
409Conflict - Connector already exists with the same name
500Internal 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:

CodeDescription
200Connector information retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Connector not found
500Internal 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 ParamDescription
PageSizeSpecify the maximum number of connectors to retrieve.
PageNumberPage 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:

CodeDescription
200Connector retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
500Internal 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:

CodeDescription
204Connector updated successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Connector not found
500Internal 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:

CodeDescription
204Connector deleted successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Connector not found
500Internal 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)

PendingConnector is not ready to serve apps
AvailableConnector is available to serve apps
UnavailableConnector is unavailable to serve apps
AgentOnlyConnector is available to serve only agent apps
AgentlessOnlyConnector is available to serve only agentless apps

Connector Statuses (For log streaming connector)

PendingConnector is not ready to serve log streaming
AvailableConnector is available to serve log streaming
UnavailableConnector is unavailable to serve log streaming
TcpOnlyConnector is available to serve only log streaming over TCP
UdpOnlyConnector is available to serve only log streaming over UDP

Successful Response Format:

{
"id":"string",
"status": "string"
}

Response Codes:

CodeDescription
200Connector status retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Connector not found
500Internal 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:

CodeDescription
200Connector installation command regenerated and retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Connector not found
500Internal server error