Walrus Protocol routes API
The routes API from Walrus Protocol — 9 operation(s) for routes.
OpenAPI Specification
openapi: 3.1.0
info:
title: Walrus Aggregator routes API
description: ''
contact:
name: Mysten Labs
email: build@mystenlabs.com
license:
name: Apache-2.0
identifier: Apache-2.0
version: 1.52.1
tags:
- name: routes
paths:
/v1/blobs/by-object-id/{blob_object_id}:
get:
tags:
- routes
summary: Retrieve a Walrus blob with its associated attribute.
description: 'First retrieves the blob metadata from Sui using the provided object ID (either of the blob
object or a shared blob), then uses the blob ID from that metadata to fetch the actual blob
data via the get_blob function. The response includes the raw data along with any attribute
headers from the metadata that are present in the configured allowed_headers set.'
operationId: get_blob_by_object_id
parameters:
- name: blob_object_id
in: path
required: true
schema:
$ref: '#/components/schemas/ObjectID'
responses:
'200':
description: The blob was reconstructed successfully. Any attribute headers present in this aggregator's allowed_headers configuration will be included in the response.
content:
application/octet-stream:
schema:
type: array
items:
type: integer
format: int32
minimum: 0
'400':
description: The consistency check options are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'403':
description: The blob size exceeds the maximum allowed size that was configured for this service. The blob is still stored on Walrus and may be accessible through a different aggregator or the CLI.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: May be returned when (1) The requested blob has not yet been stored on Walrus. (2) The requested quilt patch does not exist on Walrus.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'416':
description: The byte range parameters are invalid. This error is returned when the byte range parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: The blob cannot be returned as has been blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: An internal server error has occurred. Please report this error.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: 'The requested blob is currently not retrievable from the storage network. This is a transient condition: the blob may be mid-upload, mid-expiry, or enough storage nodes may be temporarily unreachable that the client cannot reconstruct the blob or determine a definitive status. Clients should retry with backoff.'
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/blobs/by-quilt-id/{quilt_id}/{identifier}:
get:
tags:
- routes
summary: Retrieve a patch from a Walrus quilt by its quilt ID and identifier.
description: 'Takes a quilt ID and an identifier and returns the corresponding patch from the quilt.
The patch content is returned as raw bytes in the response body, while metadata
such as the patch identifier and tags are returned in response headers.
# Example
```bash
curl -X GET "$aggregator/v1/blobs/by-quilt-id/\
rkcHpHQrornOymttgvSq3zvcmQEsMqzmeUM1HSY4ShU/my-file.txt"
```
Response:
```text
HTTP/1.1 200 OK
Content-Type: application/octet-stream
X-Quilt-Patch-Identifier: my-file.txt
ETag: "rkcHpHQrornOymttgvSq3zvcmQEsMqzmeUM1HSY4ShU"
[raw data]
```'
operationId: get_patch_by_quilt_id_and_identifier
parameters:
- name: quilt_id
in: path
description: The quilt's blob ID.
required: true
schema:
$ref: '#/components/schemas/BlobId'
- name: identifier
in: path
description: The identifier of the patch within the quilt
required: true
schema:
type: string
example: my-file.txt
responses:
'200':
description: The patch was retrieved successfully. Returns the raw bytes of the patch; the identifier and other attributes are returned as headers.
content:
application/octet-stream:
schema:
type: array
items:
type: integer
format: int32
minimum: 0
'403':
description: The blob size exceeds the maximum allowed size that was configured for this service. The blob is still stored on Walrus and may be accessible through a different aggregator or the CLI.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: May be returned when (1) The requested blob has not yet been stored on Walrus. (2) The requested quilt patch does not exist on Walrus.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'416':
description: The byte range parameters are invalid. This error is returned when the byte range parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: The blob cannot be returned as has been blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: An internal server error has occurred. Please report this error.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: 'The requested blob is currently not retrievable from the storage network. This is a transient condition: the blob may be mid-upload, mid-expiry, or enough storage nodes may be temporarily unreachable that the client cannot reconstruct the blob or determine a definitive status. Clients should retry with backoff.'
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/blobs/by-quilt-patch-id/{quilt_patch_id}:
get:
tags:
- routes
summary: Retrieve a patch from a Walrus quilt by its quilt patch ID.
description: 'Takes a quilt patch ID and returns the corresponding patch from the quilt.
The patch content is returned as raw bytes in the response body, while metadata
such as the patch identifier and tags are returned in response headers.
# Example
```bash
curl -X GET "$AGGREGATOR/v1/blobs/by-quilt-patch-id/\
DJHLsgUoKQKEPcw3uehNQwuJjMu5a2sRdn8r-f7iWSAAC8Pw"
```
Response:
```text
HTTP/1.1 200 OK
Content-Type: application/octet-stream
X-Quilt-Patch-Identifier: my-file.txt
ETag: "DJHLsgUoKQKEPcw3uehNQwuJjMu5a2sRdn8r-f7iWSAAC8Pw"
[raw data]
```'
operationId: get_patch_by_quilt_patch_id
parameters:
- name: quilt_patch_id
in: path
description: The quilt patch ID encoded as a URL-safe base64 string, without the trailing equal (=) signs.
required: true
schema:
$ref: '#/components/schemas/QuiltPatchId'
example: DJHLsgUoKQKEPcw3uehNQwuJjMu5a2sRdn8r-f7iWSAAC8Pw
responses:
'200':
description: The patch was retrieved successfully. Returns the raw bytes of the patch; the identifier and other attributes are returned as header.
content:
application/octet-stream:
schema:
type: array
items:
type: integer
format: int32
minimum: 0
'403':
description: The blob size exceeds the maximum allowed size that was configured for this service. The blob is still stored on Walrus and may be accessible through a different aggregator or the CLI.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: May be returned when (1) The requested blob has not yet been stored on Walrus. (2) The requested quilt patch does not exist on Walrus.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'416':
description: The byte range parameters are invalid. This error is returned when the byte range parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: The blob cannot be returned as has been blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: An internal server error has occurred. Please report this error.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: 'The requested blob is currently not retrievable from the storage network. This is a transient condition: the blob may be mid-upload, mid-expiry, or enough storage nodes may be temporarily unreachable that the client cannot reconstruct the blob or determine a definitive status. Clients should retry with backoff.'
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/blobs/{blob_id}:
get:
tags:
- routes
summary: Retrieve a Walrus blob.
description: 'Reconstructs the blob identified by the provided blob ID from Walrus and returns its raw data.
# HTTP Range Support
This endpoint also accepts the HTTP `Range` header to request only a portion of the blob.
When a `Range` header is provided with a specific byte range (e.g., `bytes=100-199`), the
endpoint returns HTTP 206 Partial Content with the requested byte range.
**Important**: When using byte range requests, only the consistency of the individual fetched
slivers is validated. The entire blob''s consistency is NOT validated, which provides better
performance for partial reads but with reduced integrity guarantees compared to full blob reads.
# Range Header Format
- `bytes=start-end`: Returns bytes from start to end (inclusive)
- `bytes=start-`: Not supported yet (TODO(WAL-1108))
- `bytes=-end`: Not supported yet
# Examples
```bash
# Get full blob
curl "$AGGREGATOR/v1/blobs/{blob_id}"
# Get first 1000 bytes
curl -H "Range: bytes=0-999" "$AGGREGATOR/v1/blobs/{blob_id}"'
operationId: get_blob
parameters:
- name: blob_id
in: path
required: true
schema:
$ref: '#/components/schemas/BlobId'
- name: strict_consistency_check
in: query
description: 'Whether to perform a strict consistency check.
This was the default before `v1.37`. In `v1.37`, the default consistency was changed to a
more performant one, which is sufficient for the majority of cases. This flag can be used to
enable the previous strict consistency check. See
<https://docs.wal.app/design/encoding.html#data-integrity-and-consistency> for more details.'
required: false
schema:
type: boolean
style: form
- name: skip_consistency_check
in: query
description: 'Whether to skip consistency checks entirely.
When enabled, this flag bypasses all consistency verification during blob reading. This
should be used only when the writer of the blob is trusted. Does *not* affect any
authentication checks for data received from storage nodes, which are always performed.'
required: false
schema:
type: boolean
style: form
responses:
'200':
description: The blob was reconstructed successfully
content:
application/octet-stream:
schema:
type: array
items:
type: integer
format: int32
minimum: 0
'400':
description: The consistency check options are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'403':
description: The blob size exceeds the maximum allowed size that was configured for this service. The blob is still stored on Walrus and may be accessible through a different aggregator or the CLI.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: May be returned when (1) The requested blob has not yet been stored on Walrus. (2) The requested quilt patch does not exist on Walrus.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'416':
description: The byte range parameters are invalid. This error is returned when the byte range parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: The blob cannot be returned as has been blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: An internal server error has occurred. Please report this error.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: 'The requested blob is currently not retrievable from the storage network. This is a transient condition: the blob may be mid-upload, mid-expiry, or enough storage nodes may be temporarily unreachable that the client cannot reconstruct the blob or determine a definitive status. Clients should retry with backoff.'
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/blobs/{blob_id}/byte-range:
get:
tags:
- routes
summary: Retrieve a specific byte range from a Walrus blob.
description: 'Reads a specific portion of a blob identified by the blob ID, starting from a given byte
position and reading a specified number of bytes. This is more efficient than retrieving the
entire blob when only a portion is needed.
Note that this endpoint has reduced consistency guarantees compared to the full blob read
since it will only validate the consistency of individual fetched slivers.
# Query Parameters
- `start`: The starting byte position (0-indexed, inclusive)
- `length`: The number of bytes to read
# Validation
- `start` and `length` must not overflow when added together
- The byte range `[start, start + length)` must be within the blob''s size
- `length` must be greater than 0
# Example
```bash
# Read 1024 bytes starting from position 0
curl "$AGGREGATOR/v1/blobs/{blob_id}/byte-range?start=0&length=1024"
```'
operationId: get_blob_byte_range
parameters:
- name: blob_id
in: path
required: true
schema:
$ref: '#/components/schemas/BlobId'
- name: start
in: query
description: The starting byte position (0-indexed, inclusive).
required: true
schema:
type: integer
format: int64
minimum: 0
style: form
- name: length
in: query
description: The number of bytes to read.
required: true
schema:
type: integer
format: int64
minimum: 0
style: form
responses:
'200':
description: The byte range was read successfully
content:
application/octet-stream:
schema:
type: array
items:
type: integer
format: int32
minimum: 0
'400':
description: The byte range parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'403':
description: The blob size exceeds the maximum allowed size that was configured for this service.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: The requested blob has not yet been stored on Walrus.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: The blob cannot be returned as it has been blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: An internal server error has occurred. Please report this error.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/quilts/{quilt_id}/patches:
get:
tags:
- routes
summary: List patches in a quilt.
description: "Returns a list of identifiers and quilt patch IDs for all patches contained in the specified\nquilt. Each quilt patch ID can be used with the `/v1/blobs/by-quilt-patch-id` endpoint to\nretrieve the actual blob data.\n\n# Example\n```bash\ncurl -X GET \"$aggregator/v1/quilts/patches-by-id/\\\nrkcHpHQrornOymttgvSq3zvcmQEsMqzmeUM1HSY4ShU\"\n```\n\nResponse:\n```json\n[\n {\n \"identifier\": \"walrus-38.jpeg\",\n \"patch_id\": \"uIiEbhP2qgZYygEGxJX1GeB-rQATo2yufC2DCp7B4iABAQANAA\"\n },\n {\n \"identifier\": \"walrus-39.avif\",\n \"patch_id\": \"uIiEbhP2qgZYygEGxJX1GeB-rQATo2yufC2DCp7B4iABDQBnAA\"\n }\n]\n```"
operationId: list_patches_in_quilt
parameters:
- name: quilt_id
in: path
description: The quilt ID encoded as URL-safe base64
required: true
schema:
$ref: '#/components/schemas/BlobId'
example: rkcHpHQrornOymttgvSq3zvcmQEsMqzmeUM1HSY4ShU
responses:
'200':
description: Successfully retrieved the list of patches in the quilt
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/QuiltPatchItem'
'403':
description: The blob size exceeds the maximum allowed size that was configured for this service. The blob is still stored on Walrus and may be accessible through a different aggregator or the CLI.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: May be returned when (1) The requested blob has not yet been stored on Walrus. (2) The requested quilt patch does not exist on Walrus.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'416':
description: The byte range parameters are invalid. This error is returned when the byte range parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: The blob cannot be returned as has been blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: An internal server error has occurred. Please report this error.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: 'The requested blob is currently not retrievable from the storage network. This is a transient condition: the blob may be mid-upload, mid-expiry, or enough storage nodes may be temporarily unreachable that the client cannot reconstruct the blob or determine a definitive status. Clients should retry with backoff.'
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1alpha/blobs/concat:
get:
tags:
- routes
summary: Concatenate and stream multiple blobs via GET.
description: 'Retrieves multiple blobs specified by comma-separated blob IDs or object IDs in the query
parameter, and streams them concatenated in the order specified. Each blob is loaded,
streamed, and then freed from memory before the next blob is processed.'
operationId: get_blobs_concat
parameters:
- name: ids
in: query
description: Comma-separated list of blob IDs or object IDs to concatenate.
required: true
schema:
type: string
style: form
- name: read_options
in: query
description: Consistency check options for reading the blobs.
required: true
schema:
$ref: '#/components/schemas/ReadOptions'
style: form
responses:
'200':
description: Blobs concatenated and streamed successfully
content:
application/octet-stream:
schema:
type: array
items:
type: integer
format: int32
minimum: 0
'400':
description: The consistency check options are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'403':
description: One of the blobs exceeds the maximum allowed size.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: May be returned when (1) Failed to resolve an object ID to a blob ID. (2) One of the requested blobs was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: One of the blobs is blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: Failed to read a blob.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
post:
tags:
- routes
summary: Concatenate and stream multiple blobs via POST.
description: 'Retrieves multiple blobs specified in a JSON request body containing an array of blob IDs
or object IDs, and streams them concatenated in the order specified. Each blob is loaded,
streamed, and then freed from memory before the next blob is processed.'
operationId: post_blobs_concat
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConcatRequestBody'
required: true
responses:
'200':
description: Blobs concatenated and streamed successfully
content:
application/octet-stream:
schema:
type: array
items:
type: integer
format: int32
minimum: 0
'400':
description: The consistency check options are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'403':
description: One of the blobs exceeds the maximum allowed size.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: May be returned when (1) Failed to resolve an object ID to a blob ID. (2) One of the requested blobs was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'451':
description: One of the blobs is blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: Failed to read a blob.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/blobs:
put:
tags:
- routes
summary: Store a blob on Walrus.
description: 'Store a (potentially deletable) blob on Walrus for 1 or more epochs. The associated on-Sui
object can be sent to a specified Sui address.'
operationId: put_blob
parameters:
- name: encoding_type
in: query
description: The encoding type to use for the blob.
required: false
schema:
$ref: '#/components/schemas/EncodingType'
style: form
- name: epochs
in: query
description: 'The number of epochs, ahead of the current one, for which to store the blob.
The default is 1 epoch.'
required: false
schema:
$ref: '#/components/schemas/u32'
style: form
- name: deletable
in: query
description: 'If true, the publisher creates a deletable blob.
New blobs are created as deletable by default since v1.33, and this flag is no longer
required.'
required: false
deprecated: true
schema:
type: boolean
style: form
- name: permanent
in: query
description: 'If true, the publisher creates a permanent blob instead of a deletable one.
This was the default behavior before v1.33, but *blobs are now deletable by default*.'
required: false
schema:
type: boolean
style: form
- name: force
in: query
description: 'If true, the publisher will always store the blob, creating a new Blob object.
The blob will be stored even if the blob is already certified on Walrus for the specified
number of epochs.'
required: false
schema:
type: boolean
style: form
- name: quilt_version
in: query
description: 'The quilt version to use (for quilt endpoints only).
Valid values: "v1", "V1", or "1". Defaults to "v1" if not specified.'
required: false
schema:
$ref: '#/components/schemas/QuiltVersionEnum'
style: form
- name: reuse_resources
in: query
description: 'If true, the publisher will attempt to reuse existing on-chain resources (e.g., storage and
blob objects) when storing a blob.'
required: false
schema:
type: boolean
style: form
- name: send_or_share
in: query
required: false
schema:
oneOf:
- type: object
description: Send the blob to the specified Sui address.
required:
- send_object_to
properties:
send_object_to:
$ref: '#/components/schemas/SuiAddress'
description: Send the blob to the specified Sui address.
- type: object
description: Turn the created blob into a shared blob.
required:
- share
properties:
share:
type: boolean
description: Turn the created blob into a shared blob.
description: The exclusive option to share the blob or to send it to an address.
style: form
requestBody:
description: Binary data of the unencoded blob to be stored.
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/Binary'
required: true
responses:
'200':
description: The blob was stored successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStoreResult'
'400':
description: May be returned when (1) The blob cannot be defined as both deletable and permanent. (2) The request is malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'413':
description: The blob is too large
'451':
description: The blob cannot be returned as it has been blocked.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'500':
description: An internal server error has occurred. Please report this error.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'504':
description: The service failed to store the blob to sufficient Walrus storage nodes before a timeout, please retry the operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/quilts:
put:
tags:
- routes
summary: Store multiple files as a quilt using multipart/form-data.
description: "Accepts a multipart form with files and optional per-file Walrus-native metadata.\nThe form contains:\n- Files identified by their identifiers as field names\n- An optional `_metadata` field containing a JSON array with per-file Walrus-native metadata\n\n# Contents of Walrus-native metadata\n- `identifier`: The identifier of the file, must match the corresponding file field name\n- `tags`: JSON object with string key-value pairs (optional)\n\nFiles without corresponding metadata entries will be stored with empty tags.\n\n# Examples\n\n## Files without Walrus-native metadata, with quilt version V1\n```bash\ncurl -X PUT \"$PUBLISHER/v1/quilts?epochs=5&quilt_version=V1\" \\\n -F \"contract-v2=@document.pdf\" \\\n -F \"logo-2024=@image.png\"\n```\n\n## Files with Walrus-native metadata, with default quilt version\n```bash\ncurl -X PUT \"$PUBLISHER/v1/quilts?epochs=5\" \\\n -F \"quilt-manual=@document.pdf\" \\\n -F \"logo-2025=@image.png\" \\\n -F \"_metadata=[\n {\"identifier\": \"quilt-manual\", \"tags\": {\"creator\": \"walrus\", \"version\": \"1.0\"}},\n {\"identifier\": \"logo-2025\", \"tags\": {\"type\": \"logo\", \"format\": \"png\"}}\n ]'\n```"
operationId: put_quilt
parameters:
- name: encoding_type
in: query
description: The encoding type to use for the blob.
required: false
schema:
$ref: '#/components/schemas/EncodingType'
style: form
- name: epochs
in: query
description: 'The number of epochs, ahead of the current one, for which to store the blob.
The default is 1 epoch.'
required: false
schema:
$ref: '#/components/schemas/u32'
style: form
- name: deletable
in: query
description: 'If true, the publisher creates a deletable blob.
New blobs are created as deletable by default since v1.33, and
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/walrus-protocol/refs/heads/main/openapi/walrus-protocol-routes-api-openapi.yml