---
title: "Store sealed Memory Crystal envelope (2 MiB max; ChaCha20-Poly1305 / AES-256-GCM)"
method: POST
path: "/crystals"
---

# Store sealed Memory Crystal envelope (2 MiB max; ChaCha20-Poly1305 / AES-256-GCM)

`POST /crystals`

## Request

- Base URL: `https://api.whitemagic.dev`
- URL: `https://api.whitemagic.dev/crystals`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-WM-Key`
  - API key in header `X-PAYMENT`

## Request body

- object
  - `spec` string: Crystal envelope specification version
  - `crystal_id` string, required: Content address: sha256:<64 hex> of the decoded ciphertext bytes
  - `parent_crystal_id` string, nullable: Optional parent crystal content address in lineage DAG
  - `tenant_hash` string, required: Authenticated owner locator returned by GET /crystals/owner-locator
  - `cipher` 'chacha20-poly1305' | 'aes-256-gcm', required: AEAD cipher suite used to seal the crystal
  - `nonce` string, required: base64url-encoded 12-byte AEAD nonce
  - `ciphertext` string, required: base64url-encoded sealed ciphertext including authentication tag
  - `size_bytes` integer: Decoded byte length of ciphertext (must equal len(decoded ciphertext))
  - `created_at` string, required: RFC 3339 creation timestamp bound in AEAD AAD
  - `metadata_public` object: Optional non-sensitive public metadata
  - `kek_version` integer: Optional client Key Encryption Key (KEK) version wrapping wrapped_dek (I1/I2)
  - `id_kek_version` integer: Optional initial KEK version bound into crystal_id = sha256(id_kek_version_be32 || nonce || ciphertext)
  - `wrapped_dek` string: Optional base64url-encoded 60-byte AEAD-wrapped per-crystal DEK (12B nonce + 32B DEK + 16B tag)

## Response `201`

crystal stored

- object
  - `stored` boolean, required
  - `crystal_id` string, required
  - `parent_crystal_id` string, nullable
  - `tenant_hash` string, required
  - `size_bytes` integer, required
  - `service` string, required

## Other responses

- `400`: invalid JSON or shape
- `401`: missing or invalid key
- `403`: crystal owner mismatch (envelope tenant_hash does not match authenticated owner)
- `413`: crystal exceeds the size limit
- `429`: Daily cap reached (Retry-After: 86400; X-RateLimit-* report the bucket)

---

[API](https://skmtc.dev/whitemagic/apis/whitemagic-receipt-verification-api.md) · [All operations](https://skmtc.dev/whitemagic/apis/whitemagic-receipt-verification-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whitemagic/apis/whitemagic-receipt-verification-api/revisions/92a4341eb473?raw)