POST/documents/{documentId}/link
Operation documents.link
Description
Links a document into another container through a signed document.link event, advancing its document link-set manifest and rewrapping the content keys of its attached blobs for the new container. Requires write access through the target and authorizing container paths. Stale heads or incomplete rewraps return 409 without changing the document.
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 |
Request body
application/jsonDocumentLinkSetMutationRequest
A signed document.link or document.unlink that changes the containers a document is linked into.
9 fields
Paths through which the caller may write the document now.
bodyany JSON valuerequired- at most 16 items
Container rekeys to commit first in the same transaction.
Content-key bundle for the new link set's targets.
eventobject with any fieldsrequiredexpectedManifestHashstringrequired- not empty
Hash of the link-set manifest this mutation derives.
manifestobject with any fieldsrequiredFor an unlink, a rotation baseline covering every committed update; omitted only when the document has none, and never sent with a link.
- 1 to 100 items
Path to the container being linked or unlinked.
Other fields are allowed.
Responses
200 OK
application/jsonDocumentLinkSetMutationResponse
Acknowledges a link or unlink by hash.
5 fields
contentKeyEpochintegerrequired- greater than 0
eventHashstringrequired- not empty
idstringrequiredmanifestHashstringrequired- not empty
Hash of the new document link-set manifest head.
targetHashstringrequired- not empty
Key target hash the API derived for the new link set.
Other fields are allowed.
Other responses
| Status | Meaning | Body |
|---|---|---|
| 400 | Bad Request |
|
| 401 | Unauthorized |
|
| 402 | Payment Required |
|
| 403 | Forbidden |
|
| 404 | Not Found |
|
| 409 | Conflict |
|
| 500 | Internal Server Error |
|
| 503 | Service Unavailable |
|
Additional rules
The server also enforces these rules, which the schema above cannot express.
authorizingContainerPathRefsandtargetContainerPathRefsmay contain at most 6400 references in total.checkpointKind,checkpointPayloadKind, andsourceVersionVectormust be absent together or form a rotation baseline.