---
title: "Create an immutable embedded collection only when every declared SDK installation supports the bound schema version. Identical retries return the original submission credential; handle it as a secret."
method: POST
path: "/v1/collections"
---

# Create an immutable embedded collection only when every declared SDK installation supports the bound schema version. Identical retries return the original submission credential; handle it as a secret.

`POST /v1/collections`

## Request

- Base URL: `http://127.0.0.1:8080`
- URL: `http://127.0.0.1:8080/v1/collections`
- Auth: HTTP bearer

## Headers

- `X-Likerts-Workspace` string

## Request body

- CollectionInput
  - `idempotencyKey` string, required
  - `surveyId` string, required
  - `version` integer, required
  - `placement` string, required
  - `expiresAt` string, date-time: Optional future expiry, at most 90 days from creation.
  - `responseCap` integer
  - `sdkCapabilities` SdkCapabilities, required: Customer-declared installed SDK groups. Every group must include the published/bound survey schema version. This is a compatibility guard, not attestation.
    - `installations` SdkInstallationCapability[], required
      - `target` 'web' | 'react_native' | 'ios' | 'android' | 'flutter', required
      - `sdkVersion` string, required
      - `schemaVersions` integer[], required

## Response `201`

Success

- Collection
  - `id` string, uuid, required
  - `surveyId` string, uuid, required
  - `version` integer, required
  - `placement` string, required
  - `token` string, required: Opaque limited collection bearer credential; never parse its format. Returned on creation; cannot manage surveys or read responses.
  - `accepting` boolean, required
  - `expiresAt` string, date-time, nullable, required
  - `responseCap` integer, nullable, required
  - `revoked` boolean, required
  - `sdkCapabilities` SdkCapabilities, required: Customer-declared installed SDK groups. Every group must include the published/bound survey schema version. This is a compatibility guard, not attestation.
    - `installations` SdkInstallationCapability[], required
      - `target` 'web' | 'react_native' | 'ios' | 'android' | 'flutter', required
      - `sdkVersion` string, required
      - `schemaVersions` integer[], required

## Other responses

- `400`: Invalid JSON, unknown fields or domain validation failure.
- `401`: Missing/invalid bearer credential, including wrong collection credential.
- `403`: The credential scope, membership or role does not permit this operation.
- `404`: Resource absent or belongs to another workspace.
- `409`: The workspace already has 100 active collections.
- `413`: Request body exceeds 65536 bytes.
- `415`: Content-Type must be application/json.
- `429`: Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.
- `500`: Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.
- `503`: Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.

---

[API](https://skmtc.dev/likerts/apis/likerts-development-api.md) · [All operations](https://skmtc.dev/likerts/apis/likerts-development-api/llms.txt) · [OpenAPI document](https://skmtc.dev/likerts/apis/likerts-development-api/revisions/c583fa096c07?raw)