List Capsules
const url = 'https://example.com/vault/alpha/workspaces/example/engines/example/capsules';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/vault/alpha/workspaces/example/engines/example/capsulesLists the capsules a workspace has sent. Never the payloads.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The workspace whose capsules will be listed.
Vault engine selector. - federates across every engine.
Query Parameters
Section titled “Query Parameters ”The maximum number of capsules to return. The service may return fewer than this value. If unspecified, at most 20 capsules will be returned. The maximum value is 100; values above 100 will be coerced to 100.
A page token, received from a previous ListCapsules call.
AIP-160 filter expression.
Partial matches (:, a quoted wildcard, contains/startsWith/endsWith) ignore capitalisation; = and the relational operators are exact.
Filterable fields: content_type, create_time, end_time, engine, expire_time, id, location_id, name, payload_size_bytes, source_secret_version_id, state, update_time, workspace_id.
AIP-132 order_by expression. Sortable fields: create_time, end_time, engine, expire_time, name, state, update_time.
AIP-158 offset mode: number of resources to skip from the start of the filtered, sorted set. Use EITHER skip (offset paging) OR page_token (cursor paging) — never both in the same request. Supplying both is an invalid request. Default 0 (no skip).
Responses
Section titled “ Responses ”OK
List Capsules Response
One page of capsules, a cursor for the next page, and the exact number matching the request’s filter and scope.
object
The capsules in this page.
Capsule resource: a single-use delivery of a small secret payload to a recipient who holds a link.
The payload is never a field of this message. It is returned exactly once, by RedeemCapsule, to the caller who presents the authorising half of the split token; every other read returns metadata only.
object
The unique identifier of the capsule (UUID).
This is also the PUBLIC half of the split token: it is opaque and server-assigned, so it is safe in an access log and is the only half the anonymous lookup needs.
The workspace the capsule was created in (UUID, weak reference to taxonomy).
Present on the sender’s view only. The recipient is not entitled to know which tenant sent the delivery, so the anonymous lookup returns a different message entirely rather than a redacted copy of this one.
The vault engine holding the payload.
Weak reference to a topology Location where the capsule resides. Defaults to the global location when omitted; immutable after creation.
A short, sayable handle for this capsule, e.g. swift-otter-3f9a21c4.
Server-generated and never client-supplied. A capsule is the one resource whose identifier is also a security boundary, so a sender-chosen handle would be a second way to name the same delivery — and the obvious choices are exactly the strings that must not become guessable.
The SENDER’s handle. The recipient never sees it: a label for a delivery is the sender’s business, and is the kind of context that should not reach whoever holds a guessed identifier.
The capsule’s current state.
Optional IANA media type of the payload, so the recipient has something to render it by. Defaults to application/octet-stream when omitted.
Size of the payload in bytes.
The deadline. After this instant the capsule is swept to EXPIRED and the payload destroyed, whether or not anyone collected it.
The secret version the payload was snapshotted FROM at creation, when the capsule was created from a stored secret rather than from inline bytes.
Audit only. It is never resolved again at redemption — rotating the source secret afterwards does not change what this capsule delivers.
When the capsule reached a terminal state. Absent while it is active.
Creation timestamp (server-managed).
Last modification timestamp (server-managed).
A token to retrieve the next page, or empty when this is the last page.
The exact number of capsules matching the request’s filter and scope.
Example
{ "capsules": [ { "engine": "VAULT_ENGINE_UNSPECIFIED", "state": "CAPSULE_STATE_UNSPECIFIED" } ]}default
Section titled “default ”Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
object
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
A list of messages that carry the error details. There is a common set of message types for APIs to use.
Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
object
The type of the serialized message.
Example generated
{ "code": 1, "message": "example", "details": [ { "@type": "example" } ]}