Skip to main content

Quilt HTTP APIs

Walrus supports storing and retrieving multiple blobs as a single unit called a quilt. Publishers and aggregators both support quilt operations. Set $PUBLISHER and $AGGREGATOR to endpoints from the Network Reference.

To store and retrieve a blob in a quilt:

  1. Store the files as a quilt through the publisher with PUT /v1/quilts.
  2. From the store response, copy the quiltPatchId of the blob you want, or copy the quilt ID (blobId) and the blob's identifier.
  3. Retrieve the blob through the aggregator with /v1/blobs/by-quilt-patch-id/ or /v1/blobs/by-quilt-id/.

How to store quilts​

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

The following example stores 2 files as a quilt with custom identifiers:

# 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 _. Walrus reserves the field name _metadata for native metadata. Because identifiers cannot start with _, _metadata never conflicts with a user-defined identifier. See the Quilt documentation for complete identifier restrictions.

The following example stores 2 files with Walrus-native metadata tags:

# 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"}}
  ]'

Store response​

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 you can use to retrieve specific blobs later. The actual JSON output is returned as a single line and is formatted here 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 response contains the blob object details and the stored quilt blobs:

{
  "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"
    }
  ]
}

How to read 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.

How to retrieve by quilt patch ID​

Each blob in a quilt has a unique patch ID. 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 quilt patch IDs from the store quilt output (the quiltPatchId field of each entry in storedQuiltBlobs) or by using the list-patches-in-quilt CLI command.

How to retrieve by quilt ID and identifier​

You can also retrieve a blob using the quilt ID and the blob's identifier. The quilt ID is the blobId value in the store response:

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

Response headers​

Both methods return the raw blob bytes in the response body. Metadata such as the blob ID and the tags supplied through the _metadata field at store time 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

Which ETag does each retrieval method return?​

The ETag value depends on how you retrieve the blob:

  • /v1/blobs/by-quilt-patch-id/: The ETag contains the quilt patch ID.
  • /v1/blobs/by-quilt-id/: The ETag contains the quilt ID, not a patch ID. Every blob you retrieve from the same quilt through this endpoint returns the same ETag.