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

📘

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:

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:

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:

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:

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:

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:

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)

Connector Statuses (For log streaming connector)

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:

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: