POST/blobs/{blobId}/attachment-bindings
Bind or replace a blob attachment
Operation blobs.attachmentBindings.bind
Description
Attaches an encrypted blob to an attachment slot in a document, or replaces the slot's current binding, through a signed attachment.bind event. When it names a blob stage, the server assembles and verifies the staged upload and promotes it to committed blob storage; this is the only way to complete an upload. Requires write access through an authorizing container path; a stale binding or path head returns 409, and an organization without active billing returns 402.
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 |
|---|---|---|---|
blobId | path | string | required |
Request body
application/jsonBlobAttachmentBindRequest
A signed attachment.bind: puts a blob in a document slot, optionally completing a blob stage and committing the document's first update.
7 fields
Container paths that authorize the write; the API resolves the document link-set manifest itself.
bodyany JSON valuerequiredSigned bind body naming the binding, blob, document, slot, replaced binding, and document manifest hash.
- at most 16 items
Container rekeys to commit first in the same transaction.
The document's first queued update, committed with the bind under every check a standalone sync makes.
eventobject with any fieldsrequiredThe blob stage to promote; absent when binding a blob that is already committed.
Other fields are allowed.
Responses
200 OK
application/jsonBlobAttachmentBindResponse
Acknowledges a bind by hash, so the client can compare it with what it signed.
11 fields
bindingIdstringrequiredblobIdstringrequiredcontentKeyEpochintegerrequired- greater than 0
Content-key epoch the API stored for the blob.
documentIdstringrequireddocumentManifestHashstringrequiredDocument link-set manifest head the bind was checked against.
eventHashstringrequired- not empty
Hash of the signed bind event.
previousBindingIdstringrequirednullableBinding this one replaced in the slot, or null.
slotIdstringrequiredwriteHeaderHashstringrequiredHash of the stored blob write header.
documentSyncobjectoptionalPresent exactly when the request carried
documentSync; names the accepted update.3 fields
acceptedOutgoingUpdateIdslist of stringrequired- at most 1 item
- each item: not empty
commitLsnstringrequirednullablecommitLsnModestringrequired- one of
tracked,untracked
- one of
Other fields are allowed.
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.
An attachment bind's document sync must contain exactly one outgoing update and no container rekeys, and serialize within the document sync request limit.
inlineRekeyCommitIdmust be present exactly whencontainerRekeysis non-empty.authorizingContainerPathRefsis required whenoutgoingUpdatesis non-empty.containerRekeysmay be non-empty only whenoutgoingUpdatesis non-empty.Outgoing update ids must be unique within the request.
A request carrying
pullCursormust not contain outgoing updates, container rekeys, a content-key bundle, or authorizing paths.historyMode"raw" must not be combined with outgoing updates, container rekeys, a content-key bundle, or authorizing paths.historyMode"raw" requireslocalVersionVectorto be null so the complete retained history is requested.checkpointKind,checkpointPayloadKind, andsourceVersionVectormust be absent together or form a rotation baseline.