# SetGet
Account-free ephemeral UTF-8 key/value API. Same-origin paths below; use the user's explicitly selected base URL. Never default tool calls to production.

- Full contract: /openapi.json (OpenAPI 3.1). Human docs: /docs. Console: /console. Changes: /static/changelog.md.
- Create random key: POST /v1/keys with JSON {"value":"text","capabilities":true,"ttl_seconds":3600,"ttl_mode":"absolute"}. Save returned id and capabilities.read_token/capabilities.write_token; tokens appear only once.
- Authentication: Authorization: Bearer <credential>. Writer also reads. Read capability cannot mutate/renew/consume. Query password remains supported but avoid secrets in URLs. Protected keys without sufficient access return 403; malformed v1 Authorization returns 401.
- Read: GET /v1/keys/:key returns metadata and string value. ?format=raw returns exact text/JSON. HEAD and /meta inspect without renewal/consumption.
- PUT /v1/keys/:key writes exact UTF-8 body (Content-Type text/plain or application/json). If-None-Match: * creates only. If-Match: "ETag" updates that version only; conflicts 412. DELETE returns 204, missing 404.
- PATCH uses application/merge-patch+json and exact If-Match (required, otherwise 428): objects merge, null members remove, arrays/scalars replace. Fetch a fresh ETag before retrying conflicts; never blindly replay mutations.
- POST /v1/keys/:key/touch with {} or TTL options renews within absolute deadline. Never revives expired keys.
- Default/max TTL 31,536,000 seconds (365 days), configurable. Sliding by default; authorized writer/public GET renews after >5% TTL. Read-only capability, HEAD and meta do not renew. Absolute is opt-in, cannot be removed/extended. Legacy cache hits do not renew database expiry.
- v1 limit: 50,000 UTF-8 bytes by default; empty text/whitespace preserved. Legacy SET: 50,000 Unicode characters, trims ordinary text. Binary and literal NUL are unsupported (v1 400 invalid_value); encode Base64 explicitly within limits. JSON decimal/exponent notation must decode to finite double precision; overflowing exponents return 400 invalid_json.
- POST /v1/batch: {"operations":[{"method":"GET","key":"..."}]} up to 25 GET/PUT items, 1 MiB whole request, sequential/non-atomic, per-item status/body/headers. Shares request credential; do not assume rollback on partial failure.
- Counters use existing POST /incr/:key and /decr/:key?by=1; signed 64-bit integers, min/max clamps. Optional history=true enables UTC 168h/90d/24mo aggregates. history=false clears; by=0 toggles. GET /v1/keys/:key/history?resolution=hour supports timezone-aware start/end bucket bounds. Replacements clear history.
- GET /poll/:key?last=<raw-value>&timeout=30 waits (1–90s). 200 changed, 304 no body on timeout/no visible value. Recheck auth; not durable delivery, no SSE.
- Public badges: /badge/:key, /badge/hit/:key (mutates), /badge/status/:key, /badge/progress/:key. /tools/badge lists all options/presets. Thresholds min:color compare raw numeric value or progress percentage. Never put credentials in badge URLs; protected/burn/quarantined/expired data are hidden.
- One-time notes: create with burn:true via POST /v1/keys, explicit absolute TTL. POST /v1/keys/:key/consume requires WRITE access, returns {id,value,content_type,consumed:true} once then 404. GET/HEAD /consume are 405. A lost consume response is unrecoverable.
- Legacy POST /set/:id and GET /get/:id remain supported. Legacy burn=true ignores numeric TTL and uses maximum TTL; legacy GET and implicit HEAD consume. Never preview those burn links. Prefer v1 HEAD/meta for safe checks.
- v1 errors: {"error":{"code":"...","message":"..."}}; legacy errors usually {"error":"..."}. Default limits: 10 requests/s/IP per handler (hit badge 20/s), batch 1/s; set/counters/v1 mutations share 5,000/day/IP. Review API: 5/min and 3/day. Respect Retry-After, use bounded backoff for safe reads, inspect state before retrying uncertain writes/consumption.
- /api/metrics and /stats show aggregates only. Metrics use last five complete minutes and bounded latency estimates, not raw logs. /stream/ws sends one-second aggregate legacy event counts, not every HTTP request. /api/status proxies public uptime monitors.
- No global key listing, accounts, namespaces, SSE, webhook inbox or MCP endpoint. No cross-origin browser CORS grant. Do not store credentials, personal data or prohibited content; capabilities do not make a secrets vault.