HTTP API

The Walrus client offers a daemon mode that runs a simple web server that provides HTTP interfaces you can use to store and read blobs in an aggregator or publisher role respectively. Walrus also offers HTTP APIs through public aggregator and publisher services that you can use without running a local client.

For the following examples, set the AGGREGATOR and PUBLISHER environment variables to your desired aggregator and publisher, respectively. For example, set these variables to aggregator and publisher instances run by Walrus on Walrus Testnet:

$ AGGREGATOR=https://aggregator.walrus-testnet.walrus.space
$ PUBLISHER=https://publisher.walrus-testnet.walrus.space

Walrus aggregators and publishers expose their API specifications at the path /v1/api. View this path in a browser, for example, at https://aggregator.walrus-testnet.walrus.space/v1/api. The latest version of these specifications is available on GitHub in HTML and YAML format.

Store

You can store data using HTTP PUT requests. For example, with cURL, you can store blobs using a publisher:

# Store the string `some string` for 1 storage epoch
$ curl -X PUT "$PUBLISHER/v1/blobs" -d "some string"
# Store file `some/file` for 1 storage epoch
$ curl -X PUT "$PUBLISHER/v1/blobs" --upload-file "some/file"

Control how the new blob is created through a combination of several query parameters as documented in the OpenAPI specification. For example:

Specify the lifetime of the blob through the epochs parameter. If the parameter is omitted, blobs are stored for 1 epoch.

# Store file `some/file` for 5 storage epochs
$ curl -X PUT "$PUBLISHER/v1/blobs?epochs=5" --upload-file "some/file"

Specify whether a blob is stored as permanent or deletable through a query parameter permanent=true or deletable=true, respectively:

# Store file `some/file` as a deletable blob:
$ curl -X PUT "$PUBLISHER/v1/blobs?deletable=true" --upload-file "some/file"

# Store file `some/file` as a permanent blob:
$ curl -X PUT "$PUBLISHER/v1/blobs?permanent=true" --upload-file "some/file"

warning

Newly stored blobs are deletable by default.

Specify an address to which the resulting Blob object is sent using the send-object-to parameter:

# Store file `some/file` and send the blob object to `$ADDRESS`:
$ curl -X PUT "$PUBLISHER/v1/blobs?send_object_to=$ADDRESS" --upload-file "some/file"

The store HTTP API endpoints return information about stored blobs in JSON format. When a blob is stored for the first time, a newlyCreated field contains information about it:

$ curl -X PUT "$PUBLISHER/v1/blobs" -d "some other string"

If successful, the console responds with the information stored in the content of the blob's corresponding Sui object. :

{
  "newlyCreated": {
    "blobObject": {
    "id": "0xe91eee8c5b6f35b9a250cfc29e30f0d9e5463a21fd8d1ddb0fc22d44db4eac50",
    "registeredEpoch": 34,
    "blobId": "M4hsZGQ1oCktdzegB6HnI6Mi28S2nqOPHxK-W7_4BUk",
    "size": 17,
    "encodingType": "RS2",
    "certifiedEpoch": 34,
    "storage": {
        "id": "0x4748cd83217b5ce7aa77e7f1ad6fc5f7f694e26a157381b9391ac65c47815faf",
        "startEpoch": 34,
        "endEpoch": 35,
        "storageSize": 66034000
    },
    "deletable": false
    },
    "resourceOperation": {
    "registerFromScratch": {
        "encodedLength": 66034000,
        "epochsAhead": 1
    }
    },
    "cost": 132300
  }
}

When the publisher finds a certified blob with the same blob ID and a sufficient validity period, it returns an alreadyCertified JSON structure:

{
  "alreadyCertified": {
    "blobId": "M4hsZGQ1oCktdzegB6HnI6Mi28S2nqOPHxK-W7_4BUk",
    "event": {
    "txDigest": "4XQHFa9S324wTzYHF3vsBSwpUZuLpmwTHYMFv9nsttSs",
    "eventSeq": "0"
    },
    "endEpoch": 35
  }
}

The field event returns the Sui event ID that can be used to find the object creation transaction using a Sui Explorer or using a Sui SDK.

Read

You can read blobs using HTTP GET requests and their blob ID or object ID.

Blob IDs

For example, the following cURL command reads a blob and writes it to an output file:

$ curl "$AGGREGATOR/v1/blobs/<some blob ID>" -o <some file name>

Alternatively, you can print the contents of a blob in the terminal with the cURL command:

$ curl "$AGGREGATOR/v1/blobs/<some blob ID>"

tip

Modern browsers attempt to sniff the content type for such resources, and generally do a good job of inferring content types for media. However, the aggregator on purpose prevents such sniffing from inferring dangerous executable types such as JavaScript or style sheet types.

Object ID

You can also read blobs by using the object ID of a Sui blob object or a shared blob. For example, the following cURL command downloads the blob corresponding to a Sui object ID:

$ curl "$AGGREGATOR/v1/blobs/by-object-id/<object-id>" -o <some file name>

Downloading blobs by object ID allows setting some HTTP headers. The aggregator recognizes the following attribute keys and returns the values in the corresponding HTTP headers when present:

content-disposition
content-encoding
content-language
content-location
content-type
link

Consistency checks

The consistency checks performed by the aggregator are the same as the ones performed by the CLI. For special use cases, the strict consistency check can be enabled by adding a query parameter strict_consistency_check=true (starting with v1.35). If the writer of the blob is known and trusted, you can disable the consistency check by adding a query parameter skip_consistency_check=true (starting with v1.36).

Quilt HTTP APIs

Walrus supports storing and retrieving multiple blobs as a single unit called a quilt. Publishers and aggregators both support quilt operations.

Storing quilts

All query parameters available for storing regular blobs can also be used when storing quilts.

Use the following publisher API to store multiple blobs as a quilt.

# Store 2 files `document.pdf` and `image.png`, with custom identifiers `contract-v2` and `logo-2024`, respectively:
$ curl -X PUT "$PUBLISHER/v1/quilts?epochs=5" \
  -F "contract-v2=@document.pdf" \
  -F "logo-2024=@image.png"

Identifiers must be unique within a quilt and cannot start with _. The field name _metadata is reserved for Walrus native metadata and does not conflict with user-defined identifiers. See the Quilt documentation for complete identifier restrictions.

# Store 2 files with Walrus-native metadata. `_metadata` must be used as the field name for Walrus native metadata
$ curl -X PUT "$PUBLISHER/v1/quilts?epochs=5" \
  -F "quilt-manual=@document.pdf" \
  -F "logo-2025=@image.png" \
  -F '_metadata=[
    {"identifier": "quilt-manual", "tags": {"creator": "walrus", "version": "1.0"}},
    {"identifier": "logo-2025", "tags": {"type": "logo", "format": "png"}}
  ]'

The quilt store API returns a JSON response with information about the stored quilt, including the quilt ID (blobId) and individual blob patch IDs that can be used to retrieve specific blobs later. The following example shows the command and response. The actual JSON output is returned as a single line and is formatted on this page for readability:

$ curl -X PUT "http://127.0.0.1:31415/v1/quilts?epochs=1" \
  -F "walrus.jpg=@./walrus-33.jpg" \
  -F "another_walrus.jpg=@./walrus-46.jpg"

If successful, the console responds:

{
  "blobStoreResult": {
    "newlyCreated": {
    "blobObject": {
        "id": "0xe6ac1e1ac08a603aef73a34328b0b623ffba6be6586e159a1d79c5ef0357bc02",
        "registeredEpoch": 103,
        "blobId": "6XUOE-Q5-nAXHRifN6n9nomVDtHZQbGuAkW3PjlBuKo",
        "size": 1782224,
        "encodingType": "RS2",
        "certifiedEpoch": null,
        "storage": {
        "id": "0xbc8ff9b4071927689d59468f887f94a4a503d9c6c5ef4c4d97fcb475a257758f",
        "startEpoch": 103,
        "endEpoch": 104,
        "storageSize": 72040000
        },
        "deletable": false
    },
    "resourceOperation": {
        "registerFromScratch": {
        "encodedLength": 72040000,
        "epochsAhead": 1
        }
    },
    "cost": 12075000
    }
  },
  "storedQuiltBlobs": [
    {
    "identifier": "another_walrus.jpg",
    "quiltPatchId": "6XUOE-Q5-nAXHRifN6n9nomVDtHZQbGuAkW3PjlBuKoBAQDQAA"
    },
    {
    "identifier": "walrus.jpg",
    "quiltPatchId": "6XUOE-Q5-nAXHRifN6n9nomVDtHZQbGuAkW3PjlBuKoB0AB7Ag"
    }
  ]
}

Reading quilts

You can retrieve blobs from a quilt through the aggregator APIs using their quilt patch ID or their quilt ID and unique identifier. Currently, only 1 blob can be retrieved per request. Bulk retrieval of multiple blobs from a quilt in a single request is not yet supported.

Quilt patch ID

Each blob in a quilt has a unique patch ID. You can retrieve a specific blob using its patch ID.

# Retrieve a blob using its quilt patch ID:
$ curl "$AGGREGATOR/v1/blobs/by-quilt-patch-id/6XUOE-Q5-nAXHRifN6n9nomVDtHZQbGuAkW3PjlBuKoBAQDQAA" \

You can obtain QuiltPatchIds from the store quilt output or by using the list-patches-in-quilt CLI command.

Quilt ID and identifier

You can also retrieve a blob using the quilt ID and the blob's identifier.

# Retrieve a blob with identifier `walrus.jpg` from the quilt:
$ curl "$AGGREGATOR/v1/blobs/by-quilt-id/6XUOE-Q5-nAXHRifN6n9nomVDtHZQbGuAkW3PjlBuKo/walrus.jpg" \

Both methods return the raw blob bytes in the response body. Metadata such as the blob ID and tags are returned as HTTP headers:

X-Quilt-Patch-Identifier: The identifier of the blob within the quilt
ETag: The patch ID or quilt ID for caching purposes
Additional custom headers from blob tags, if configured

Using a public aggregator or publisher

On Walrus Testnet, many entities run public aggregators and publishers. On Mainnet, there are no public publishers without authentication, as they consume both SUI and WAL.

See the aggregators and publishers list for public services on Mainnet and Testnet. Walrus also provides the operator lists in JSON format.

The operator list in JSON format includes additional info about aggregators, namely whether they are deployed with caching functionality and whether they are found to be functional. The list is updated once per week.

Most aggregators and publishers limit requests to 10 MB by default. If you want to upload larger files, you need to run your own publisher or use the CLI.

Aggregators and publishers list

Loading operators...

Store​

Read​

Blob IDs​

Object ID​

Consistency checks​

Quilt HTTP APIs​

Storing quilts​

Reading quilts​

Quilt patch ID​

Quilt ID and identifier​

Using a public aggregator or publisher​

Aggregators and publishers list​