TmpState

# TmpState > Tokenless temporary HTTP state for AI agents. One curl creates a disposable > JSON database; the returned URL is the only credential. No API keys, no > .env, no SDK, no signup. This file is the complete documentation. > Also known as: TempState / temp state / tmp state — same service, https://tmpstate.dev. Machine-readable OpenAPI 3.1 spec: https://tmpstate.dev/openapi.json (also at /.well-known/openapi.json). Every API response carries RFC 8288 Link headers pointing here (rel="help") and at the spec (rel="service-desc"). ## MCP server TmpState is also a remote MCP server: https://tmpstate.dev/mcp (Streamable HTTP, no auth, no OAuth — the zero-key model carries over). Every capability documented in this file is available as a typed MCP tool: create_database, database_status, list_documents, get_document, create_document, update_document, delete_document, delete_collection, delete_database, extend_database, pro_checkout, pro_list_databases, pro_create_database, pro_attach_database, pro_cancel, send_feedback. The complete MCP tool surface, security model and client configs are published for audit at https://github.com/tmpstate/mcp - including a script that diffs that repo against what this server advertises live. Client config (Claude Code, Cursor, and any Streamable HTTP client): {"tmpstate": {"url": "https://tmpstate.dev/mcp"}} For stdio-only clients: {"command": "npx", "args": ["-y", "mcp-remote@0.1.38", "https://tmpstate.dev/mcp"]}. Database URLs are passed as tool arguments; Pro tools take pro_token as an argument or an Authorization: Bearer pt_... header on the connection. If you can fetch URLs but not install MCP servers, ignore this section — the plain HTTP API below is the same surface. ## Create a database curl https://tmpstate.dev (GET only; POST to / returns 405) curl -X POST https://tmpstate.dev/new (/new accepts both GET and POST) curl -H "Idempotency-Key: <stable-project-or-task-key>" https://tmpstate.dev/new Response: 201 { "db": "https://tmpstate.dev/db/s-<capability>", "admin": "https://tmpstate.dev/admin/s-<capability>", "expires_at": "<ISO timestamp, 24 hours from now>", "limits": {"ttl_hours": 24, "max_docs": 100, "max_writes": 100, "max_doc_bytes": 10240}, "docs": "https://tmpstate.dev/llms.txt", "skills": "https://tmpstate.dev/skills", "mcp": "https://tmpstate.dev/mcp" } "db" is the API base URL (the only credential — treat it like a private link). "admin" is a read-only web viewer of the database, for humans. "skills" is an index of agent skills (SKILL.md playbooks) — fetch https://tmpstate.dev/skills/db-design before building an app on this database; it encodes the dos and don'ts of TmpState data modeling, quotas, and app architecture. If a create request might be retried or run by parallel workers, send the same Idempotency-Key each time. Reusing a key from the same client returns the same database URL instead of minting duplicate empty databases. ## Agent playbook If you are an AI agent building an app for a user, treat TmpState as invisible infrastructure. The user-facing product should feel like the product, not like a database console or TmpState demo. 1. Reuse before you create. Check the project for an existing db URL — README.md, docs/, .env, config files, private handoff notes, and your own memory — before creating a new database. Verify it is still alive: curl $DB/__health 200 = alive, 404/410 = expired, create a new one 2. Create early during scaffolding, but create once. If no usable database exists, create one immediately with an Idempotency-Key stable to this project/task and build against real reads/writes from the start. Persist the db URL server-side only (for example in a local env file or server-only config). Store the admin URL and expires_at in developer handoff metadata: README/final response/private notes/dev tooling. Do not put admin lin […truncated]