Azion API quickstart

Authenticate to the Azion API with a personal token, list your workloads, and create, read, rename, and delete a network list.

Last updated

View as Markdown Agent setup

This guide instructs you through your first requests to the Azion API.

  • Get a personal token to authenticate your requests.
  • List the workloads of your account.
  • Create a network list.
  • Read the network list and rename it.
  • Delete the network list and confirm that it is gone.

Every request goes to the base URL https://api.azion.com/v4 and carries your personal token in the Authorization header. The guide creates one object, a network list with one IP address, and links it to nothing else. You delete it in the last stage, so the account ends as it started.

The Azion CLI gets the same results from the terminal. Each stage shows the API request and the CLI command that matches it. For every endpoint, with request examples in curl and other languages, refer to the Azion API reference.

Choose API or CLI once. The prerequisites and the five stages switch to that interface.

Prerequisites

  • curl, or another HTTP client.

Get a personal token

A personal token authenticates your requests to the Azion API and the Azion CLI. To create one in Azion Console, refer to Manage personal tokens. Copy the token when Azion Console shows it, because you can only see it when you create it.

The Azion API reads the token from the Authorization header. Every request in this guide sends it in this form:

Authorization: Token [TOKEN VALUE]

The API also accepts a personal token with the Bearer scheme: Authorization: Bearer [TOKEN VALUE]. You have the header that authenticates every request in the next stages.

Save the token in the Azion CLI. Replace [TOKEN VALUE] with your token:

azion -t [TOKEN VALUE]

The CLI stores the token in its configuration folder, and later commands use it without the flag. For more information about the CLI configuration, refer to Azion CLI quickstart.

List your workloads

A list request returns the workloads of your account and confirms that the token works. The response is one page of results.

Send a GET request to the workloads endpoint. The page_size=100 parameter asks for up to 100 workloads on one page, and fields=id returns only the ID of each workload:

Shell
01curl --request GET \
02 --url 'https://api.azion.com/v4/workspace/workloads?page_size=100&fields=id' \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]'

A 200 returns the page of workloads:

JSON
01{
02 "count": 17,
03 "total_pages": 1,
04 "page": 1,
05 "page_size": 100,
06 "next": null,
07 "previous": null,
08 "results": [
09 {"id": 1234567890},
10 {"id": 1234567891},
11 {"id": 1234567892},
12 {"id": 1234567893},
13 {"id": 1234567894},
14 {"id": 1234567895},
15 {"id": 1234567896},
16 {"id": 1234567897},
17 {"id": 1234567898},
18 {"id": 1234567899},
19 {"id": 1234567900},
20 {"id": 1234567901},
21 {"id": 1234567902},
22 {"id": 1234567903},
23 {"id": 1234567904},
24 {"id": 1234567905},
25 {"id": 1234567906}
26 ]
27}

The count field holds the number of workloads in the account, and results holds the workloads of the page. A list response carries count, total_pages, page, page_size, next, previous, and results. For pagination, fields, ordering, and search, refer to Azion API.

List the workloads with the Azion CLI. The --page-size 1 flag returns one workload, and --details adds columns:

azion list workload --page-size 1 --details

The command prints one row for the workload:

Text
01ID NAME ACTIVE LAST EDITOR LAST MODIFIED
021234567890 my-blog true you@example.com 2026-01-01 12:00:00.000000 +0000 UTC

Without --page-size, azion list workload prints the ID and name of every workload in the account.

Create a network list

A network list holds a set of values of one type. The request needs a name, a type, and the items of the list. The type takes ip_cidr, asn, or countries, and items takes from 1 to 20,000 entries. This guide creates an ip_cidr list with one address from the documentation range 192.0.2.0/24.

Send a POST request to the network lists endpoint:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/network_lists \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data '{"name": "my-ip-list", "type": "ip_cidr", "items": ["192.0.2.10"]}'

A 201 returns the network list inside data, with "state": "executed":

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": 1234567890,
05 "name": "my-ip-list",
06 "type": "ip_cidr",
07 "items": ["192.0.2.10"],
08 "last_editor": "you@example.com",
09 "last_modified": "2026-01-01T12:00:00.000000Z",
10 "created_at": "2026-01-01T12:00:00.000000Z",
11 "active": true,
12 "version_id": null,
13 "version_state": null,
14 "is_versioned": false,
15 "version": null
16 }
17}

The active field defaults to true when the request omits it. Record the id. The next stages send it in the URL.

Create the network list with the Azion CLI:

azion create network-list --name my-ip-list --type ip_cidr --items 192.0.2.10

The command prints the ID of the network list:

Created Network List with ID 12345

Record the ID. The next stages pass it to --network-list-id.

Read and rename the network list

Reading the network list returns its current values. A rename changes one field and leaves the others as they are.

Send a GET request to the network list. Replace <network-list-id> with the id the create request returned:

Shell
01curl --request GET \
02 --url https://api.azion.com/v4/workspace/network_lists/<network-list-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]'

A 200 returns the network list inside data:

JSON
01{
02 "data": {
03 "id": 1234567890,
04 "name": "my-ip-list",
05 "type": "ip_cidr",
06 "items": ["192.0.2.10"],
07 "last_editor": "you@example.com",
08 "last_modified": "2026-01-01T12:00:00.000000Z",
09 "created_at": "2026-01-01T12:00:00.000000Z",
10 "active": true,
11 "version_id": null,
12 "version_state": null,
13 "is_versioned": false,
14 "version": null
15 }
16}

To rename the network list, send a PATCH request with the new name only:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/network_lists/<network-list-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data '{"name": "my-ip-list-renamed"}'

A 200 returns the network list with the new name and a new last_modified:

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": 1234567890,
05 "name": "my-ip-list-renamed",
06 "type": "ip_cidr",
07 "items": ["192.0.2.10"],
08 "last_editor": "you@example.com",
09 "last_modified": "2026-01-01T12:01:00.000000Z",
10 "created_at": "2026-01-01T12:00:00.000000Z",
11 "active": true,
12 "version_id": null,
13 "version_state": null,
14 "is_versioned": false,
15 "version": null
16 }
17}

The type and items fields keep the values of the create request.

Describe the network list. Replace <network-list-id> with the ID the create command printed:

azion describe network-list --network-list-id <network-list-id>

The command prints the name, the type, the items, and the state of the network list:

Text
01ID: 12345
02Name: my-ip-list
03Type: ip_cidr
04Items: ["192.0.2.10"]
05Last Editor: you@example.com
06Last Modified: "2026-01-01T12:00:00.000000Z"
07Active: true

Rename the network list:

azion update network-list --network-list-id <network-list-id> --name my-ip-list-renamed

The command confirms the update:

Updated Network List with ID 12345

Describe the network list again:

azion describe network-list --network-list-id <network-list-id>

The output shows the new name and a new Last Modified value, and the type and items are unchanged:

Text
01ID: 12345
02Name: my-ip-list-renamed
03Type: ip_cidr
04Items: ["192.0.2.10"]
05Last Editor: you@example.com
06Last Modified: "2026-01-01T12:01:00.000000Z"
07Active: true

Delete the network list

Deleting the network list returns the account to the state it had before you created the list.

Send a DELETE request to the network list:

Shell
01curl --request DELETE \
02 --url https://api.azion.com/v4/workspace/network_lists/<network-list-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]'

A 200 returns only the state of the operation:

{"state": "executed"}

To confirm the deletion, send the GET request that read the list again. A 404 returns the error envelope:

{"errors": [{"code": "10004", "title": "Not Found", "detail": "Not found.", "status": "404"}]}

The network list no longer exists.

Delete the network list with the Azion CLI:

azion delete network-list --network-list-id <network-list-id>

The command confirms the deletion:

Network List 12345 was successfully deleted

To confirm the deletion, describe the network list again:

azion describe network-list --network-list-id <network-list-id>

The command exits with status 1 and prints the error:

Error: Failed to describe Network List: The given ID or API's endpoint doesn't exist or isn't available. Check that the identifying information is correct

The network list no longer exists.

Next steps

Azion APIThe base URL, authentication, pagination, query parameters, and rate limits of the API.Troubleshoot Azion APICauses and fixes for the errors the API returns, by status code.Network listsThe fields, list types, and errors of a network list, and how a firewall rule matches it.Azion CLI network-listEvery flag of the commands that create, list, describe, update, and delete network lists.