Aggregator

The aggregator reads blobs from the storage nodes, decodes them, checks their blob ID and serves them over HTTP. It also serves single files of a quilt and the status of the network.

Base URL: https://aggregator.iotastorage.com. Public, without authentication, with CORS (access-control-allow-origin: *).

Method	Path	Returns
GET, HEAD	/v1/blobs/<blob ID>	The blob.
GET, HEAD	/v1/blobs/by-object-id/<object ID>	The blob of a Blob object.
GET, HEAD	/v1/blobs/by-quilt-patch-id/<quilt patch ID>	One file (patch) of a quilt.
GET, HEAD	/v1/blobs/by-quilt-id/<quilt blob ID>/<identifier>	One file of a quilt, by its identifier.
GET	/v1/quilts/<quilt blob ID>/patches	The list of files of a quilt.
GET	/v1/estado	Status of the network.

Read a blob

curl -o file https://aggregator.iotastorage.com/v1/blobs/<blob ID>
curl -o file https://aggregator.iotastorage.com/v1/blobs/by-object-id/0x<object ID>

The response is the content of the blob, with these headers:

Header	Value
content-type	application/octet-stream
content-length	Size of the blob.
etag	The blob ID, in quotes. The content of a blob ID never changes.
x-content-type-options	nosniff

HEAD returns the same headers without the body.

• By object ID, the aggregator reads the Blob object on IOTA to get its blob ID. If there is no Blob with that ID, it answers 404.
• Every read is decoded from the slivers of the nodes and checked against the blob ID, so the aggregator never serves bytes that do not match.
• The largest blob is 149,286,452 bytes (about 142 MiB) with 100 shards.

Read a file of a quilt

A file stored in a quilt can be read by its quilt patch ID or by the blob ID of the quilt and the file's identifier:

curl https://aggregator.iotastorage.com/v1/blobs/by-quilt-patch-id/<quilt patch ID>
curl https://aggregator.iotastorage.com/v1/blobs/by-quilt-id/<quilt blob ID>/index.html

The identifier can contain slashes, encoded as %2F or not. The files of a site use their path as identifier, starting with /: /index.html is read at …/by-quilt-id/<quilt blob ID>/%2Findex.html. The response has the same headers as a blob, except:

• etag is the quilt patch ID;
• x-quilt-patch-identifier is the identifier of the file (URL-encoded if it is not ASCII).

If the blob is not a quilt, or it has no such patch, the answer is 404.

List the files of a quilt

curl https://aggregator.iotastorage.com/v1/quilts/<quilt blob ID>/patches

[
  { "identifier": "index.html", "patch_id": "<quilt patch ID>", "tags": {} },
  { "identifier": "logo.svg", "patch_id": "<quilt patch ID>", "tags": { "kind": "image" } }
]

tags are the tags stored with each file, if any (see the publisher).

Network status

GET /v1/estado is specific to IOTA Storage. It returns the current epoch, the shards, the largest blob and the committee. The field names are in Spanish:

curl https://aggregator.iotastorage.com/v1/estado

{
  "epoca": 1,
  "shards": 100,
  "tamanoMaximo": 149286452,
  "nodos": [
    { "nombre": "nodo-4", "direccionRed": "nodo-4.iotastorage.com:443", "shards": 25 },
    { "nombre": "nodo-1", "direccionRed": "nodo-1.iotastorage.com:443", "shards": 25 },
    { "nombre": "nodo-3", "direccionRed": "nodo-3.iotastorage.com:443", "shards": 25 },
    { "nombre": "nodo-2", "direccionRed": "nodo-2.iotastorage.com:443", "shards": 25 }
  ],
  "publisher": { "direccion": "0x…", "maxTamano": 10485760, "maxEpocas": 53, "conToken": true }
}

Field	Meaning
epoca	Current epoch.
shards	Number of shards of the network.
tamanoMaximo	Largest blob, in bytes.
nodos	Committee of the epoch: name, network address registered on IOTA and number of shards of each node.
publisher	If this server also publishes: its IOTA address, the largest blob it accepts (maxTamano), the most epochs (maxEpocas) and whether it requires a token (conToken). null otherwise.

Errors

Errors are JSON:

{ "error": { "status": "NOT_FOUND", "code": 404, "message": "…" } }

Code	status	When
400	INVALID_ARGUMENT	Malformed blob ID, object ID, quilt patch ID or identifier.
404	NOT_FOUND	No node has the blob (never stored, expired or deleted), no Blob with that object ID, not a quilt or no such patch, or unknown path.
405	METHOD_NOT_ALLOWED	Wrong method for the path.
503	UNAVAILABLE	Not enough primary slivers could be read from the nodes.

The message texts are currently in Spanish.

Current limitations

• A patch is read by decoding the whole quilt, which is then cached, instead of reading only the slivers of the patch's columns.
• It does not yet return the headers that come from the attributes of a Blob or from the tags of a patch.