Limits

Limits are per tier, enforced per caller, and published here and at GET /v1/limits. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Ckrets-Tier. Errors are application/problem+json. A create the API refuses (400, 413, 428, 429) spends none of your creates. Every window is fixed, not rolling: the clock hour and the day, both in UTC. All times are UTC. Every time in a body is RFC 3339 with Z and whole seconds (2026-10-24T01:11:09Z), and every window resets on the UTC clock. A 429 with Retry-After means slow down (rate-limited, retryable: true); a 429 without it means stop until resetsAt or mint a key (quota-exhausted, retryable: false). A tier past its daily budget returns 503 with Retry-After; signed and keyed tiers never see that 503. A 503 with no Retry-After and no problem body comes from the platform in front of the API: usually it shed the load and nothing was done, but a write (a create, a reveal, a revoke) that ran past the platform's 15-second limit may have happened, so after a write check as for outcome: "unknown" before you send it again; after a read, wait 2 seconds and retry. Two 503 temporarily-unavailable answers both carry Retry-After: tell them apart by the problem body, never by the header. retryable: true with no outcome means nothing was done; outcome: "unknown" (with retryable: false) means a write may have happened, so read the call in check before you send it again. Every TTL default is 7 days, on every tier. Earlier values and every revision of this page are dated in the changelog.

Scroll the table sideways: one column per tier.

The per-address counters count an address, not a caller: callers behind one NAT or one shared egress address share them (an IPv6 caller is counted by its /64). The per-network counters cover the whole IPv4 /24 or IPv6 /48 around that address, so neighbours on one network share those too.

#How limits change

Limits are policy, not part of the API's compatibility promise: the shapes of calls never narrow inside /v1; the numbers in the table can. A change is published here with a dated line and at GET /v1/limits 30 days before it applies. A response to abuse (the first-month review) applies at once and is published the same day. Secrets already stored keep their size and expiry.

#How a limit shows up

HTTP/2 429
content-type: application/problem+json
retry-after: 2
ratelimit-limit: 5
ratelimit-remaining: 3
ratelimit-reset: 2
ckrets-tier: anonymous

{ "type": "https://ckrets.ai/problems/rate-limited",
  "title": "Wait before the next attempt",
  "status": 429,
  "limit": "revealAttempts",
  "retryable": true,
  "retryAfter": 2 }

HTTP/2 429
content-type: application/problem+json
ratelimit-limit: 300
ratelimit-remaining: 0
ratelimit-reset: 46800
ckrets-tier: anonymous

{ "type": "https://ckrets.ai/problems/quota-exhausted",
  "title": "No creates left today",
  "status": 429,
  "limit": "createsPerDay",
  "retryable": false,
  "resetsAt": "2026-10-25T00:00:00Z",
  "detail": "Mint a free key at POST /v1/keys to continue now." }

The hour's refusal has the same shape: limit createsPerHour, title "No creates left this hour", resetsAt the next whole hour. A network's ceiling names netCreatesPerHour or netCreatesPerDay. A key's names createsPerDay. None carries Retry-After: each is a stop until resetsAt, not a slow-down.

A create the API refuses as invalid (400, 413) is checked before anything is counted, so it spends none of your creates; a create refused by one limit (429) gives back what the others took, so it spends nothing either; a throttled one (503) gives back what it took. An agent that reads RateLimit-Remaining on each response never needs to see a 429. An agent that plans more than a few calls should call GET /v1/limits first, or mint a free key with POST /v1/keys. SDK default retry policies treat every 429 as transient; ours says which it is, so a client that honours retryable never retry-storms a spent quota.

At the door, before the API (measured in a load test): the edge refuses more than 300 creates a minute from one address (POST /v1/secrets and POST /mcp together) with a plain 403 (no problem body, no RateLimit-* headers), so one address bursting creates meets the 403 before any 429; a batch belongs in POST /v1/batches, not a loop. Under a flood the anonymous tier pauses (503 tier-budget-exhausted with Retry-After) while keyed agents keep working (14 of 14 creates and reveals beside a flood of 108,000 creates a minute): an agent that matters holds a free key. The edge has a second rule: more than 100 requests a minute from one address to one /v1/secrets/… path (a reveal, a status, a public view) is the same plain 403. Every request counts toward these two, whatever its outcome and whoever sends it: the door counts by address and never sees a key, so keyed and CI callers behind one address count together. A door 403 is CloudFront's own page, never application/problem+json: an API 403 always has a problem body with a type. A door 403 lifts once the address's rate falls back under the limit (a minute or two); wait, then slow down.

RateLimit-* on a reveal describe the token's attempt budget (limit follows the creator's tier: 5 for a secret made anonymously, 10 for one made with a free key; remaining attempts left, reset the seconds of cooldown left). On every other route they describe the caller's tightest create limit (an anonymous address's hour or day, a key's day). There is no in-flight figure.

Only an anonymous create is ever refused for the tier's daily budget (on /v1 and /mcp) or for a stamp (on /v1). While the anonymous tier is paused, reveals, status, revokes, /public, key mints, reports, GET /v1/limits and GET /v1/me/key all still work, and none of them needs a stamp. Of these, GET /v1/limits, status, /public and GET /v1/me/key also spend nothing.

What each call spends, in one place:

Scroll the table sideways.

#Errors, retries and headers

Every error from the API is application/problem+json with type (a stable URI: branch on it), title (for people; it varies with the cause, so never parse it), status and requestId. retryable and retryAfter appear on every 429 and 503, and on the two 409s about an Idempotency-Key (idempotency-in-progress: retryable: true, with Retry-After; idempotency-key-retired: false); any other status has neither and is final for that request: change something before you send it again. Every type, with what to do:

Scroll the table sideways.

The first-party apps' routes (Puzzlebox's boxes, template: puzzle) and later versions add these:

Scroll the table sideways.

A reveal is not idempotent. Each reveal is claimed by one conditional write: with N reveals left, exactly N of any number of callers at once get the value, and the rest get 410. Once its claim is written the reveal is spent, even if the answer never reaches you (a dropped connection, a timeout, a 200 you never read), and nothing fetches a value again. The value's key and the receipt are made ready before the claim, so a failure in either spends nothing (503 key-unavailable or a retryable 503), except on a Strict riddle box, where an attempt whose commitment was already checked stays counted (never the box). Past the claim nothing else can fail the reveal: a value whose deletion fails is deleted by the next hourly sweep. After a 503 with outcome: "unknown", never resend blindly: read the call in check first, then send it again at most once, and only if the check says nothing was spent. A reveal whose answer was lost, worked through:

HTTP/2 503
content-type: application/problem+json
retry-after: 1

{ "type": "https://ckrets.ai/problems/temporarily-unavailable",
  "title": "Busy: the outcome is unknown",
  "status": 503,
  "retryable": false,
  "outcome": "unknown",
  "check": "GET /v1/secrets/{token}/public",
  "retryAfter": 1 }

Read GET /v1/secrets/{token}/public (it reads consistently, as status does, so a claimed reveal always shows). revealsLeft the same as before your reveal: nothing was spent; reveal again, once. revealsLeft lower, or state revealed: the reveal was spent and its answer lost, so the value is gone; ask the sender to create again. On a secret with several reveals, another recipient may have revealed meanwhile, so /public cannot say whose reveal it was: only the creator's status (revealedAt, and revealedBy for an audience) says who. A puzzle claim or open is checked the same way, by /public's state and attemptsLeft; the same commitment sent again answers as the first time and spends nothing.

The puzzle template and the first-party apps have their own types (not-yet-open 425, ticket-invalid, verdict-invalid and session-invalid 401, proof-required 401 or 403, policy-widening 409, hint-out-of-range 422, void-not-allowed 403); the planned calls add batch-too-large, webhook-unverified and domain-unverified. A type you do not know: treat it by its status.

Which refusal comes first. Every call: a write that is not JSON (415), then a bad Authorization header (401 invalid-credentials), then a key's missing scope on a reveal, status or revoke (403 scope-missing). A create: its form (400, 413) before any limit (503, 428, 429); a key without create is 403 after the form checks and before any limit, so it spends nothing. A reveal: a token that will not reveal (410), then the audience proof (403), then the cooldown (429, the same answer whatever passphrase is sent, right or wrong, and nothing counted), then the passphrase (401). So a token with an audience and a passphrase answers 403 to a stranger whatever passphrase is sent, and a token that is gone (revealed, expired, revoked, frozen or out of attempts) answers 410 to everyone before any proof is read: that 410 records no denial and no deny receipt, whatever proof was sent.

Every response from the API carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Ckrets-Tier and Ckrets-App (the door's 403 and the platform's 503 carry none), and every answer from the API carries Ckrets-Request-Id, the id to quote in a report (a problem's requestId is the same). A key minted with clientEncryptionRequired: true (or switched on with PATCH /v1/me/key; it cannot be switched off) refuses every value it would hand over in the clear with 400 plaintext-refused: plain creates, creates through the hosted MCP server, and requests (their answers are sealed by ckrets). Every create's 201 carries Ckrets-Encryption: client when the value arrived encrypted on your side (clientEncrypted: true), server when ckrets sealed it, which means ckrets could read it; the receipt's ce claim says the same. HEAD answers like GET (the same status and headers, no body) on GET /v1/limits, /.well-known/jwks.json and the public views (/v1/secrets/{token}/public, /v1/requests/{requestId}/public), for uptime probes; never on a reveal. Every answer is Cache-Control: no-store and the CDN never caches /v1/*, so a reveal is never served from a cache. Browsers on other sites get no CORS grant, on /v1 and /mcp alike (only the first-party apps' own origins are allowed; agents are not browsers), and a write must be JSON, so no web page can make a visitor's browser create, mint or call /mcp for it.

Every answer also carries Ckrets-Version: YYYY-MM-DD, the dated contract it follows (2026-11-06, the beta launch date, is the first and only one). A request may send Ckrets-Version to name the contract it was written for; a date this server does not serve is 400 version-unknown, listing the dates it does. A request without the header gets the original contract. A new date comes only with a breaking change (an added field, value or call never makes one), it is announced in /changelog.md, and an old date is served for at least 12 months after the next is published. The path stays /v1. The helper, the SDKs and the MCP tools send the date they were built against.

#Requests to a person

POST /v1/requests makes a page (/q/<requestId>) that asks a person for one value on behalf of a key. Anyone with a free key can make one, so the page is treated as a phishing surface and these limits are tighter than a create's:

Scroll the table sideways.

The page always shows the same notice above the input, which no request can change: "This request was made by an API key, not by ckrets. ckrets never asks for your email, bank or ckrets passwords. Only answer if you know who is asking and why." Then the key's label, its domain (marked unverified in v1) and its id. The prompt is kept with the request only (for its own life and the 30 days after), and never written to our logs.

#The proof-of-work stamp

On the HTTP API, anonymous tier only. A create normally needs none. When the tier is busy (more than 20 anonymous creates a second across the whole tier, whoever sends them), a create without a good stamp answers 428 with problem type proof-of-work-required and a fresh stamp: {alg: "sha256", difficulty, nonce, expiresAt} in its body (one is also in GET /v1/limits). Every 428 carries a new stamp with a new nonce, never the one you sent: solve the stamp in the latest answer. Find a counter (a decimal number from 0, at most 15 digits) such that sha256(nonce + ":" + counter) has difficulty leading zero bits, then resend the create with the header Ckrets-Proof: stamp=<nonce>:<counter>. The difficulty is 11 bits by default (about 10 ms in Node); it never changes with load: only the operator sets it, as a limit, so a change is announced like any limit (on /limits.md and in GET /v1/limits, 30 days ahead, except in answer to abuse). Always read difficulty from the stamp you were given, never hard-code it. A stamp is good only at the difficulty it was issued with, so a change voids outstanding stamps. The stamp's network is narrower than the per-network counters' on IPv6 on purpose: a stamp is bound to what one caller holds (an IPv6 /64, the unit a per-address limit counts; an IPv4 /24, so an egress pool's rotation keeps it), while the counters use a /48 to catch a pool spread over a whole site's subnets. A stamp is not single use: it is good for any number of creates until its expiresAt (120 s after issue), from the network it was issued to (IPv4 /24, IPv6 /64, so a rotating egress pool keeps it), each create still counted. Any stamp that fails (missing, malformed, too weak, expired, from another network, or issued before a difficulty change) is answered the same way: 428 again with a new stamp, never 400. When the tier is not busy a stamp is not read at all, so sending one does no harm. One caller over its own rate gets 429, not 428: the 428 depends only on the tier's load. Signed and keyed callers never need a stamp. On /mcp there is no stamp; the anonymous tier there has the same rates.

#What a create checks

Every check below runs before anything is counted or spent, so a refused create costs nothing. Nothing is ever clamped to fit: a request over a limit is refused, never shortened.

Scroll the table sideways.

The TTL starts at create: expiresAt is the create's time plus ttl, cut down to the whole second (so a TTL can run up to a second short, never long); a reveal never extends it. A token reveals while the service clock is before expiresAt; at expiresAt it is 410. The claim's write decides: a reveal claimed before expiresAt returns the value even if the answer leaves after it.

#Why these numbers

Content is never inspected (the platform is content-blind, and no-view when the client encrypts), so the limits are the control. The anonymous tier is sized to what a one-time hand-off needs and no more: 1 KB holds any credential, 7 days covers a hand-off that will be collected this week, and one reveal is the product. Those caps also make the tier a poor staging post for anything else, which is the lesson of every anonymous drop box before it. The per-IP and per-key rates bound what one caller can do; the tier budget bounds what the anonymous tier can cost; the attempt cap and cooldown make a passphrase worth having; audience binding is available on every tier because a token only its recipient can open is worth nothing to anyone else. The signed-agent tier exists so that a cooperative agent can be accountable without an account: its operator's domain publishes the key. The numbers are a starting point and will be tuned from the first month's measurements; changes are announced with a date in /changelog.md (linked from /llms.txt; a status page at /status is planned). If the anonymous tier is abused, the next step is that minting a key needs a passkey-signed human or a signed agent; the anonymous call itself stays small and fast to take down by token.

#Apps on the same platform

The ckrets.ai API is the unlock service under every product. Limits are rows per (app, tier): the table above is the agent API's (app: api, the default). First-party apps call the same API from their own domains through a CORS allow-list, send Ckrets-App, and bring their own anonymous proof (Ckrets-App counts only on an app's own routes: on a plain create, keys, report, status or revoke it is ignored and the answer is api's); GET /v1/limits returns the row that applied, and every response carries Ckrets-App beside Ckrets-Tier.

Scroll the table sideways.

In v1 the puzzle template (riddle, game and dated boxes) belongs to first-party apps (Ckrets-App: puzzlebox); opening it to agents on the api rows is a later addition. A puzzle box's attempts follow its own policy: each claim counts when made, hints cost an attempt each (every claim of one, the same hint again included), and claim n+1 waits 2^(n-1) seconds after claim n (1, 2, 4, 8, 16 s) until the box opens; a cooldown refusal is not counted.

#Alarms

These events are visible in status, and, once webhooks are built (planned), also delivered to keyed and signed callers as signed webhooks: a reveal attempted after the last permitted one (secret.consumed_attempt), a secret that expired without being revealed (secret.expired_unrevealed), a denied reveal (secret.reveal_denied: wrong passphrase, wrong audience), and a revocation. They are the two questions a sender has after an incident: did the right party get it, and did anyone else try.

#What we keep, and for how long

Never the value after its last reveal or expiry, and never a value the client encrypted. The Public API is what runs today; the Enterprise API is planned, and its column is what it will follow, not something it does yet.

Scroll the table sideways.

The Enterprise API's logging follows PCI DSS, HIPAA and SOC 2 rules: a complete audit trail of every access and administrative action, protected from change, kept for the periods those rules require, under a contract (a BAA for health data). It is planned: the health tier opens in early 2027 and PCI DSS validation is upcoming.

Logs never hold a value, a digest key, a passphrase, a key, a CI OIDC token, the Authorization header, a manage token or a token: the API's request log records no headers, no path and no query (only its route key), and an error log keeps only the path, with any token in it masked. The CDN and the door in front of the API keep no access log, so no token in a path is logged at the edge either. /mcp keeps no session: the Mcp-Session-Id it hands out is random and never stored. The address hash in a secret's record uses one service-wide secret salt, which is not rotated, so one address hashes the same way for the 13 months the metadata is kept. This metadata is what a lawful request or an abuse report gets. Apps built on ckrets publish their own retention.

#When deleted means deleted

Two promises, each with its bound:

• One secret. A revoke or the last reveal removes the value at once: no reveal can return it after that answer. Copies leave our backups within 7 days (the tables' point-in-time recovery window).
• A whole account. At contract end the account's data key is deleted. Every running instance stops being able to open its secrets within the key cache's lifetime: about 5 minutes when ckrets holds the key, about 60 seconds when the customer does. Backups clear within 7 days. When the customer's own KMS key is destroyed, AWS's record of that is the proof.

That cache lifetime is also how long a revoked or disabled key takes to stop working everywhere.

Each value is sealed under a data key of its own, made from the account's data key, which our KMS key wraps. Every stored item names its key version and algorithm, so a key can be rotated (new values seal under the new version, and a background pass moves the rest) without a secret becoming unreadable. A secret's status shows encryption.custody (ckrets today) and encryption.dedicatedKey; neither can be set on a create.

#Prohibited uses and reports

Malware staging, exfiltration of data you are not entitled to move, anything unlawful where you or the recipient are. POST /v1/report takes a token or URL and a reason (required: at most 2,000 characters; without one it is 400) and answers a case id, the same whether or not the token exists. A bearer token is frozen pending review (a review lifts it), so anyone holding its URL can freeze it: name an audience when that matters. In v1 there is no call to lift a freeze or to ask for a review, and no review time is promised: a sender whose token was frozen revokes it with the manage token and sends a new one. An audience-bound token is recorded, not frozen, since its audience already keeps strangers out. In v1 the creator sees a report in status (reports, frozen, lastCase); webhooks are planned. One report per token per address counts once; 10 reports an hour per address. Takedown is by token. The beta terms and privacy page say the rest. The points of contact for the EU Digital Services Act and the UK Online Safety Act are not published yet; until they are, reach us about content with POST /v1/report.