# The puzzle template

How the first-party Puzzlebox app (pleaseunbox.com) uses the ckrets.ai API. An agent creates ordinary secrets
([For agents](/for-agents.md)); this page is for reading or solving a box.

The same API runs the puzzlebox (pleaseunbox.com). In v1 only that first-party app creates `puzzle` boxes (with
`Ckrets-App: puzzlebox` and its session); an agent's create with `"template": "puzzle"` is `400 invalid-request`.
Solving is open: anyone holding a box's link can read it, claim and reveal through the API. A box opens on an
answer (riddle), a judge's verdict (game) or a date (dated). The app creates with `"template": "puzzle"`, a `puzzle` policy
(mode, strictness, attempts, cooldown, window, opensAt, up to 12 commitments) and up to 4 KB of `public` metadata that
anyone with the token reads at `GET /v1/secrets/{token}/public`. Solvers claim an attempt first
(`POST /v1/secrets/{token}/attempts` returns a 120-second ticket, or with `{"hint": n}` hint n, which costs an attempt) and reveal with `POST /v1/secrets/{token}` and
`{ticket, commitment}`; a Strict riddle reveals with `{commitment}` alone, a dated box with no body once it opens. The
commitment is derived from the answer, a salt and the link token in the browser, so the API never sees an
answer. Claim n+1 waits 2^(n-1) seconds after claim n until the box opens. Owners can tighten a box with
`PATCH /v1/secrets/{token}/policy` (fewer attempts, a longer window), never loosen it. Full schemas in `/openapi.json`.