The Atmos Cloud API allows administrators to have programmatic control over locations. Click here to learn more about generating an API token.

📘
NOTE
This is a limited release feature. For more information contact Axis Security Support: [email protected]

Locations

Create a new location

The management API allows administrators to create new location.

Note: When creating a new location, the following sub-location is automatically created: <Location Name> - Other.
This sub-location refers to all the addresses that are not specified in the custom sub-locations). This sub-location is reserved and cannot be deleted.

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations”
Request Method: POST
Request Headers: Authorization: “Bearer {API Token}”
Request Body (JSON):

Field	Type	Description
Name	Mandatory	The location name

📘
NOTE

The ID parameter is NOT required when adding a new location via the API

Creating a new location creates a reserved sub-location "Other"

Request Format:

{
"name":"Chicago Office",
}

Successful Response Format:

{
"id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office",
"subLocations":
  [
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "name":"Chicago Office - Other"
    }
  ],
"tunnels": []
}

Response Codes:

Code	Description
201	Location created successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
409	Conflict - Location already exists with the same name
500	Internal server error

Get the details of an existing location

To get the details of an existing location, the location ID should be added to the request URL.

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>”
Request Method: GET
Request Headers: Authorization: “Bearer {API Token}”
Request Body: empty

Successful Response Format:

{
"id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office",
"subLocations":
  [
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0001"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0002"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - Guest-Wifi"
    },
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "name":"Chicago Office - Other"
    }
  ],
"tunnels":
  [
    {
      "id":"6ee0bd21-4f50-454a-9f75-82f6933d54b0",
      "name":"Chicago IPSec1"
    }
  ]
}

Response Codes:

Code	Description
200	Location information retrieved successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404	Location not found
500	Internal server error

Get a list of existing locations

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations?pageSize=100&pageNumber=1”
Request Method: GET
Request Headers: Authorization: “Bearer {API Token}”
Query params:

Query Param	Description
PageSize	Specify the maximum number of tags to retrieve.
PageNumber	Page number 1 will retrieve the first tags.

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":[
    {
    "id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
    "name":"Chicago Office",
    "subLocations":
      [
        {
          "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
          "name":"Chicago Office - VLAN0001"
        },
        {
          "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
          "name":"Chicago - VLAN0002"
        },
        {
          "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
          "name":"Chicago - Guest-Wifi"
        },
        {
          "id":"ee472846-8e02-4377-977e-292dd56913d0",
          "name":"Chicago - Other"
        }
      ],
    "tunnels":
      [
        {
          "id":"6ee0bd21-4f50-454a-9f75-82f6933d54b0",
          "name":"Chicago IPSec1"
        }
      ]
    }
  ]
}

Response Codes:

Code	Description
200	Location 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 location

To update an existing location, the location's ID should be added to the request URL.
A successful response will return a 204 response with the location details.

Request Details::
Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>”
Request Method: PUT
Request Headers: Authorization: “Bearer {API Token}”

Request Format:

{
	"name":"<new location name>",
}

Successful Response Format:

{
  "id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
  "name":"<new location name>",
  "subLocations":
  [
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0001"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0002"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - Guest-Wifi"
    },
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "name":"<new location name> - Other"
    }
  ],
  "tunnels":
  [
    {
      "id":"6ee0bd21-4f50-454a-9f75-82f6933d54b0",
      "name":"Chicago IPSec1"
    }
  ]
}

Response Codes:

Code	Description
204	Location updated successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404	Location not found
500	Internal server error

Delete a location

To delete an existing location, the location'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/locations/<location ID>”
Request Method: Delete
Request Headers: Authorization: “Bearer {API Token}”
Request Body: empty

Response Codes:

Code	Description
204	Location deleted successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
403	Operation is Forbidden. Make sure the location is not used by any tunnel or policy rule.
404	Location not found
500	Internal server error

Sub-Locations

Add a new sub-location to a location

The management API allows administrators to create new sub location.

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations/{location ID}/sublocations”
Request Method: POST
Request Headers: Authorization: “Bearer {API Token}”
Request Body (JSON):

Field	Type	Description
Name	Mandatory	The location name
IpRanges	Mandatory	List of IP addresses, IP ranges and CIDRs

📘
NOTE
The ID parameter is NOT required when adding a new sub location via the API

Request Format:

{
"name":"Chicago Office - VLAN0003",
"ipRanges": ["10.10.3.0/24"]
}

Successful Response Format:

{
"id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office - VLAN0003",
"type": "Custom",
"ipRanges": ["10.10.3.0/24"]
}

Response Codes:

Code	Description
201	Location created successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
409	Conflict - Sub-location already exists with the same name in the location
500	Internal server error

Get the details of an existing sub-location in a location

To get the details of an existing sub-location, the location ID and the sub-location ID should be added to the request URL.

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>”/sublocations/<sub-location ID>”
Request Method: GET
Request Headers: Authorization: “Bearer {API Token}”
Request Body: empty

Successful Response Format (Custom Sub-Location):

{
"id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office - VLAN0003",
"type": "Custom",
"ipRanges": ["10.10.3.0/24"]
}

Successful Response Format (Other Sub-Location):

{
"id":"ee472846-8e02-4377-977e-292dd56913d0",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office - Other",
"type": "Other",
"ipRanges": []
}

Response Codes:

Code	Description
200	Sub-Location information retrieved successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404	Sub-Location not found
500	Internal server error

List existing sub-locations in a location

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>/sublocations/?pageSize=100&pageNumber=1”
Request Method: GET
Request Headers: Authorization: “Bearer {API Token}”
Query params:

Query Param	Description
PageSize	Specify the maximum number of tags to retrieve.
PageNumber	Page number 1 will retrieve the first tags.

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":[
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - VLAN0001",
      "type": "Custom",
      "ipRanges": ["10.10.1.0/24"]
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - VLAN0002",
      "type": "Custom",
      "ipRanges": ["10.10.2.0/24"]
    },
    {
      "id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - VLAN0003",
      "type": "Custom",
      "ipRanges": ["10.10.3.0/24"]
  	},
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - Guest-Wifi",
      "type": "Custom",
      "ipRanges": ["192.168.1.0/24","192.168.12.22"]
    },
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - Other",
      "type": "Other",
      "ipRanges": []
    }
  ]
}

Response Codes:

Code	Description
200	Location 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 sub-location in a location

To update an existing location, the location's ID and the sub-location's ID should be added to the request URL.
A successful response will return a 204 response with the location details.

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>/<sub location ID>”
Request Method: POST
Request Headers: Authorization: “Bearer {API Token}”

Request Format:

{
"name":"<new sub-location name>",
"ipRanges": ["<new ip range>"]
}

Successful Response Format:

{
"id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"<new sub-location name>",
"type": "Custom",
"ipRanges": ["<new ip range>"]
}

Response Codes:

Code	Description
204	Location updated successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404	Location not found
409	Conflict - Sub-location already exists with the same name in the location
500	Internal server error

Delete an existing sub-location in a location

To delete an existing location, the location's ID should be added to the request URL.
A successful response will return a 204 response with an empty body.

Note: The auto-created sub-location, <Location Name> - Other, is reserved and cannot be deleted.

Request Details:

Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>/sublocations/<sub-location ID>”
Request Method: Delete
Request Headers: Authorization: “Bearer {API Token}”
Request Body: empty

Response Codes:

Code	Description
204	Location deleted successfully
400	Bad request
401	Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
403	Operation is Forbidden. Make sure the sub-location is not of type "Default" or "Other", and it's not used by any policy rule.
404	Location not found
500	Internal server error

Atmos Cloud API: Locations

📘
NOTE

Locations

Create a new location

📘
NOTE

Get the details of an existing location

Get a list of existing locations

Update an existing location

Delete a location

Sub-Locations

Add a new sub-location to a location

📘
NOTE

Get the details of an existing sub-location in a location

List existing sub-locations in a location

Update an existing sub-location in a location

Delete an existing sub-location in a location

📘NOTE

Locations

Create a new location

📘NOTE

Get the details of an existing location

Get a list of existing locations

Update an existing location

Delete a location

Sub-Locations

Add a new sub-location to a location

📘NOTE

Get the details of an existing sub-location in a location

List existing sub-locations in a location

Update an existing sub-location in a location

Delete an existing sub-location in a location

📘
NOTE

📘
NOTE

📘
NOTE