Albums and lifecycle writes

Generated from capsule-server/openapi.json, the OpenAPI 3.2 document capsule-server emits and mise run openapi-check-kynos keeps current. To change a description on this page, change the annotation on the handler or model it comes from and regenerate — this file is build output. The auth model, error contract, and conventions common to every endpoint are on the REST API overview.

POST /v1/albums

Bind an album id to the authenticated caller.

Idempotent: the same id from a second device, or after a recovery, is a success that writes nothing.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.

Request body (required, application/json): ProvisionAlbumRequest

Status	Body	Description
200	ProvisionAlbumResponse application/json	The album id was already provisioned to this account; nothing was written. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
201	ProvisionAlbumResponse application/json	The album was created and bound to the caller. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	CodedProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
415	CodedProblem application/problem+json	Unsupported Media Type. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
422	CodedProblem application/problem+json	Unprocessable Entity. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
426	CodedProblem application/problem+json	Protocol version unsupported. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

POST /v1/albums/{album_id}/capabilities

Mint a capability letting one peer server pull one album.

The token is in the response and nowhere else: this server keeps the record, never the credential.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.
album_id	path	string	Required. The album’s id.

Request body (required, application/json): MintCapabilityRequest

Status	Body	Description
201	MintedCapabilityResponse application/json	The capability was minted. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	CodedProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
404	CodedProblem application/problem+json	Not found. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
409	CodedProblem application/problem+json	Member not on roster. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
415	CodedProblem application/problem+json	Unsupported Media Type. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
422	CodedProblem application/problem+json	Unprocessable Entity. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
426	CodedProblem application/problem+json	Protocol version unsupported. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

DELETE /v1/albums/{album_id}/capabilities/{jti}

Revoke one capability of one album.

Idempotent, and silent about what it did: a jti that is not a live capability of this album — never issued, already revoked, or another album’s — is the same 204 a revocation is, so the operation is not a probe over identifiers.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.
album_id	path	string	Required. The album’s id.
jti	path	string	Required. The capability’s jti.

Status	Body	Description
204	—	the request succeeded and there is no content to send. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	CodedProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
404	CodedProblem application/problem+json	Not found. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
426	CodedProblem application/problem+json	Protocol version unsupported. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

POST /v1/albums/{album_id}/ops

Apply one signed lifecycle manifest to an album’s asset.

The whole battery runs before anything is written, and a rejection writes nothing — including the blobs the bundle carries, which are stored only after the manifest has passed every check the server can make without a key.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.
album_id	path	string	Required. The album’s identifier.

Request body (required, application/json): OpRequest

Status	Body	Description
200	OpResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	CodedProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
409	StaleRevivalProblem application/problem+json	Stale revival. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
415	CodedProblem application/problem+json	Unsupported Media Type. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
422	CodedProblem application/problem+json	Unprocessable Entity. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
426	ProtocolRangeProblem application/problem+json	Upgrade required. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

PUT /v1/albums/{album_id}/roster

Publish the caller’s roster for one of their albums.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.
album_id	path	string	Required. The album’s id.

Request body (required, application/json): RosterRequest

Status	Body	Description
200	RosterResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	RosterVersionLeapProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
404	CodedProblem application/problem+json	Not found. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
409	RosterStaleProblem application/problem+json	Roster stale. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
415	CodedProblem application/problem+json	Unsupported Media Type. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
422	CodedProblem application/problem+json	Unprocessable Entity. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
426	CodedProblem application/problem+json	Protocol version unsupported. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

GET /v1/albums/{album_id}/upgrade

Read the ceremony’s phase and the drain count.

The one call a proposer polls between steps 2 and 4. in_flight reaching zero is the signal that the tombstone may be committed.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.
album_id	path	string	Required. The album’s id.

Status	Body	Description
200	UpgradePhaseResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	CodedProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
404	CodedProblem application/problem+json	Not found. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

POST /v1/albums/{album_id}/upgrade

Put an album into upgrade quiescence.

Idempotent under its own intent_id: versioning.md is explicit that the same UpgradeIntent never produces two forks, and a proposer that lost an acknowledgement re-POSTs the same bytes.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.
album_id	path	string	Required. The album’s id.

Request body (required, application/cbor): string

Status	Body	Description
200	UpgradePhaseResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	CodedProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
404	CodedProblem application/problem+json	Not found. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
409	CodedProblem application/problem+json	Upgrade in flight. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
415	CodedProblem application/problem+json	Unsupported media type. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
426	CodedProblem application/problem+json	Protocol version unsupported. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

DELETE /v1/albums/{album_id}/upgrade

Abort a ceremony, returning the album to normal operation.

Named by intent_id in the path’s own query so that aborting is a statement about which upgrade — a caller that does not hold the live id gets a 409 rather than the power to cancel somebody else’s ceremony.

Authentication: required — bearer.

Parameter	In	Type	Description
X-Capsule-Crypto-Suite	header	integer	The crypto suite id from the primitives inventory. Sent on writes; a suite this server does not implement is refused with 400.
X-Capsule-Protocol	header	string	Required. The YYYY-MM-DD protocol version this request is written against. Outside the server’s [X-Capsule-Protocol-Min, X-Capsule-Protocol-Max] window the request is refused with 426.
X-Capsule-Sidecar-Schema	header	integer	The sidecar schema version declared at sidecar_schema field 0. Sent on metadata updates; a schema newer than this server indexes is refused with 400.
album_id	path	string	Required. The album’s id.
intent_id	query	string	Required. The ceremony to abort.

Status	Body	Description
200	UpgradePhaseResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
400	CodedProblem application/problem+json	Bad Request. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
401	CodedProblem application/problem+json	Unauthorized. Headers: WWW-Authenticate, X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
403	CodedProblem application/problem+json	Forbidden. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
404	CodedProblem application/problem+json	Not found. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
409	CodedProblem application/problem+json	Upgrade in flight. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
426	CodedProblem application/problem+json	Protocol version unsupported. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
500	CodedProblem application/problem+json	Internal server error. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

Schemas

The models these endpoints carry. A field whose type names another model links to it when this page documents that model, which it does when some path from an operation reaches it within 4 references. A model only ever reached deeper than that is named without being expanded.

CodedProblem

An RFC 9457 problem detail.

Field	Type	Description
type	string	Required.
title	string	—
status	integer	Required.
detail	string	—
instance	string	—
code	string	Required. The stable error.* catalog code. The client localizes this; detail stays English. Present on every problem this server renders.

ManifestEnvelope

The server-visible mirror of the signed manifest’s envelope fields, as declared at POST /v1/upload.

Strict (deny_unknown_fields) like the rest of the transport JSON. The Postel asymmetry the design draws — tolerant inside documents that outlive us, strict on the wire we own — puts unknown-key tolerance in the signed CBOR interiors, never in this JSON projection.

Field	Type	Description
crypto_suite_id	integer	Required. The crypto suite the blob was sealed under. Must equal the top-level declaration.
protocol_version	string	Required. The protocol date the manifest was written under (YYYY-MM-DD).
album_id	string | null	The album the asset belongs to. Must equal the top-level declaration.
file_id	string	Required. The asset this blob belongs to — the same id across the bundle’s members.
amk_version	integer	Required. The album-key epoch the manifest was written under.
ciphertext_hash	string	Required. The ciphertext content hash, lowercase hex. Must equal the top-level hash. This names the blob this session is uploading, not the manifest’s own ciphertext_hash. For the original the two coincide; for a metadata or provenance session they do not, and the projection reuses the manifest’s field name for a per-blob declaration. Invisible for a create, because the bundle is assembled in a pending row nobody can see and no member has to name another. It is not invisible for a replace, which is why [Self::original_blob_hash] exists (S-C43).
plaintext_size	integer	Required. The plaintext length the manifest commits to.
chunk_size	integer	Required. The STREAM plaintext chunk size.
key_mode	string	Required. derived or wrapped.
metadata_blob_hash	string | null	The content hash of the bundle’s metadata blob, when the manifest commits to one.
original_blob_hash	string | null	The content hash of the bundle’s original blob, when the manifest commits to one (S-C43). The manifest’s own ciphertext_hash, under a name that cannot be confused with [Self::ciphertext_hash]‘s per-session meaning. Optional on the wire and required on a replace: a replace re-points roles that already have bytes, so it has to be applied as one act, and the only member of the bundle that can carry the whole change is the manifest — which therefore has to be able to name the original it commits to. A create may omit it. Its bundle is assembled incrementally in a row nobody can see, so no member needs to name another and requiring it would be a wire change for no gain.
created_by_user	string	Required. The account that created the asset.
created_by_device	string	Required. The device that created it, as a UUID — invariant 7’s subject.
client_version	string	Required. The client build that wrote the manifest.
timestamp	string	Required. The manifest’s self-asserted RFC3339 timestamp — invariants 7 and 8’s subject.
action	string	Required. The lifecycle action. create or replace on this surface — the two that move blob bytes — and see [GateReject::ActionNotAllowed] for the rest.
prior_provenance_hash	string | null	The provenance chain position this write continues from.
retention_until	string | null	The retention floor the manifest carries, when it carries one.

MintCapabilityRequest

The mint request.

Field	Type	Description
peer	string	Required. The peer server the grant is for, as its own server-info names it (other.tld).
member	string	Required. The roster member whose access the grant carries, as the owner listed them.
scope	WireScope	Required. What the grant permits.
ttl_seconds	integer | null	How long one token should live, in seconds. Clamped to the 24-hour ceiling; absent is six hours.
renewable_until	string | null	The absolute deadline the whole grant dies at, RFC 3339 — and the only thing that makes it renewable. Absent, the default, is a grant that cannot be refreshed at all: it lives exactly ttl_seconds and then the owner mints again if they still mean to share. Present, it must be in the future and at most ninety days out.

MintedCapabilityResponse

A freshly minted capability.

The token is returned once. Nothing on this server can produce it again — a stored grant re-signs byte-for-byte, but only the refresh operation does that, and only for its holder.

Field	Type	Description
token	string	Required. The signed capability, to be carried as Authorization: Bearer.
jti	string	Required. Its identifier, and the key it is revoked by.
album_id	string	Required. The album it scopes to.
peer	string	Required. The peer it was minted for.
member	string	Required. The roster member whose access it carries.
scope	WireScope	Required. What it permits.
issued_at	string	Required. When it was minted, RFC 3339.
expires_at	string	Required. When this token stops being honoured, RFC 3339.
not_after	string	Required. When the whole grant dies, RFC 3339. Equal to expires_at when it is not renewable.
renewable	boolean	Required. Whether a refresh may issue a successor from this grant. Stated plainly rather than left to be inferred from the two timestamps above: how long an owner is sharing for is the decision this response reports back to them.
min_protocol_version	string	Required. The album’s pinned protocol date, which the peer must speak to pull.

OpRequest

The signed manifest bundle a lifecycle write carries.

Field	Type	Description
manifest_envelope	ManifestEnvelope	Required. The server-visible projection of the signed manifest’s fields, exactly as POST /v1/upload carries it. Its album_id must equal the path segment and its action must be one this surface accepts.
manifest_cbor	string	Required. The signed manifest itself, base64 of the canonical CBOR. Stored verbatim as the asset’s new provenance blob, so the feed serves the exact bytes the client signed (S-C30) for a lifecycle write as it already does for an upload. The server does not parse it: base64 is a transport encoding, and decode(encode(b)) == b.
metadata_blob	string | null	The encrypted metadata blob, base64, present exactly when the action carries one. Its content hash must equal the manifest’s committed metadata_blob_hash (invariant 25). The server holds no key and never reads it.

OpResponse

What a lifecycle write did.

Field	Type	Description
asset_id	string	Required. The asset the op chained onto.
sync_seq	integer	Required. The feed position it occupies. On a replay, the position the first application took.
action	string	Required. The action that was applied.
replayed	boolean	Required. Whether this response is a replay of an already-applied manifest. Advisory, and deliberately not something a correct client needs: the other three fields are identical either way, which is what “byte-identical prior response” means.

ProtocolRangeProblem

An RFC 9457 problem detail.

Field	Type	Description
type	string	Required.
title	string	—
status	integer	Required.
detail	string	—
instance	string	—
code	string	Required. The stable error.* catalog code. The client localizes this; detail stays English. Present on every problem this server renders.
protocol_min	string	The oldest protocol date this server still speaks (YYYY-MM-DD).
protocol_max	string	The newest protocol date this server speaks (YYYY-MM-DD).

ProvisionAlbumRequest

The provisioning request.

Field	Type	Description
album_id	string	Required. The client-derived album id, as a canonical lowercase hyphenated UUID.

ProvisionAlbumResponse

What provisioning did.

Field	Type	Description
album_id	string	Required. The album, echoed.
protocol_version	string	Required. The protocol date the album is pinned to — the server’s, fixed at creation.
created	boolean	Required. Whether this call created the album. Advisory; both answers mean the same thing.

RosterRequest

The publish request.

Field	Type	Description
roster_cbor	string	Required. The signed roster, as standard base64 of its canonical CBOR encoding.

RosterResponse

What the server now holds for the album.

Field	Type	Description
album_id	string	Required. The album, echoed.
roster_version	integer	Required. The roster version the server holds after this call.
amk_epoch	integer	Required. The AMK epoch that roster reflects.
member_count	integer	Required. How many members the held roster names, the owner excluded.
replayed	boolean	Required. Whether this call was a replay of the roster already held. Advisory: both answers mean “the server holds this roster”.

RosterStaleProblem

An RFC 9457 problem detail.

Field	Type	Description
type	string	Required.
title	string	—
status	integer	Required.
detail	string	—
instance	string	—
code	string	Required. The stable error.* catalog code. The client localizes this; detail stays English. Present on every problem this server renders.
current_version	integer	The roster version the server holds. A client re-syncs and republishes above it.

RosterVersionLeapProblem

An RFC 9457 problem detail.

Field	Type	Description
type	string	Required.
title	string	—
status	integer	Required.
detail	string	—
instance	string	—
code	string	Required. The stable error.* catalog code. The client localizes this; detail stays English. Present on every problem this server renders.
current_version	integer	The roster version the server holds; 0 when it holds none.
max_version	integer	The highest version this album would have accepted. A client re-signs the same roster at current_version + 1; a version nothing could supersede would freeze the album’s membership.

StaleRevivalProblem

An RFC 9457 problem detail.

Field	Type	Description
type	string	Required.
title	string	—
status	integer	Required.
detail	string	—
instance	string	—
code	string	Required. The stable error.* catalog code. The client localizes this; detail stays English. Present on every problem this server renders.
chain_head	string | null	The manifest hash the asset’s chain is actually at. Absent when the conflict is not a chain conflict, which is why it is nullable.

UpgradePhaseResponse

The ceremony this album is in, as a client polls it.

Field	Type	Description
album_id	string	Required. The album, echoed.
intent_id	string | null	The ceremony in flight, or absent when the album is in normal operation. Absent also covers expired: the deadline passing aborts the upgrade, so there is nothing left to be in.
to_protocol_version	string | null	The protocol version the fork will be pinned to, when a ceremony is in flight.
expires_at	string | null	When the window closes, RFC 3339, on the server’s clock.
in_flight	integer	Required. How many upload sessions are still in flight against this album. The drain signal of versioning.md step 3: the proposer waits for zero. A count rather than a listing, because the proposer needs to know whether to wait and has no business seeing other members’ upload identifiers to find out.

WireScope

What a capability permits, on the wire.

A mirror of [Scope] rather than the type itself, for the reason WireBlobRole is one: the domain enum is not a schema type, and the wire spelling is a contract that should not move when an internal name does.

One of: read, read-derivative-only.