# Azion API quickstart 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](/en/documentation/platform/firewall/network-shield/network-lists/) 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](https://api.azion.com/). --- Choose API or CLI once. The prerequisites and the five stages switch to that interface. ## Prerequisites - An Azion account. To create one, refer to [Create an account](/en/documentation/fundamentals/creating-account/). **API** - `curl`, or another HTTP client. **CLI** - The [Azion CLI](/en/documentation/devtools/cli/) installed. To install it, refer to [Azion CLI quickstart](/en/documentation/devtools/cli/quickstart/). --- ## Get a personal token A [personal token](/en/documentation/fundamentals/personal-tokens/) authenticates your requests to the Azion API and the Azion CLI. To create one in Azion Console, refer to [Manage personal tokens](/en/documentation/guides/platform/account-and-billing/personal-tokens/). Copy the token when Azion Console shows it, because you can only see it when you create it. **API** The Azion API reads the token from the `Authorization` header. Every request in this guide sends it in this form: ```text 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. **CLI** Save the token in the Azion CLI. Replace `[TOKEN VALUE]` with your token: ```bash 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](/en/documentation/devtools/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. **API** 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: ```bash curl --request GET \ --url 'https://api.azion.com/v4/workspace/workloads?page_size=100&fields=id' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A `200` returns the page of workloads: ```json { "count": 17, "total_pages": 1, "page": 1, "page_size": 100, "next": null, "previous": null, "results": [ {"id": 1234567890}, {"id": 1234567891}, {"id": 1234567892}, {"id": 1234567893}, {"id": 1234567894}, {"id": 1234567895}, {"id": 1234567896}, {"id": 1234567897}, {"id": 1234567898}, {"id": 1234567899}, {"id": 1234567900}, {"id": 1234567901}, {"id": 1234567902}, {"id": 1234567903}, {"id": 1234567904}, {"id": 1234567905}, {"id": 1234567906} ] } ``` 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](/en/documentation/devtools/api/). **CLI** List the workloads with the Azion CLI. The `--page-size 1` flag returns one workload, and `--details` adds columns: ```bash azion list workload --page-size 1 --details ``` The command prints one row for the workload: ```text ID NAME ACTIVE LAST EDITOR LAST MODIFIED 1234567890 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`. **API** Send a `POST` request to the network lists endpoint: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/network_lists \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --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 { "state": "executed", "data": { "id": 1234567890, "name": "my-ip-list", "type": "ip_cidr", "items": ["192.0.2.10"], "last_editor": "you@example.com", "last_modified": "2026-01-01T12:00:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` The `active` field defaults to `true` when the request omits it. Record the `id`. The next stages send it in the URL. **CLI** Create the network list with the Azion CLI: ```bash 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: ```text 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. **API** Send a `GET` request to the network list. Replace `` with the `id` the create request returned: ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/network_lists/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A `200` returns the network list inside `data`: ```json { "data": { "id": 1234567890, "name": "my-ip-list", "type": "ip_cidr", "items": ["192.0.2.10"], "last_editor": "you@example.com", "last_modified": "2026-01-01T12:00:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` To rename the network list, send a `PATCH` request with the new `name` only: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/network_lists/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{"name": "my-ip-list-renamed"}' ``` A `200` returns the network list with the new name and a new `last_modified`: ```json { "state": "executed", "data": { "id": 1234567890, "name": "my-ip-list-renamed", "type": "ip_cidr", "items": ["192.0.2.10"], "last_editor": "you@example.com", "last_modified": "2026-01-01T12:01:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` The `type` and `items` fields keep the values of the create request. **CLI** Describe the network list. Replace `` with the ID the create command printed: ```bash azion describe network-list --network-list-id ``` The command prints the name, the type, the items, and the state of the network list: ```text ID: 12345 Name: my-ip-list Type: ip_cidr Items: ["192.0.2.10"] Last Editor: you@example.com Last Modified: "2026-01-01T12:00:00.000000Z" Active: true ``` Rename the network list: ```bash azion update network-list --network-list-id --name my-ip-list-renamed ``` The command confirms the update: ```text Updated Network List with ID 12345 ``` Describe the network list again: ```bash azion describe network-list --network-list-id ``` The output shows the new name and a new **Last Modified** value, and the type and items are unchanged: ```text ID: 12345 Name: my-ip-list-renamed Type: ip_cidr Items: ["192.0.2.10"] Last Editor: you@example.com Last Modified: "2026-01-01T12:01:00.000000Z" Active: true ``` --- ## Delete the network list Deleting the network list returns the account to the state it had before you created the list. **API** Send a `DELETE` request to the network list: ```bash curl --request DELETE \ --url https://api.azion.com/v4/workspace/network_lists/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A `200` returns only the state of the operation: ```json {"state": "executed"} ``` To confirm the deletion, send the `GET` request that read the list again. A `404` returns the error envelope: ```json {"errors": [{"code": "10004", "title": "Not Found", "detail": "Not found.", "status": "404"}]} ``` The network list no longer exists. **CLI** Delete the network list with the Azion CLI: ```bash azion delete network-list --network-list-id ``` The command confirms the deletion: ```text Network List 12345 was successfully deleted ``` To confirm the deletion, describe the network list again: ```bash azion describe network-list --network-list-id ``` The command exits with status `1` and prints the error: ```text 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 API](/en/documentation/devtools/api.md): The base URL, authentication, pagination, query parameters, and rate limits of the API. - [Troubleshoot Azion API](/en/documentation/devtools/api/troubleshooting.md): Causes and fixes for the errors the API returns, by status code. - [Network lists](/en/documentation/platform/firewall/network-shield/network-lists.md): The fields, list types, and errors of a network list, and how a firewall rule matches it. - [Azion CLI network-list](/en/documentation/devtools/cli/resources/network-list.md): Every flag of the commands that create, list, describe, update, and delete network lists.