Atmos Cloud API: Web Categories

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

Create a new web category

The management API allows administrators to create new web category.

Request Details

  • Request URL: “admin-api.axissecurity.com/api/v1/webcategories”
  • Request Method: POST
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body (JSON):
FieldTypeDescription
NameMandatoryThe connector name
DescriptionOptionalDescription of the web category
IncludedDomainsOrUrlsOptionalA list of FQDN/URLs and DNS wildcards to be included in the web category.
ExcludedDomainsOrUrlsOptionalA list of FQDN/URLs and DNS wildcards to be excluded from the web category.
ConnectorZoneIDOptionalThe connector zone ID

Default: Public Zone

📘

NOTE

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

Request Format:

{
  "name":"ACME Resources",
  "description": "ACME Resources.",
  "IncludedDomainsOrUrls": ["acme.com","*.ustream.tv"],
  "ExcludedDomainsOrUrls": ["acme.com/sport/*"],
  "connectorZoneID": "string"
}

Successful Response Format:

{
  "id":"string",
  "name":"ACME Resources",
  "description": "ACME Resources.",
  "includedDomainsOrUrls": ["acme.com","*.ustream.tv"],
  "excludedDomainsOrUrls": ["acme.com/sport/*"],
  "connectorZoneID": "string",
  "type": "Custom"
}

Response Codes:

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

Get the details of an existing web category

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

Request Details

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

Successful Response Format (For custom web category):

{
  "id":"string",
  "name":"ACME Resources",
  "description": "ACME Resources.",
  "includedDomainsOrUrls": ["acme.com","*.ustream.tv"],
  "excludedDomainsOrUrls": ["acme.com/sport/*"],
  "connectorZoneID": "string",
  "type": "Custom"
}

Successful Response Format (For predefined web category):

{
  "id":"string",
  "name":"Unconfirmed SPAM Sources",
  "description": "Possible sources of SPAM.",
  "includedDomainsOrUrls": [],
  "excludedDomainsOrUrls": [],
  "connectorZoneID": "string",
  "type": "Predefined"
}

Response Codes:

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

Get a list of existing web categories

Request Details

  • Request URL: “admin-api.axissecurity.com/api/v1/webcategories?pageSize=100&pageNumber=1”
  • Request Method: GET
  • Request Headers: Authorization: “Bearer {API Token}”
  • Query params:
Query ParamDescription
PageSizeSpecify the maximum number of tags to retrieve.
PageNumberPage 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":"string",
      "name":"Unconfirmed SPAM Sources",
      "description": "Possible sources of SPAM.",
      "includedDomainsOrUrls": [],
      "excludedDomainsOrUrls": [],
      "connectorZoneID": "string",
      "type": "Predefined"
    }
  ]

Response Codes:

CodeDescription
200Web categories 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 web category

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

📘

Note

For predefined web categories, which are managed by Axis, the Name and Description fields cannot be updated.

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

Request Format:

{
  "name":"ACME Resources",
  "description": "ACME Resources.",
  "includedDomainsOrUrls": ["acme.com","*.ustream.tv"],
  "excludedDomainsOrUrls": ["acme.com/sport/*"],
  "connectorZoneID": "string",
  "type": "Custom"
}

Successful Response Format:

{
  "id":"string",
  "name":"ACME Resources",
  "description": "ACME Resources.",
  "includedDomainsOrUrls": ["acme.com","*.ustream.tv"],
  "excludedDomainsOrUrls": ["acme.com/sport/*"],
  "connectorZoneID": "string",
  "type": "Custom"
}

Response Codes:

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

Delete a web category

To delete an existing web category, the web category's ID should be added to the request URL.

📘

Note

Predefined web categories are managed by Axis and cannot be deleted.

Request Details

  • Request URL: “admin-api.axissecurity.com/api/v1/webcategories/<web category ID>”
  • Request Method: Delete
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body: empty

Response Codes:

CodeDescription
204Web category deleted successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Web category not found
500Internal server error