Create a container with its metadata document | API reference

Description

Creates a container and its encrypted metadata document in one transaction, optionally seeding the document's first update. Authorization and conflicts are those of POST /containers and POST /documents; a 409 document_manifest_already_exists may have rolled the new container back, so clients treat it as terminal unless they verify both artifacts.

Authentication

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

Request body

application/jsonContainerCreateWithMetadataDocumentRequest

Creates a container together with its encrypted metadata document.

4 fields

containerContainerMutationRequestrequired
metadataDocumentobjectrequired
8 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
Other fields are allowed.
systemSlotstringoptionalnullable
- pattern ^sys_v1_[A-Za-z0-9_-]{43}$
initialMetadataSyncDocumentSyncRequestoptional
The metadata document's first queued update, committed in the same transaction.

Other fields are allowed.

Responses

200 OK

application/jsonContainerCreateWithMetadataDocumentResponse

Acknowledges a container and its metadata document.

2 fields

containerContainerMutationResponserequired
metadataDocumentDocumentCreateResponserequired

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`ErrorResponse
409	Conflict	`application/json`ContainerMutationFailureResponse
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 container response keyring is null exactly for container key epoch 1.
A container create metadata 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.