Get a document writer projection | API reference

Description

Returns everything a client needs to read and write a document: its document link-set manifest history, the authorizing container paths with their KEK wraps and keyrings, and the key targets. Requires current read access; write authority is checked again when a write commits. A vanished container is reported as 409, never 404, because 404 here means the document itself was deleted.

Authentication

Requires a signed-in session: the client sends its session token as a bearer token in the Authorization header.

Parameters

Name	In	Type	Details
`documentId`	path	string	required
`x-known-manifests`	header	string	optional at most 3,215 characters Comma-separated typed digests the device holds verified: m:<manifest hash> for an access-manifest bundle, k:<level digest> for a container KEK level; at most 48, unique

Responses

200 OK

application/jsonDocumentWriterProjectionWireResponse

A document writer projection: its link-set history, authorizing container paths with KEK levels, and key targets. Every manifest is carried once in bundles and cited by hash.

12 fields

bundlesmap of string to AccessManifestBundleWireResponserequired
Signed manifest bundles keyed by manifest hash.
omittedBundleslist of stringrequired
- each item: not empty
Cited hashes left out because the request said the client holds them.
policyEvidenceProjectionPolicyEvidenceResponserequired
Public principal policy history the cited manifests depend on.
authorizingContainerPathslist of objectrequired
- at least 1 item
Each linked container's path from the root, with one KEK level per manifest.
4 fields
- containerIdstringrequired
- containerKekslist of one of: CitedContainerKekLevel, objectrequired
  1. CitedContainerKekLevel
  2. object
    12 fields
    accessManifestHashstringrequired
    not empty
    containerIdstringrequired
    containerKeyEpochintegerrequired
    greater than 0
    containerKeyEpochIdstringrequired
    not empty
    containerManifestHistorylist of stringrequired
    each item: not empty
    keyEpochobject with any fieldsrequired
    keyEpochHashstringrequired
    not empty
    keyringContainerKekKeyringWireRecordrequirednullable
    keyTargetHashstringrequired
    not empty
    parentContainerKeyEpochIdstringrequirednullable
    recipientTargetslist of object with any fieldsrequired
    at least 1 item
    wrapslist of object with any fieldsrequired
    at least 1 item
    Other fields are allowed.
- organizationIdstringrequired
- pathlist of stringrequired
  - at least 1 item
  - each item: not empty
Other fields are allowed.
contentKeyBundleDocumentContentKeyBundleResponserequired
contentKeyBundleStalebooleanoptional
- always true
Present only when the stored content-key bundle targets superseded KEKs and must be rewrapped.
documentContainerManifestHistorylist of stringrequired
- each item: not empty
documentIdstringrequired
documentKekTargetsDocumentKekTargetsResponserequired
documentManifeststringrequired
- not empty
Hash of the current document link-set manifest.
documentManifestContainerPathslist of list of stringrequired
- each item: each item: not empty
documentManifestHistorylist of stringrequired
- each item: not empty
Hashes of earlier document link-set manifests.

Other fields are allowed.

202 Accepted

application/jsonPrincipalHistoryPreparationResponse

A 202: the operation rolled back while the server prepares principal history. Retry the identical request.

3 fields

codestringrequired
- always principal_history_preparation_pending
committedbooleanrequired
- always false
progressTokenstringrequired
- exactly 64 characters
- lowercase hexadecimal
Changes when preparation advances; clients stop after three identical tokens in a row.

Other responses

Status	Meaning	Body
400	Bad Request	`application/json`ErrorResponse
401	Unauthorized	`application/json`SessionFailureResponse
403	Forbidden	`application/json`ErrorResponse
404	Not Found	`application/json`DocumentNotFoundErrorResponse
409	Conflict	`application/json`DocumentWriterProjectionErrorResponse
500	Internal Server Error	`application/json`ErrorResponse
503	Service Unavailable	`application/json`ErrorResponse

Additional rules

The server also enforces these rules, which the schema above cannot express.

containerKeks must contain exactly one entry for every manifest in path.
A container response keyring is null exactly for container key epoch 1.
Every cited manifest hash names one bundles entry, every bundles key equals its bundle's manifestHash, and every bundle is cited.
X-known-manifests must list at most 48 unique typed digests, each m: or k: followed by a lowercase SHA-256 hex digest.