Create a document | API reference

Description

Creates a document from a signed document access event, its document link-set manifest, and its content-key bundle, optionally committing the document's first encrypted update in the same transaction. Requires write access to the target container through an authorizing container path. A retry of a create that already committed returns 409 document_manifest_already_exists, which lets the client adopt it.

Authentication

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

Request body

application/jsonDocumentCreateRequest

A signed document create: the document's first link-set manifest, its content-key bundle, and optionally its first encrypted update.

9 fields

authorizingContainerPathRefsContainerManifestRefArrayArrayoptional
bodyany JSON valuerequired
containerRekeyslist of ContainerMutationRequestoptional
- at most 16 items
contentKeyBundleDocumentContentKeyBundleRequestrequired
eventobject with any fieldsrequired
expectedManifestHashstringrequired
- not empty
manifestobject with any fieldsrequired
targetContainerPathRefslist of ContainerManifestRefoptional
- 1 to 100 items
initialSyncDocumentSyncRequestoptional
The document's first queued update, committed in the create transaction under every check a sync makes.

Other fields are allowed.

Responses

200 OK

application/jsonDocumentCreateResponse

Acknowledges a document create by hash.

7 fields

contentKeyEpochintegerrequired
- greater than 0
Content-key epoch the API stored.
eventHashstringrequired
- not empty
Hash of the signed event.
idstringrequired
manifestHashstringrequired
- not empty
Hash of the committed document link-set manifest.
targetHashstringrequired
- not empty
Key target hash the API derived.
createdAtstringrequired
initialSyncobjectoptional
Present exactly when the request carried a seed; names the accepted update and its commit position.
3 fields
- acceptedOutgoingUpdateIdslist of stringrequired
  - at most 1 item
  - each item: not empty
- commitLsnstringrequirednullable
- commitLsnModestringrequired
  - one of tracked, untracked
Other fields are allowed.

Other fields are allowed.

Other responses

Status	Meaning	Body
400	Bad Request	`application/json`ErrorResponse
401	Unauthorized	`application/json`SessionFailureResponse
402	Payment Required	`application/json`PaymentRequiredErrorResponse
403	Forbidden	`application/json`ErrorResponse
404	Not Found	`application/json`DocumentMutationFailureResponse
409	Conflict	`application/json`DocumentMutationFailureResponse
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.

A document create seed must contain exactly one outgoing update and no container rekeys, and serialize within the document sync request limit.
inlineRekeyCommitId must be present exactly when containerRekeys is non-empty.
authorizingContainerPathRefs is required when outgoingUpdates is non-empty.
containerRekeys may be non-empty only when outgoingUpdates is non-empty.
Outgoing update ids must be unique within the request.
A request carrying pullCursor must 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" requires localVersionVector to be null so the complete retained history is requested.
checkpointKind, checkpointPayloadKind, and sourceVersionVector must be absent together or form a rotation baseline.