POST/containers
Create a container
Operation containers.create
Description
Creates a container from a signed container.create event, its derived access manifest, and the container KEK wrapped to its recipients. Requires write access to the parent container, or admin access for a system container. A retry of a create that already committed returns 409 container_manifest_already_exists, which lets the client adopt it; a stale parent returns 409 container_mutation_state_stale.
Authentication
Requires a signed-in session: the client sends its session token as a bearer token in the Authorization header.
Request body
application/jsonContainerMutationRequest
A signed container mutation (create, share, or the container part of a larger write): the event, the manifest it derives, and the KEK material, citing stored heads instead of resending them.
16 fields
bodyany JSON valuerequiredEvent-type-specific body the signature commits to.
- at most 4,096 items
Earlier manifests of this container the verifier needs, cited by hash.
- at most 100 items
Current path to the new parent, for a move.
eventobject with any fieldsrequiredexpectedManifestHashstringrequired- not empty
Hash of the manifest this mutation derives; the API derives it independently and must agree.
keyEpochobject with any fieldsrequiredThe container KEK epoch this mutation leaves current.
For a KEK rotation, every predecessor KEK sealed under the new KEK; null otherwise.
manifestobject with any fieldsrequired- at most 100 items
Current path to the parent container.
parentKekRefobjectoptionalnullableThe parent's current KEK epoch, for a child container; any other epoch is refused as stale.
3 fields
containerIdstringrequired- not empty
containerKeyEpochIdstringrequired- not empty
keyEpochHashstringrequired- exactly 64 characters
- lowercase hexadecimal
Other fields are allowed.
predecessorBridgeobject with any fieldsrequirednullableFor a KEK rotation, the retiring KEK encrypted under the new one; null otherwise.
- at most 100 items
Current path to the mutated container, from its root.
The container's current manifest head; absent for a create.
Heads of the principal policies the mutation was planned against.
userRecipientKeyslist of object with any fieldsoptionalPublic keys of users the container KEK is wrapped to directly.
wrapslist of object with any fieldsrequiredThe container KEK wrapped to each derived recipient target.
Other fields are allowed.
Responses
200 OK
application/jsonContainerMutationResponse
Acknowledges a container mutation by hash; the client compares each value with the plan it signed and refuses any mismatch.
9 fields
containerIdstringrequiredcreatedAtstringrequiredeventHashstringrequired- not empty
Hash of the signed event the API stored.
manifestHeadobjectrequiredEpoch and hash of the container's new manifest head.
2 fields
epochnumberrequiredmanifestHashstringrequired
Other fields are allowed.
organizationIdstringrequiredparentIdstringrequirednullablesystemSlotstringoptionalnullable- pattern
^sys_v1_[A-Za-z0-9_-]{43}$
Opaque id of a system container's role, or null for an ordinary container.
- pattern
updatedAtstringrequiredcontainerKekobjectrequiredIdentity and hashes of the container's current KEK epoch.
6 fields
containerKeyEpochintegerrequired- greater than 0
containerKeyEpochIdstringrequired- not empty
keyEpochHashstringrequired- not empty
keyringHashstringrequirednullable- not empty
keyTargetHashstringrequired- not empty
parentContainerKeyEpochIdstringrequirednullable
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.
A container response keyring is null exactly for container key epoch 1.