Create or fetch a container

Method POST https://<client-api-host>/api/v3.1/containers

Create the container of an order or a savings pot, identified by your reference (crid). The response carries the recording link and the editKey of the first message. Replaying the same crid returns the existing container with 200 and ignores mode, gallery, notifications and the contacts of the body. A crid that belongs to a container created through /api/v3 answers 409 CRID_IN_USE.

Authorization

Required scope containers:write

Use Authorization: Bearer liv_<prefix>_<secret>. The key must belong to a platform served by the V3 pipeline; otherwise every route answers 403 PLATFORM_NOT_V3.

Request body

Required application/json Schema V31CreateContainerRequest

Name	Type	Required	Description
`crid`	`string`	Required	Constraints pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
`mode`	`V31ContainerMode`	Required	`single` holds one message (gift message); `gallery` accepts several (savings pot). Required at creation and immutable afterwards. Values `single` `gallery`
`language`	`string`	Optional	`uid` of a platform language.
`codeGroup`	`string`	Optional	`publicId` of a code group of the platform; ignored when unknown.
`sender`	`V31Sender`	Optional
`recipient`	`V31Recipient`	Optional
`gallery`	`V31GalleryInput`	Optional
`notifications`	`V31Notifications`	Optional
`additionalData`	`object`	Optional	At most 20 keys matching `^[A-Za-z0-9_]{1,40}$`; values are strings (500 characters at most), numbers or booleans. Key names containing `mail` or `phone` are refused.

Responses

200 application/json Schema V31CreateContainerResponse

Container already existed; returned unchanged.

201 application/json Schema V31CreateContainerResponse

Container created.

400 application/json Schema V31ErrorEnvelope

Invalid payload, unknown field or invalid value.

json 400

{
  "error": {
    "code": "DATA_INVALID",
    "message": "Invalid field crid"
  }
}

401 application/json Schema V31ErrorEnvelope

Authentication failed or missing bearer token.

json 401

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key"
  }
}

403 application/json Schema V31ErrorEnvelope

Authenticated but not allowed: missing scope (FORBIDDEN), invalid platform constraints (INVALID_PLATFORM_CONSTRAINTS) or a platform not served by API v3.1 (PLATFORM_NOT_V3).

json 403

{
  "error": {
    "code": "PLATFORM_NOT_V3",
    "message": "Platform is not served by API v3.1"
  }
}

409 application/json Schema V31ErrorEnvelope

The request conflicts with the state of the container or message: CRID_IN_USE, MODE_MISMATCH, GALLERY_CLOSED, GALLERY_NOT_EMPTY, MESSAGE_REJECTED, MESSAGE_MISSING.

json 409

{
  "error": {
    "code": "GALLERY_CLOSED",
    "message": "Gallery is closed"
  }
}

429 application/json Schema V31ErrorEnvelope

Rate limit exceeded.

json 429

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

500 application/json Schema V31ErrorEnvelope

Unexpected server error.

json 500

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}