Wallet Attached Storage v0.3

Initial use cases that are motivating this work:

• Sharing of W3C Verifiable Credentials from mobile credential wallets, as well as document sharing in general
• Serving as standardized storage (and a point of sync and interop) for multiple Verifiable Credential wallets.
• Enabling data portability and service provider interoperability for user-controlled social networking
• Enabling the "bring your own storage" architecture pattern of web app development
• Providing data storage and authorization frameworks for Agentic AI

This specification represents a layered and modular approach to storage, combining core features and optional extension points.

The layers below describe conformance tiers. Each tier adds optional capability on top of the one before it, so an implementer can stop at any tier and still be conformant. The normative body, by contrast, is organized container-first (outermost to innermost: Spaces Repositories, Spaces, Collections, then Resources), which is convenient as a reference but is the reverse of the tiers. If you're new to the spec, scan the profile table below for the conformance tiers, then walk through 2.5 Quickstart: Your First Request to watch a request succeed. The core tier is just 11. Resources and Blobs plus 5.1 WAS Authorization Profile v0.1.

Each tier stacks on the one above it. The Minimal profile is a permissioned key/value CRUD API built from simple HTTP verbs and delegatable capability-based authorization -- enough, on its own, to read and write any resource (text, structured document, or binary blob) without collection or space management.Listing, Collection and Space management will feel familiar to anyone who has used a GUI front end for a database or file system. Multi-tenant support lets a provider host many Spaces on one server. The Extensions tier layers on optional features -- an access-policy resource, user-writable metadata (for example, "tags" on binary files), a Space export endpoint, pluggable 13. Backends, query, quotas, client-side encryption (via Encrypted Data Vaults), replication, and versioning -- discovered through the linkset feature-detection mechanism (from [RFC9264]; see 12. Linksets).

Normative status. Section back-placement does not imply informative status. Everything from 2. Introduction through 14. Quotas is normative, as are the appendices A. Pagination, B. Reserved Path Segment Registry, C. Encryption Scheme Registry, and E. Error Type Registry (each of which also carries an inline "This appendix is normative." banner). The remaining appendices -- F. Goals and Requirements and G. IANA Considerations -- are informative. Optionality is orthogonal to normativity: many normative sections describe OPTIONAL endpoint groups, but a server that implements them MUST follow the stated requirements.

Step 1: Write. PUT a JSON document to a resource path under a collection. A 204 No Content confirms the write:

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{"message":"hi"}

HTTP/1.1 204 No Content

Step 2: Read. GET the same path to retrieve what you just stored:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{"message":"hi"}

(The Authorization: ... placeholder stands for a signed zCap invocation). WAS reads are authorized too, so the header is required on the GET just as on the PUT. How that invocation is constructed is defined in 5.1.3 Performing Authorized API Calls, and its fully expanded form -- with the Digest, Capability-Invocation, and Signature headers spelled out -- is shown once in the worked example within that section. Producing that signature requires a conformant WAS client: it is an Ed25519 did:key capability invocation, not something you can hand-write with curl.

To go beyond a single pre-existing Space -- to create your own Space, or delegate access to others -- see the conformance-profile table in 2.4 Scope and Conformance Profiles and the full endpoint map in 2.6 API Summary.

API summary at a glance.

Unless otherwise specified by the controller, all operations require authorization. This can be overridden by the controller via the (optional) /policy endpoints. Hosting "public-read" resources, such as HTML files for websites, or media files you can link to via <img src="">, is a common use case.

The endpoints below divide into a Core profile that every conformant server implements, and Optional extensions grouped by feature. Each row links to the section that defines its operation. Rows marked Reserved name a path this specification anchors (see B. Reserved Path Segment Registry) but does not yet define an operation for; a server MUST NOT repurpose a reserved path.

Space, Collection, and Resource identifiers used in this specification are required to have the following properties.

1. URL-safety - All characters in a given identifier MUST be URL-safe.
2. Uniqueness - All identifiers MUST be unique within a given container. That is: Space ids (denoted by {space_id} in URL templates) MUST be unique within a given server, Collection ids (denoted by {collection_id} in URL templates) MUST be unique within a given Space, and Resource ids (denoted by {resource_id} in URL templates) MUST be unique within a given Collection.

Identifier length limits are currently left to the implementer. However, implementations SHOULD limit identifier length to their appropriate use case.

Identifier format constraints are currently left to the implementer. Common identifier formats include:

• Random IDs (either UUIDv4 with hyphens or using a compact encoding). Not recommended for extremely high throughput use cases, since the clients or servers that are generating them might be limited by available device entropy.
• Semi-random Time-sortable IDs (UUIDv7). Useful for cases involving logs, histories, feeds, and other situations where sorting by time is desirable.
• Content-based IDs (CIDs). Useful for data deduplication use cases.
• Human-readable IDs. Some use cases might require human-readable identifiers (for example, a user hosting a blog in their space might want meaningful collection and resource IDs such as /posts/2020-01-01-hello-world).

Like many authorization specifications, the WAS Authorization Profile tries to address opposing tensions. On the one hand, to cover the full range of use cases, it needs to be delegatable, revocable, secure, flexible, and thus capability-based. On the other hand, for ease of implementation and adoption, and for maximum developer usability, the profile must make the most common operations as simple and friction-free as possible.

To that end, the profile offers the following layered mechanisms.

1. Root Access: For basic admin CRUD operations, use the space's controller DID directly to sign API calls with HTTP Signatures.
2. Public Read: For the common "public read" use case (the typical web publishing workflow, where a site or a file is shared for anyone to access via an HTTP GET), use the simple { "type": "PublicCanRead" } WAS Authorization syntax, see below.
3. Advanced Delegatable Capabilities ("anyone with the link..." style): Use zCaps Authorization Capabilities v0.3
4. Policy Based Access Control (including the familiar "share with this list of people or groups" style): Use the space's linkset property to point to a linkset that includes a URL to an access control policy document.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/photos/sunset.png HTTP/1.1
Host: example.com
Content-Type: image/png
Digest: mh=uEiCPO-qYr-z0GYV5F75-N1l8Rhjv4xIkKZsnbTZeZ7emSA
Capability-Invocation: zcap id="urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2F81246131-69a4-45ab-9bff-9c946b59cf2e%2Fphotos%2Fsunset.png",action="PUT"
Authorization: Signature keyId="did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW#z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest",
  signature="6GoRQ+rW69wBhNyERkafAXEZXZArezHvGRNUWC0HNI4Ss1xAiiMHdayS5aA2R6hLuYRNw6h9J9eCmQVMuHE1Bw==",
  created="1758150502",expires="1758151102"

...binary PNG bytes...

{
  "@context": "https://w3id.org/zcap/v1",
  "id": "urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2F81246131-69a4-45ab-9bff-9c946b59cf2e%2Fmessages%2Fhello-world",
  "invocationTarget": "https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

{
  "@context": "https://w3id.org/zcap/v1",
  "id": "urn:uuid:6c9f3a1e-2b4d-4f8a-9c1e-7d2b3a4c5e6f",
  "parentCapability": "urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2F81246131-69a4-45ab-9bff-9c946b59cf2e%2Fmessages%2F",
  "invocationTarget": "https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/",
  "controller": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "allowedAction": ["GET"],
  "expires": "2026-12-31T23:59:59Z",
  "proof": { "...": "delegation proof signed by the parent capability's controller" }
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset HTTP/1.1
Host: example.com
Accept: application/linkset+json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/linkset+json

{
  "linkset": [
    {
      "anchor": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e",
      "https://wallet.storage/spec#policy": [
        { 
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy",
          "type": "application/json"
        }
      ]
    }
  ]
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy HTTP/1.1
Host: example.com
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{ "type": "PublicCanRead" }

{ "type": "PublicCanRead" }

WAS relies on ordinary [RFC9111] HTTP caching and defines no caching layer of its own. On the read side, a Resource's strong ETag validator (see 7.2 Conditional Requests) drives standard validation: a GET carrying If-None-Match: "<etag>" yields 304 Not Modified when the Resource is unchanged. Servers SHOULD emit ETag (and MAY emit Last-Modified) on GET/HEAD responses, and SHOULD mark responses to non-idempotent operations as non-cacheable (for example, Cache-Control: no-store).

Servers and backends MAY support [RFC9110] conditional requests to provide optimistic concurrency control on writes. This mechanism helps prevent the "lost update" problem, where two clients that both read version N of a Resource each write version N+1 and the second silently clobbers the first. A backend that supports this advertises the conditional-writes feature in its Backend description (see 13.1 Backend Data Model); a client SHOULD use these preconditions only against a backend that advertises support.

When supported, a Resource carries a strong ETag validator that changes whenever its stored content changes. Servers SHOULD return the ETag on GET/HEAD responses. The validator is opaque to clients: how a backend derives it is a server-side concern (see 13.1 Backend Data Model).

A state-changing request (PUT or DELETE) MAY carry a precondition:

• If-Match: "<etag>" -- perform the write only if the Resource's current ETag matches it (an "update-if-unchanged"). If it does not match, the server MUST NOT perform the write and MUST respond with precondition-failed (412).
• If-None-Match: * -- perform the write only if the Resource does not yet exist (a "create-if-absent"). If it already exists, the server MUST NOT perform the write and MUST respond with precondition-failed (412).

A server that supports conditional writes MUST evaluate the precondition atomically with the write, so that two concurrent writers cannot both observe the same prior version and both succeed; how a backend achieves this atomicity is a server-side concern (see 13.1 Backend Data Model). A client recovers from a 412 by re-reading the current Resource, re-applying its change on top of the new version, and retrying.

As with id-conflict, a server MUST verify the caller's authorization before evaluating a precondition, so a 412 is only ever observed by a caller already authorized to write the target; an under-authorized caller receives the merged not-found (404) instead, per the maximum-privacy rule in 6. Error Handling.

A 412 arises only from an explicit If-Match / If-None-Match precondition header. It is deliberately distinct from the header-less 409 conflict kinds -- id-conflict (a POST create whose chosen id is already taken) and reserved-id -- which describe a conflict with current state where the client stated no precondition. Conditional requests are the versioned, header-driven concurrency mechanism; the 409 kinds are not.

The list operations -- 8.2 List Spaces Operation, 9.5 List All Collections operation, and 10.5 List Collection operation -- MAY paginate their responses, returning one page of items at a time using the cursor-based profile defined in Appendix A. Pagination. Pagination is OPTIONAL: a server that returns every item in a single response is conformant, and a client MUST be prepared for either behavior.

To create a Space:

• Perform an authorized Create Space operation that includes a Proof of (cryptographic material) Possession via a mechanism such as HTTP Signatures.

• If no id is provided, it will be generated by the storage server.

• A controller DID MUST be provided in the request body, and the request MUST be authorized by that DID.

  • If no controller is provided, the server MUST return an HTTP 400 error response
  • The capability invocation MUST be authorized by the body's controller: either signed directly by the controller DID (the common case), or signed by another DID presenting a valid, unexpired delegation chain rooted in the controller (see 5.1.5.2 Delegation). This is how the root of trust is initially set up (see 5.1.2 Space controller and the Root of Trust for more details).
  • The delegated form supports creating a Space on behalf of its eventual controller: for example, a provisioning service that handles payment or onboarding can be delegated a POST capability for /spaces/ by the user, and create a Space that the user's DID controls from the start. What is never acceptable is installing a controller that has authorized nothing at all: that would let anyone bind arbitrary DIDs to Spaces without their consent -- squatting meaningful ids "in their name", or burning per-controller onboarding allowances such as "one free Space per controller".

• (Optional, out of scope) A given storage provider MAY impose additional requirements to create a Space for a given controller, such as:

  • a Verifiable Credential representing a pre-arranged onboarding coupon
  • a proof of payment
  • a proof of membership in an organization

POST /spaces/ HTTP/1.1
Host: example.com
Accept: application/json
Content-type: application/json
Authorization: ...

{
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

• Requires appropriate authorization (root zcap invoked by the controller of one or more spaces, or a zcap granting permission to read a one or more spaces)

• Lists only the spaces the requester is authorized to see

• MAY be paginated (see A. Pagination)

GET /spaces/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "url": "/spaces/",
  "totalItems": 1,
  "items": [
    {
      "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e"
    }
  ]
}

HTTP/1.1 200 OK
Content-type: application/json

{
  "url": "/spaces/",
  "totalItems": 0,
  "items": []
}

Space properties:

• id - A unique identifier for a space at a given server. Created by the server if not provided. Note: the {space_id} template parameter used in URL templates in this spec MUST match that space's id property. See 4. Identifiers for additional constraints.
• type - An array of strings, MUST include the type Space. The array SHOULD be lexically sorted so that the object has a canonical, stable serialization (useful for hashing or signing).
• name (optional) - An arbitrary human-readable name for the space. Does not have to be unique.
• controller - A cryptographic identifier (a did) of the entity that is authorized to perform operations on the space (or to delegate authorization to other entities)

Space properties automatically added by the server:

• createdBy (optional) - The did of the party whose capability invocation created the space. It is recorded on the first write and preserved unchanged by later writes, so it names the creator rather than the last writer. It is read-only: a server MUST ignore a createdBy supplied in a request body. createdBy is distinct from controller -- under delegated provisioning (see 5.1.2 Space controller and the Root of Trust) the party that creates a space need not be the party that controls it. Recording it is OPTIONAL, so a client MUST treat an absent createdBy as "not recorded" rather than as an assertion that the space has no creator.
• url - A relative URL to the space's description resource. Added by the server, used in the Space Description object as well as the 8.2 List Spaces Operation result.
• linkset - A relative URL to a resource which contains a set of links to auxiliary resources (such as to access control policy documents). See section 12.1 Space Linkset. Note that this is one of the B.1 Space-level reserved endpoints.

• Requires appropriate authorization (root zcap invoked by the space's controller, or a zcap granting permission to read a particular space)
• Returns the details for the specified space id
• Only includes the resources the requester is authorized to see

The format of the response is determined based on content negotiation; application/json is the REQUIRED baseline (see 11.3 Content Types and Representations).

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "createdBy": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset"
}

When creating or modifying a Space via PUT, the client specifies the id of the Space.

• Requires appropriate authorization (root zcap invoked by the space's controller, or a zcap granting permission to write to a particular space)
• Allows the client to update the following fields:
  • name
  • controller

The controller property in the request body is the proposed value, not the root of trust for the request. When the Space already exists, the capability invocation MUST be verified against the Space's currently stored controller: only the current controller (or its delegate) may update the Space, including transferring it by writing a new controller. The body's controller participates in verification only when the PUT creates the Space -- there is no stored controller yet, so, as with 8.1 Create Space operation, the invocation MUST be authorized by the body's controller: signed by it directly, or presented with a valid, unexpired delegation chain rooted in it (violations are controller-mismatch, as for POST). A server that verifies an update against the body's controller reopens the takeover described under 8.1.2 Create Space Errors: any caller could seize an existing Space by PUTting its id with themselves as the controller.

A server that records createdBy (see 9.1 Space Data Model) sets it only on the PUT that creates the Space, to the did of the party that invoked the capability -- which is not necessarily the body's controller. On a PUT that updates an existing Space, the stored createdBy is preserved, so transferring the Space by writing a new controller does not rewrite its creator.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Accept: application/json
Content-type: application/json
Authorization: ...

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Content-type: application/json
Accept: application/json
Authorization: ...

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Newly renamed space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW"
}

HTTP/1.1 204 No Content

• Requires appropriate authorization (root zcap invoked by the space's controller, or a zcap granting permission to write to a particular space)
• Deletes the space and all the data (collections and resources) contained in it
• This operation is idempotent

DELETE /space/81246131-69a4-45ab-9bff-9c946b59cf2e HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 204 No Content

• Returns the list of all Collections in a Space (that the requester has permission to access)
• Requires appropriate authorization
  • For example, when using zCaps for authorization, the request must be signed by the space's controller, or invoke a delegated capability that allows the GET action
• Since Collection's name property is optional, default it to be the same value as id when name is missing. (The name is intended to drive UIs, so defaulting to id simplifies consuming client logic.)
• MAY be paginated (see A. Pagination)

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/",
  "totalItems": 2,
  "items": [
    {
      "id": "example",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/example",
      "name": "Example Collection"
    },
    {
      "id": "73WakrfVbNJBaAmhQtEeDv",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
      "name": "73WakrfVbNJBaAmhQtEeDv"
    }
  ]
}

Collection properties (user-writable):

• id - A unique collection identifier (within a given space). Created by the server if not provided. Note: the {collection_id} template parameter used in URL templates in this spec MUST match that collection's id property. See 4. Identifiers for additional constraints.
• type - An array of strings, MUST include the type Collection. As with a Space's type, the array SHOULD be lexically sorted for a canonical, stable serialization.
• name (optional) - An arbitrary human-readable name for the collection. Does not have to be unique.
• backend (optional) - An object describing the storage backend selected for this collection. If not specified, defaults to the value { "id": "default" }. The backend object's id property MUST be from the list of 13.2 Space Backends Available for the given space. If an unavailable (unsupported) backend is specified, the server MUST throw an error. See section 13. Backends for more details.
• encryption (optional) - A non-secret marker declaring that this collection's Resources are client-side encrypted, and naming the scheme. The value is an object with a required string scheme property (e.g. { "scheme": "edv" } for the EDV-over-WAS scheme); absent means the collection is plaintext. The server MUST NOT interpret the marker beyond validating its shape -- it never holds key material and stores the marker opaquely. Its purpose is discovery: any authorized reader (including a delegated consumer that did not create the collection) learns from the Collection Description that the collection is encrypted, and decrypts with its own keys. The marker is set-once: a server MUST allow declaring it on a collection that lacks one (e.g. migrating a pre-existing collection), but MUST reject (with an encryption-immutable error) any attempt to change its scheme or clear it on an existing collection, since that would corrupt the already-stored encrypted Resources. See section 13. Backends (client-side encryption note) for the rationale. A server that recognizes the declared scheme enforces it structurally on write -- rejecting any non-envelope body so plaintext can never be stored in an encrypted Collection; see C. Encryption Scheme Registry.

Collection properties automatically added by the server:

• createdBy (optional) - The did of the party whose capability invocation created the collection, on the same terms as a Space's createdBy (see 9.1 Space Data Model): recorded on the first write, preserved by later writes, read-only, and OPTIONAL.
• url - A relative URL to the collection's description resource. Added by the server, used in the Collection Description object as well as the List Collections operations result.
• linkset - A relative URL to a resource which contains a set of links to auxiliary resources (such as to access control policy documents). See section 12.2 Collection Linkset. Note that this is one of the B.2 Collection-level reserved endpoints.

Example collection (JSON representation):

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "type": ["Collection"],
  "name": "Verifiable Credentials Collection",
  "createdBy": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/linkset"
}

When a Collection is created via a POST, the client can specify the id of the Collection. If the id is not specified, one is auto-generated by the server and returned as part of the Location response header.

POST /space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/ HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"]
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/21f81693-f4a3-4caa-b81c-b663d6e1e3ae

POST /space/81246131-69a4-45ab-9bff-9c946b59cf2e/collections/ HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "id": "credentials",
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"],
  "backend": { "id": "default" }
}

HTTP/1.1 201 Created
Content-type: application/json
Location: https://example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e/credentials

When creating or modifying a Collection via PUT, the client specifies the id of the Collection. This Collection id MUST NOT collide with the list of B.1 Space-level reserved endpoints.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"],
  "backend": { "id": "default" }
}

HTTP/1.1 201 Created

• Returns the Collection description object
• Requires appropriate authorization
  • For example, when using zCaps for authorization, the request must be signed by the space's controller, or invoke a delegated capability that allows the GET action

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"],
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/linkset",
  "backend": { "id": "default" }
}

• Returns the list of Collection resources
• Requires appropriate authorization
  • For example, when using zCaps for authorization, the request must be signed by the space's controller, or invoke a delegated capability that allows the GET action
• MAY be paginated (see A. Pagination); the example below shows a single unpaginated page, and the paginated example that follows shows the next link and cursor continuation.

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/ HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Example JSON Documents Collection",
  "type": ["Collection"],
  "totalItems": 2,
  "items": [
    {
      "id": "321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "contentType": "application/json" 
    },
    {
      "id": "3943c87f-b617-44bc-ba75-8de2b16c3640",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/3943c87f-b617-44bc-ba75-8de2b16c3640",
      "contentType": "application/json" 
    }
  ]
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/?limit=2 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Example JSON Documents Collection",
  "type": ["Collection"],
  "items": [
    {
      "id": "321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/321efd4e-23cb-497c-aaee-7bd26e66d39e",
      "contentType": "application/json"
    },
    {
      "id": "3943c87f-b617-44bc-ba75-8de2b16c3640",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/3943c87f-b617-44bc-ba75-8de2b16c3640",
      "contentType": "application/json"
    }
  ],
  "next": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/?limit=2&cursor=eyJhZnRlciI6IjM5NDNjODdmLWI2MTctNDRiYy1iYTc1LThkZTJiMTZjMzY0MCJ9"
}

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/?limit=2&cursor=eyJhZnRlciI6IjM5NDNjODdmLWI2MTctNDRiYy1iYTc1LThkZTJiMTZjMzY0MCJ9 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: ...

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv",
  "name": "Example JSON Documents Collection",
  "type": ["Collection"],
  "items": [
    {
      "id": "9c7b2e51-0d4a-4c2f-8b3e-1f6a5d8e7c90",
      "url": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/73WakrfVbNJBaAmhQtEeDv/9c7b2e51-0d4a-4c2f-8b3e-1f6a5d8e7c90",
      "contentType": "application/json"
    }
  ]
}

A unit of data, in transit or at rest. (As described in the W3C FileAPI: Blob Interface).

Blob properties:

• byte stream
• size - length of the byte stream in bytes
  • Note: Although size can be derived from bytes, it's useful to be able to have it up front (for the receiving system to decide to reject an upload based on quota / exceeding max size, etc).
• type (from the IANA mime type registry) - If not specified, defaults to application/octet-stream

When a Blob is stored as a Resource, its type and size are reported as the contentType and size properties of the Resource's Metadata object (see 11.8 Resource Metadata Data Model), and the stored bytes are returned verbatim on reads (see 11.3 Content Types and Representations).

A resource is a named (addressable) Blob stored in a given collection, with metadata. The data model is derived from W3C FileAPI: File Interface, but with the addition of a few crucial properties.

In similar storage systems, a resource is called "File", "Object", "Document", "Row", "Graph", and so on.

Resource properties:

• id - A unique identifier for a resource for a given collection. Created by the server if not provided. Note: the {resource_id} template parameter used in URL templates in this spec MUST match that resource's id property (as returned by the 10.5 List Collection operation).
• name - (optional) - Human-readable name for the resource, useful for building user interfaces for browsing collection contents.
• type (optional) - An array of strings describing the resource. Unlike Space and Collection, no specific type value is required of a Resource.
• url (optional) - A relative URL (provided by the server when listing resources via the 10.5 List Collection operation)
• contentType (optional) - The MIME type of the default representation of the resource (provided by the server when listing resources via the 10.5 List Collection operation)
• Each Resource also has an associated Metadata object -- server-managed properties (contentType, size, optional timestamps) plus user-writable ones (name and tags, nested under custom) -- addressable at the reserved /meta path segment under the Resource URL. See 11.8 Resource Metadata Data Model.

A Resource has exactly one current representation: the stored bytes plus the content type they are stored under. Every successful write (POST or PUT) replaces that representation entirely -- including replacing a representation previously stored under a different content type. Servers are not required to store, convert between, or negotiate multiple representations of a Resource.

Writing. A Resource write request MUST carry a Content-Type header; a server MUST reject a write without one with a missing-content-type (400) error. The request body is interpreted according to its content type:

• JSON -- a content type of application/json, or any type with a +json structured-syntax suffix [RFC6839] (for example, application/ld+json), is stored as a JSON document.
• Raw binary (support REQUIRED) -- any other content type is stored as an opaque byte stream (see 11.1 Blob Data Model), verbatim, under the supplied content type. Clients with no more specific type SHOULD use application/octet-stream.
• Multipart upload (support OPTIONAL) -- a server MAY additionally accept multipart/form-data [RFC7578] uploads (the HTML form workflow). The request MUST contain exactly one file part; that part supplies the stored bytes, and its own content type (not multipart/form-data) becomes the stored content type. Because a write targets a single Resource, there is no batch form: a server MUST reject a multipart request with no file part, or with more than one, with an invalid-request-body (400) error.

Reading. A GET returns the current representation, verbatim, with the stored content type as the response Content-Type. Because Resources are single-representation, the request's Accept header is advisory: a server MAY ignore it, and MUST NOT reject a Resource read for lack of an acceptable representation (no 406 Not Acceptable) -- the stored representation is always the answer. A HEAD request returns the same headers without the body; the response Content-Type and Content-Length correspond to the contentType and size properties of the Resource's Metadata object (see 11.8 Resource Metadata Data Model).

Description objects. API documents generated by the server -- Space and Collection descriptions, listings, quota reports, Metadata objects -- MUST be available as application/json. Linkset documents use application/linkset+json [RFC9264], and error responses use application/problem+json [RFC9457] (see 6. Error Handling). Other representations of these documents (negotiated via Accept) MAY be offered in addition to, never instead of, the JSON baseline.

A read returns the Resource's single stored representation, with the stored content type; see 11.3 Content Types and Representations for content type and Accept header handling (including the HEAD variant).

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-type: application/json

{"message":"hi"}

When creating or modifying a Resource via PUT, the client specifies the id of the Resource. This Resource id MUST NOT collide with the list of B.2 Collection-level reserved endpoints.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{"message":"hi"}

HTTP/1.1 204 No Content

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{"message":"no I've changed my mind"}

HTTP/1.1 204 No Content

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/photos/sunset.png HTTP/1.1
Host: example.com
Content-Type: image/png
Digest: mh=uEiCPO-qYr-z0GYV5F75-N1l8Rhjv4xIkKZsnbTZeZ7emSA
Authorization: ...

...binary PNG bytes...

HTTP/1.1 204 No Content

Each Resource has an associated Metadata object, addressable at the reserved /meta path segment under the Resource URL (one of the B.3 Resource-level reserved endpoints). The metadata endpoints are OPTIONAL; a server that does not implement them SHOULD return an unsupported-operation (501) error for requests to /meta paths.

The Metadata object is a JSON document containing two groups of properties:

• Server-managed properties appear at the top level of the Metadata object. They are maintained by the server as a side effect of Resource write operations and are read-only: the 11.10 Update Resource Metadata Operation cannot change them.
• User-writable properties are nested under the custom property and are set by the client via the 11.10 Update Resource Metadata Operation. Keeping them in their own object makes the writable surface explicit and leaves the top level free for future server-managed properties.

Server-managed properties (contentType and size are REQUIRED in every Metadata object; the timestamps and createdBy are OPTIONAL):

• contentType - The MIME type of the stored representation of the Resource, recorded from the Content-Type header of the request that last wrote the Resource's content (application/octet-stream if none was provided). The same value is reported in 10.5 List Collection operation results and as the Content-Type header of GET/HEAD responses for the Resource itself.
• size - The length in bytes of the stored representation of the Resource (see the size property of the 11.1 Blob Data Model).
• createdAt (optional) - The [RFC3339] date-time at which the Resource was created.
• updatedAt (optional) - The [RFC3339] date-time at which the Resource's content or user-writable metadata was last modified.
• createdBy (optional) - The did of the party whose capability invocation created the Resource. It is recorded on the first write and preserved unchanged by later writes, so it names the creator rather than the last writer -- in a Collection written by several delegated agents, createdBy and the party responsible for the current content need not be the same. Like the other server-managed properties it is read-only: it cannot be set through the 11.10 Update Resource Metadata Operation. Recording it is OPTIONAL, so a client MUST treat an absent createdBy as "not recorded" rather than as an assertion that the Resource has no creator.

User-writable properties:

• custom (optional) - A JSON object holding the user-writable properties below. A Metadata object with no user-writable properties set MAY omit custom or report it as {}.
  • name (optional) - A human-readable name for the Resource. This is the same name property defined in the 11.2 Resource Data Model.
  • tags (optional) - A JSON object of application-defined annotations. Keys are strings chosen by the application; values SHOULD be strings, so that tags stay cheap to index and filter on. Applications that need richer structured metadata SHOULD store it as a Resource in its own right rather than in tags.

On a Collection that declares an encryption marker (see C. Encryption Scheme Registry), the user-writable custom object is stored encrypted: its value is an envelope of the Collection's declared scheme (the same envelope profile used for a Resource's content). The server-managed top-level properties (contentType, size, the timestamps, and createdBy) remain plaintext -- the server needs them for listings, GET/HEAD headers, quotas, and, in the case of createdBy, because it is the very identity the server authenticated on the creating write. The server validates the custom envelope structurally on write (rejecting a plaintext custom with an encryption-scheme-mismatch) and never decrypts it; a client holding the keys decrypts custom back to { name, tags, ... } after reading. Because the server cannot read an encrypted name, 10.5 List Collection operation summaries for an encrypted Collection carry no name.

A Resource's Metadata object is created and deleted together with the Resource itself: it comes into existence (with only server-managed properties) when the Resource is created and is removed when the Resource is deleted. There is no DELETE /meta operation; to clear the user-writable properties, send a PUT with an empty custom object ({ "custom": {} }) or an empty body object ({}).

A PUT to the /meta endpoint is a full replacement of the Metadata object's custom object: the stored custom object is replaced by the one in the request body, so any user-writable property omitted from it is cleared (and a request body with no custom property clears them all). Server-managed properties are not affected by this operation; a server MUST ignore any top-level properties other than custom present in the request body (so that a client may read the Metadata object, modify it, and PUT it back without first stripping the server-managed properties).

Unlike the 11.6 Update (or Create By Id) Resource Operation, a PUT to /meta does not create anything: a Metadata object cannot exist apart from its Resource, so a PUT to the /meta path of a nonexistent Resource returns a not-found (404) error.

PUT /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/hello-world/meta HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: ...

{
  "custom": {
    "name": "Hello World greeting",
    "tags": { "project": "demo", "status": "draft" }
  }
}

HTTP/1.1 204 No Content

The space linkset resource (one of the B.1 Space-level reserved endpoints), located at /space/{space_id}/linkset contains a set of links to auxiliary resources and extension points:

• policy relation (https://wallet.storage/spec#policy) - A link to the /space/{space_id}/policy resource, which contains a set of links to access control policy documents.
• backends-available (https://wallet.storage/spec#backends-available) - A link to the /space/{space_id}/backends "Backends Available" resource.
• quotas relation (https://wallet.storage/spec#quotas) - A link to the /space/{space_id}/quotas per-backend storage quota report (see 14. Quotas).
• /space/{space_id}/query - Reserved for cross-space query operations.

Example space linkset resource request and response:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset HTTP/1.1
Accept: application/linkset+json
Authorization: ...

Response:

HTTP/1.1 200 OK
Content-type: application/linkset+json

{
  "linkset": [
    {
      "anchor": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e",
      "https://wallet.storage/spec#policy": [
        { 
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/policy",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#backends-available": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/backends",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#quotas": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/quotas",
          "type": "application/json"
        }
      ]
    }
  ]
}

The collection linkset resource (one of the B.2 Collection-level reserved endpoints), located at /space/{space_id}/{collection_id}/linkset contains a set of links to auxiliary resources and extension points:

• The policy relation (https://wallet.storage/spec#policy) - A link to the /space/{space_id}/{collection_id}/policy resource, which contains a set of links to access control policy documents.
• backend relation (https://wallet.storage/spec#backend) - A link to the detailed /space/{space_id}/{collection_id}/backend "Backend Selected for this collection" resource.
• quota relation (https://wallet.storage/spec#quota) - A link to the /space/{space_id}/{collection_id}/quota storage quota report for this collection (see 14. Quotas).
• /space/{space_id}/{collection_id}/query - (Optional) Query operations within a collection, discriminated by a request-body profile (see D. Query Profile Registry).

Example collection linkset resource request and response:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/linkset HTTP/1.1
Accept: application/linkset+json
Authorization: ...

Response:

HTTP/1.1 200 OK
Content-type: application/linkset+json

{
  "linkset": [
    {
      "anchor": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages",
      "https://wallet.storage/spec#policy": [
        { 
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/policy",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#backend": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/backend",
          "type": "application/json"
        }
      ],
      "https://wallet.storage/spec#quota": [
        {
          "href": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/messages/quota",
          "type": "application/json"
        }
      ]
    }
  ]
}

A Backend description object advertises a backend's identity and features so that clients can select a suitable backend for each Collection (and so that storage management UIs can present meaningful choices to users).

Backend description properties:

• id (required) - A unique backend identifier (within a given space). The id default is conventionally used for the server-assigned default backend. See 4. Identifiers for additional constraints.
• name (optional) - An arbitrary human-readable name for the backend. Does not have to be unique.
• managedBy (optional) - Who operates the backend. One of:
  • server - configured and operated server-side (for example, the server's filesystem or database backends). This is the default if unspecified.
  • external - a "Bring Your Own Storage" provider registered by the client (for example, a connected Dropbox account).
• storageMode (optional) - An array of storage modalities the backend supports. This specification defines two values: document (structured JSON resources) and blob (opaque binary byte streams). Advertising modalities up front prevents mismatches, such as attempting to store a multi-gigabyte binary file on a JSON-only document store. If unspecified, clients SHOULD assume both modalities are supported.
• persistence (optional) - Either durable (the engine stores data on persistent media, e.g. disk, and it survives a restart) or volatile (the engine stores data in memory, e.g. a RAM-backed cache tier, and data may not survive a restart). Defaults to durable. Note that this is a technical property of the storage engine, deliberately distinct from any administrative data-retention rules (see the editor's note on lifecycle configuration below).
• features (optional) - An array of feature tokens advertising optional server affordances the backend provides beyond the baseline read/write API, so that clients can gate behavior on what the backend actually does. The vocabulary is open and additive: a client MUST ignore tokens it does not recognize, and MUST treat an absent token (or an absent features array) as "not supported" rather than assuming a default. Tokens this specification defines:
  • conditional-writes - the backend enforces If-Match / If-None-Match write preconditions (see 7.2 Conditional Requests).
  • changes-query - the backend serves the changes profile of the query endpoint (see D. Query Profile Registry).
  • blinded-index-query - the backend serves the blinded-index profile of the query endpoint (see D. Query Profile Registry).
  • chunked-streams - the backend supports chunk addressing for large blobs.

Each token names something the server must actively do. Note that client-side encryption is deliberately not a backend feature: an encrypted document is opaque client-encrypted JSON that any document-capable backend stores faithfully with no server cooperation, and whether a given Collection is encrypted varies per Collection on the very same backend. Encryption is therefore a property of a Collection's data (signaled at the Collection level and held in the client's keys), not a capability of the backend. Concretely, this signal is the Collection's optional encryption marker (see 10.1 Collection Data Model): a non-secret declaration any authorized reader discovers from the Collection Description, while the keys stay in the client.

A backend that advertises conditional-writes takes on the server-side half of the client contract in 7.2 Conditional Requests. It MAY derive the ETag from an internal monotonic version counter (such as an Encrypted Data Vault document sequence); the validator is opaque to clients. It MUST evaluate a write's If-Match / If-None-Match precondition atomically with the write (for example, under a per-Resource lock), so that two concurrent writers cannot both observe the same prior version and both succeed. An in-process per-Resource lock satisfies this for a single-instance server only; a horizontally-scaled deployment needs to coordinate the check-and-write across instances (e.g. an atomic compare-and-swap on the stored version or a shared lock).

The list of backends registered on a Space is discoverable via the backends-available relation in the linkset (see 12.1 Space Linkset).

Example request:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/backends HTTP/1.1
Accept: application/json
Authorization: ...

Example success response:

HTTP/1.1 200 OK
Content-type: application/json

[
  {
    "id": "default",
    "name": "Server Filesystem",
    "managedBy": "server",
    "storageMode": ["document", "blob"],
    "persistence": "durable"
  },
  {
    "id": "dropbox",
    "name": "Dropbox",
    "managedBy": "external",
    "storageMode": ["blob"],
    "persistence": "durable"
  },
  {
    "id": "edv",
    "name": "Encrypted Data Vault",
    "managedBy": "server",
    "storageMode": ["document", "blob"],
    "persistence": "durable",
    "features": ["conditional-writes", "blinded-index-query", "chunked-streams"]
  }
]

Each collection has an optional backend property that is set during its creation (see 10.1 Collection Data Model). If not specified, it is assumed to have the id of default. The selected backend is discoverable via the backend relation in the collection's linkset (see 12.2 Collection Linkset).

Returns the storage report for a Space, grouped by backend, and is discoverable via the quotas relation in the Space's linkset (see 12.1 Space Linkset). Each entry in the backends array carries:

• id, name, managedBy - identifying properties from the corresponding Backend description object (see 13.1 Backend Data Model).
• state - the backend's current condition, one of: ok, near-limit, over-quota, or unreachable.
• usageBytes - total bytes consumed on this backend by this Space.
• limit - an object with capacityBytes and an isUnlimited boolean (when isUnlimited is true, capacityBytes MAY be omitted).
• constraints (optional) - operational constraints such as maxUploadBytes, the largest single upload the backend accepts.
• restrictedActions - an array of actions (uppercase HTTP verbs, the same vocabulary as the WAS Authorization Profile, see 5.1.5 Authorization Actions and the Root Capability) currently unavailable on this backend. For example, a full backend reports ["POST", "PUT"] while still permitting reads and deletes.
• measuredAt - when the usage numbers were measured. For external ("Bring Your Own Storage") backends, the server proxies the provider's reported numbers, which may be cached or stale; measuredAt lets clients judge freshness independently of the report's top-level respondedAt.

Example request:

GET /space/81246131-69a4-45ab-9bff-9c946b59cf2e/quotas HTTP/1.1
Accept: application/json
Authorization: ...

Example success response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "respondedAt": "2026-06-12T13:25:00Z",
  "backends": [
    {
      "id": "default",
      "name": "Server Filesystem",
      "managedBy": "server",
      "state": "ok",
      "usageBytes": 524288000,
      "limit": { "capacityBytes": 10737418240, "isUnlimited": false },
      "restrictedActions": [],
      "measuredAt": "2026-06-12T13:25:00Z"
    },
    {
      "id": "dropbox",
      "name": "Dropbox",
      "managedBy": "external",
      "state": "near-limit",
      "usageBytes": 314572800,
      "limit": { "capacityBytes": 367001600, "isUnlimited": false },
      "constraints": { "maxUploadBytes": 157286400 },
      "restrictedActions": [],
      "measuredAt": "2026-06-12T13:24:45Z"
    }
  ]
}

With the include=collections query parameter, each backend entry additionally carries a usageByCollection array, giving storage-manager applications a full breakdown in a single request while keeping the hot-path payload lean:

HTTP/1.1 200 OK
Content-type: application/json

{
  "respondedAt": "2026-06-12T13:25:00Z",
  "backends": [
    {
      "id": "default",
      "name": "Server Filesystem",
      "managedBy": "server",
      "state": "ok",
      "usageBytes": 524288000,
      "limit": { "capacityBytes": 10737418240, "isUnlimited": false },
      "restrictedActions": [],
      "measuredAt": "2026-06-12T13:25:00Z",
      "usageByCollection": [
        { "id": "credentials", "usageBytes": 419430400 },
        { "id": "inbox", "usageBytes": 104857600 }
      ]
    }
  ]
}

Returns the storage report for a single Collection, scoped to that Collection's backend (the entry has the same shape as a backends array entry, with usageBytes reflecting only this Collection's consumption). It is discoverable via the quota relation in the Collection's linkset (see 12.2 Collection Linkset).

Not all backends support per-collection accounting. Where unsupported, the server returns an unsupported-operation (501) error.

Errors (see E. Error Type Registry for canonical examples):

• not-found (404) -- the Space or Collection does not exist, or the caller is not authorized to read the quota report.
• unsupported-operation (501) -- the Collection's backend does not support per-collection quota accounting.