Create a files kubbi

Create a multi-file kubbi package: multiple files encrypted together with a single claim URL. Same endpoint as a single-content kubbi (Create a kubbi), but with a files array instead of content. The request must contain exactly one of the two, never both.

POST/api/v1/kubbis

Create a multi-file kubbi package. The request must contain files (not content).

Auth: API key (Bearer token)

Parameters

Field	Type	Required	Description
files	array	Yes	File objects (max count and total size depend on your plan)
ttl_seconds	integer	Yes	60 – max depends on your plan
max_retrievals	integer	No	≥ 1 if set; upper bound depends on your plan tier. Omit or null for unlimited within TTL
metadata	object	No	≤ 1 KB serialized

Each file object

Field	Type	Required	Description
name	string	Yes	≤ 255 chars, alphanumeric start, characters limited to `a-zA-Z0-9._-`, no `..` substring, no null bytes, unique within the package (case-insensitive)
content	string	Yes	File content; valid base64 if encoding is "base64"
content_type	string	Yes	Valid MIME format (type/subtype)
role	string	No	`instructions`, `data`, `context`, `config`, or `attachment`
encoding	string	No	Only valid value: `"base64"` (for binary files)

Response 201· json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "claim_url": "https://api.kubbi.ai/r/pkg456xyz",
  "claim_token": "pkg456xyz",
  "status": "active",
  "file_count": 3,
  "total_size_bytes": 1234,
  "max_retrievals": 2,
  "metadata": null,
  "created_at": "2026-03-28T12:00:00.000Z",
  "expires_at": "2026-03-28T13:00:00.000Z"
}