Upload and download objects

You upload, list, download, replace, and delete the objects of an Object Storage bucket from Azion Console, the Azion API, the Azion CLI, or a function. An object exists as soon as its upload succeeds, stored under the key you gave it. The bucket then lists that key with its size and the time it was last modified.

To create the bucket itself, or to change the access level it carries, refer to Create a bucket.

Prerequisites

A bucket. To create one, refer to Create a bucket.
A file on your machine to upload.
Access to Azion Console, for the Console procedures. Refer to Access Azion Console.
A personal token, for the API procedures.
The Azion CLI installed and authorized, for the CLI procedures.

Upload an object using Azion Console

Azion Console is the shortest path for a handful of files. The API and the Azion CLI put the same upload inside a script or a pipeline. The files land in the files area of the bucket, described as “Browse, upload, and manage objects stored in this bucket.” To upload them:

Open the bucket

Access Azion Console > Object Storage > Buckets, then select the bucket.

Add the files

Select Upload files for one or more files, or Upload folder for a directory. Dragging the files onto the drop target, which reads “Drag files here to add them to your bucket”, adds them as well.

Each file is stored as an object of the bucket and appears in the files area under its key.

Azion Console refuses a file larger than 300 MB: “Files larger than 300 MB cannot be uploaded.” The bound applies to the Console. For more information, refer to Object Storage limits.

Upload an object using the API

The bucket name and the object key travel in the path, and the file travels in the request body. To upload the object:

Send the upload request

Replace [TOKEN VALUE] with your personal token, my-bucket with your bucket, and folder/file.csv with the key you want:

Shell

01curl --location --request POST 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]' \

04--header 'Content-Type: text/csv' \

05--data-binary '@./path/file.csv'

Read the response

The API answers with HTTP 201, or 202 when it processes the request asynchronously, and names the key it stored the object under:

JSON

01{

02 "state": "executed",

03 "data": {

04 "object_key": "folder/file.csv"

05 }

06}

The object is stored under folder/file.csv. The folder/ segment is part of the key: Object Storage creates the prefix with the upload, and no request creates it beforehand.

The stored content type comes from the Content-Type header of the upload. A request that carries no Content-Type leaves Azion to detect the type. An object key holds 1 to 1,024 characters. For more information, refer to Buckets and objects.

Upload an object using the Azion CLI

The command reads the file named in --source and stores it under --object-key. To upload the object:

azion create storage object --bucket-name my-bucket --object-key folder/file.csv --source ./path/file.csv

The command prints one line:

Object created successfully

The object is stored in the bucket, under the key you passed in --object-key.

--source takes a path relative to the directory you run the command in. An absolute path fails, because the Azion CLI prepends the working directory to it.

List the objects in a bucket

Every interface returns the keys the bucket holds, and the API narrows the list to one prefix.

Azion Console

Access Azion Console > Object Storage > Buckets, then select the bucket. Its files area lists the objects it holds.

The API

Send a GET request to the objects endpoint:

Shell

01curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]'

The response carries one entry per object: its key, the time it was last modified, its size in bytes, and whether the entry is a prefix.

JSON

01{

02 "continuation_token": null,

03 "results": [

04 {

05 "key": "folder/file.csv",

06 "last_modified": "2026-01-01T12:00:00.000000Z",

07 "size": 12,

08 "is_folder": false

09 }

10 ]

11}

Four query parameters shape the listing:

Parameter	What it does
`prefix`	Returns the keys that begin with the value. The default is empty, which returns every key
`all_levels`	Defaults to `true` and returns the keys at every level under the prefix
`max_object_count`	Sets how many entries one response carries, up to 1,000
`continuation_token`	Returns the entries that follow the token the previous response carried

With all_levels=false, a prefix is returned as one entry instead of the keys under it:

{"key": "folder/", "last_modified": null, "size": 0, "is_folder": true}

The Azion CLI

Name the bucket with --bucket-name:

azion list storage object --bucket-name my-bucket --page-size 5

The command prints a table with a KEY column and a LAST MODIFIED column. --details adds a SIZE column, and --next-page moves to the next page.

The listing names every key the bucket holds, which is how you confirm an upload arrived.

Download an object

A download returns the bytes of one object, addressed by its key.

The API

Send a GET request to the key:

Shell

01curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Authorization: Token [TOKEN VALUE]'

The API answers with HTTP 200 and the object as application/octet-stream, so the terminal prints the contents of the object. A key that does not exist answers with HTTP 404 and error 17013, Object Does Not Exist.

To write the object to a local file instead, add the curl options -O and -J. They take the object name from the response headers and write the output into a file:

Shell

01curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Authorization: Token [TOKEN VALUE]' \

03-O -J

A key that carries a prefix, such as folder/file.csv, creates no directory. The file is written to the directory you ran the command in.

The Azion CLI

Name the bucket and the key:

azion describe storage object --bucket-name my-bucket --object-key folder/file.csv

The command prints the content of the object.

You now hold the object’s bytes, in the terminal or in a local file.

Replace an object

Two methods write over the object stored under a key, and they differ in what they do with a key that does not exist yet. POST stores the object either way and answers with HTTP 201. PUT replaces only: a PUT to a key that does not exist answers with HTTP 404 and error 17013, Object Does Not Exist.

The API

Send a PUT request to the key, with the new file as the body:

Shell

01curl --location --request PUT 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]' \

04--header 'Content-Type: text/csv' \

05--data-binary '@./path/file.csv'

The API answers with HTTP 200, or 202 when it processes the request asynchronously, and names the key it replaced:

JSON

01{

02 "state": "executed",

03 "data": {

04 "object_key": "folder/file.csv"

05 }

06}

The Azion CLI

Name the new file in --source:

azion update storage object --bucket-name my-bucket --object-key folder/file.csv --source ./path/file.csv

The command prints one line:

Object updated successfully

azion update storage object -h lists every flag it accepts.

The key now addresses the new content, and the content it held is gone.

A key cannot be renamed. Azion Console carries a Move dialog, which asks for the destination folder path and takes the bucket root when the path is empty. The move copies the object to the destination and deletes the original, so the key itself is still immutable.

Delete an object

A delete is asynchronous. Azion accepts the request, the key leaves the listing at once, and the object is permanently removed after a 24-hour grace period.

Azion Console

To delete the objects:

Open the bucket

Access Azion Console > Object Storage > Buckets, then select the bucket.

Select the files to delete

Confirm the deletion

Azion Console asks “Are you sure you want to delete the selected files?” before it removes them.

The objects leave the files area of the bucket.

The API

Send a DELETE request to the key:

Shell

curl --location --request DELETE 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]'

The API answers with HTTP 202 and reports the delete as pending:

{"state": "pending"}

The key is gone from the listing, and a request for it answers with HTTP 404 right away.

The Azion CLI

Name the bucket and the key:

azion delete storage object --bucket-name my-bucket --object-key folder/file.csv

The command names the key it removed:

Object folder/file.csv was deleted successfully

The object answers no request, and a second delete of the same key returns error 17013, Object Does Not Exist.

Azion removes a deleted object permanently after a 24-hour grace period, and refuses to delete the bucket during that period. For more information, refer to Create a bucket.

Read and write objects from a function

A function reaches the same bucket through the azion:storage module, so an application stores what a request carries and returns what the bucket holds. To put the bucket behind a function:

Create the function

Create a function in Functions with this code. It routes by method. A POST writes the request body under the key taken from the request path. A GET reads the object back and answers with the content type it was stored with.

JavaScript

01import Storage from "azion:storage";

03async function doGet(path, bucket_name) {

04 const storage = new Storage(bucket_name);

05 const asset = await storage.get(path);

06 return new Response(await asset.arrayBuffer(), {

07 headers: {

08 "Content-Type": asset.contentType

09 },

10 });

11}

13async function doPost(path, content_type, value, bucket_name) {

14 let options = {

15 "content-type": content_type

16 }

17 const storage = new Storage(bucket_name);

18 await storage.put(path, value, options);

19 return new Response("Object added.");

20}

22async function router(event) {

23 const request = event.request;

24 const method = request.method;

25 const path = decodeURI(new URL(request.url).pathname);

26 const bucket_name = event.args.bucket;

27 if (method === "POST") {

28 let content_type = request.headers.get("Content-Type");

29 let content = await request.arrayBuffer();

30 return doPost(path, content_type, content, bucket_name);

31 } else if (method === "GET") {

32 return doGet(path, bucket_name);

33 } else {

34 throw new Error(`Invalid method: ${method}. Expected POST or GET.`);

35 }

36}

38addEventListener("fetch", (event) => {

39 event.respondWith(

40 router(event)

41 );

42});

The values it carries:

Variable	Description
`path`	The path to the object. Example: `./path/file.csv`
`bucket_name`	The name of the bucket. Example: `my-bucket`
`content_type`	The MIME type of the object. Example: `text/csv`
`value`	The contents of the object, as binary data

Set the bucket argument

The function reads the bucket name from its own arguments, so add the bucket property with the name of your bucket as a string:

JSON

01{

02 "bucket": "my-bucket"

03}

Instantiate the function in an application

A function answers a request only once an application runs it, so instantiate the function in the application that receives the uploads.

A POST to the application stores the request body in the bucket. A GET to the same path returns the object with the content type it was stored with.

storage.put and storage.get are two of the methods the module carries, and storage.list and storage.delete cover the other two operations on this page. For every method, its parameters, and what it returns, refer to Storage runtime API.

Next steps

Use a bucket as an application originPoint an application at the bucket so these objects answer requests from the internet.Buckets and objectsEvery field, parameter, and error of the bucket and object endpoints.Use S3-compatible tools with Object StorageManage the same objects with an S3 client and a credential.TroubleshootingWhat each rejection means when an upload, a download, or a delete fails.