{ "openapi": "3.1.0", "info": { "title": "TmpState", "version": "1.0.0", "summary": "Tokenless temporary JSON database for AI agents.", "description": "One curl creates a disposable JSON database; the returned URL is the only credential. No API keys, no .env, no SDK, no signup. Databases expire after 24 hours. Agent playbook and prose documentation: https://tmpstate.dev/llms.txt. Also available as a remote MCP server (Streamable HTTP, no auth): https://tmpstate.dev/mcp" }, "externalDocs": { "description": "Agent documentation (llms.txt)", "url": "https://tmpstate.dev/llms.txt" }, "servers": [ { "url": "https://tmpstate.dev" } ], "paths": { "/new": { "get": { "operationId": "createDatabase", "summary": "Create a database", "description": "Also available as GET / with a non-HTML Accept header (curl gets a database; browsers get the landing page). POST / is not supported — use /new for POST.", "responses": { "201": { "description": "Database created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponse" } } } }, "429": { "description": "Creation rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createDatabasePost", "summary": "Create a database (POST form)", "responses": { "201": { "description": "Database created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponse" } } } }, "429": { "description": "Creation rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } } ], "get": { "operationId": "getDatabaseHelp", "summary": "Endpoint listing and curl examples for this database", "responses": { "200": { "description": "Help JSON." }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDatabase", "summary": "Delete the whole database immediately", "description": "Irreversible. Requires ?confirm=true. No quota cost; works even after expiry. Use it if the URL leaked.", "parameters": [ { "name": "confirm", "in": "query", "required": true, "description": "Must be the string 'true' to proceed with this irreversible delete.", "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "Deleted." }, "400": { "description": "Missing confirmation (?confirm=true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/{collection}": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "description": "Collection name. Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$; must not start with __ or be a reserved word (admin, new, health, db, api, skills). Created implicitly on first write.", "schema": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } } ], "get": { "operationId": "listDocuments", "summary": "List documents", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "From next_cursor." } ], "responses": { "200": { "description": "Documents under `items`; empty collections return 200 with items: [].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } } }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createDocument", "summary": "Create a document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Any JSON object (max 10240 bytes serialized). Keys __proto__, constructor, prototype are rejected at any depth." } } } }, "responses": { "201": { "description": "Created. Your fields are under `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Invalid body or collection name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Document exceeds 10240 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Quota exceeded (max 100 docs, 100 writes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteCollection", "summary": "Delete an entire collection", "description": "Deletes are always allowed and do not count against the write quota.", "responses": { "200": { "description": "Deleted." }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/{collection}/{id}": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "description": "Collection name. Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$; must not start with __ or be a reserved word (admin, new, health, db, api, skills). Created implicitly on first write.", "schema": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } }, { "name": "id", "in": "path", "required": true, "description": "Server-generated document id (doc_...).", "schema": { "type": "string" } } ], "get": { "operationId": "getDocument", "summary": "Read one document", "responses": { "200": { "description": "The document; your fields are under `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "404": { "description": "Unknown database or document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchDocument", "summary": "Shallow-merge update", "description": "null sets a field to null; keys are never deleted. Size limit applies to the merged result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Any JSON object (max 10240 bytes serialized). Keys __proto__, constructor, prototype are rejected at any depth." } } } }, "responses": { "200": { "description": "Full updated document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "404": { "description": "Unknown database or document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merged document exceeds 10240 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Write quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDocument", "summary": "Delete one document", "responses": { "200": { "description": "{\"deleted\":true,...}" }, "404": { "description": "Unknown database or document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/__meta": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } } ], "get": { "operationId": "getMeta", "summary": "Usage, limits, expiry", "responses": { "200": { "description": "Meta JSON." }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/__schema": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } } ], "get": { "operationId": "getSchema", "summary": "Inferred schema per collection", "responses": { "200": { "description": "field -> observed types." }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/__export": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } } ], "get": { "operationId": "exportDatabase", "summary": "Full JSON export of every collection", "responses": { "200": { "description": "Export JSON." }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/__health": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } } ], "get": { "operationId": "healthCheck", "summary": "Liveness check for this database", "responses": { "200": { "description": "{\"ok\":true}" }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Database expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/__extend": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } } ], "get": { "operationId": "getExtensionPlans", "summary": "Paid extension plans for keeping this database alive", "description": "Transparent pricing table. Works on expired databases too — expired data stays frozen and restorable by payment during the grace window.", "responses": { "200": { "description": "Plans, prices, current expiry, purchase instructions." }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createExtensionCheckout", "summary": "Buy an extension (returns a Stripe checkout URL for a human)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string", "enum": [ "week", "month", "quarter" ] } } } } } }, "responses": { "200": { "description": "{checkout_url, plan, price_usd, adds_days} — open checkout_url in a browser to pay." }, "400": { "description": "Unknown plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Payments not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/db/{capability}/__pro": { "parameters": [ { "name": "capability", "in": "path", "required": true, "description": "Secret database capability from the create response (the `db` URL contains it).", "schema": { "type": "string" } } ], "get": { "operationId": "getProOffer", "summary": "Pro upgrade offer for this database", "description": "How to make this specific database always-on (no TTL) by upgrading it in place to a Pro account. Works on expired (frozen) databases too.", "responses": { "200": { "description": "Offer + upgrade steps." }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pro/checkout": { "post": { "operationId": "createProAccount", "summary": "Start a Pro subscription (returns a token + Stripe checkout URL)", "description": "Mints a Pro account token (persist it immediately) and a subscription checkout URL for a human to pay. The account becomes active once payment is confirmed.", "responses": { "200": { "description": "{pro_token, checkout_url, base_price_usd, included_dbs, extra_db_price_usd}." }, "503": { "description": "Pro not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pro/databases": { "get": { "operationId": "listProDatabases", "summary": "List the Pro account's databases", "description": "Requires `Authorization: Bearer `. Returns database ids + metadata (not URLs — only a hash is stored server-side).", "responses": { "200": { "description": "Account summary + database list." }, "401": { "description": "Missing or unknown Pro token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Subscription not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createProDatabase", "summary": "Create a new always-on Pro database", "description": "Beyond the included databases each one costs a flat fee charged to the card on file IMMEDIATELY, renewing monthly while it exists; the request must acknowledge it with body {\"accept_overage_usd\":\"...\"} or a 400 confirmation_required returns the exact price (and nothing is created or billed). If the immediate charge fails, nothing is created. Inform the human before accepting.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept_overage_usd": { "type": "string", "description": "Explicit acknowledgment of the extra-database monthly price (e.g. \"1.50\"). Required only beyond the included allotment." } } } } } }, "responses": { "201": { "description": "The new database (db URL is the only credential — persist it)." }, "400": { "description": "Overage acknowledgment required (confirmation_required, details carry the exact price).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown Pro token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Subscription not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pro/databases/{id}": { "delete": { "operationId": "deleteProDatabase", "summary": "Spin down (permanently delete) one Pro database by id", "description": "Requires `Authorization: Bearer ` and ?confirm=true. Immediate and irreversible; stops the database's monthly renewal charge (no partial-month refund). Export first if the data matters.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database id (db_...) from GET /api/pro/databases." }, { "name": "confirm", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Must be the string 'true' to proceed with this irreversible delete." } ], "responses": { "200": { "description": "{\"deleted\":true,\"id\":\"db_...\",\"docs\":n}" }, "400": { "description": "Missing confirmation (?confirm=true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown Pro token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No database with this id on the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pro/cancel": { "get": { "operationId": "getCancellationTerms", "summary": "Pre-cancellation disclosure", "description": "Requires `Authorization: Bearer ` (any subscription status). Returns exactly what cancellation does and when: access end, database freeze date, permanent deletion date.", "responses": { "200": { "description": "Cancellation consequences with concrete timestamps." }, "401": { "description": "Missing or unknown Pro token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "cancelProSubscription", "summary": "Cancel the Pro subscription at period end", "description": "DESTRUCTIVE: after the paid period plus grace window, every database on the account freezes and is then permanently deleted. Requires explicit confirmation; without it a 400 returns the full disclosure. Inform the human and get approval before calling.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "string", "enum": [ "cancel" ] } } } } } }, "responses": { "200": { "description": "Canceled at period end; response carries the freeze/deletion dates." }, "400": { "description": "Missing confirmation (confirmation_required, details carry the disclosure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown Pro token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No subscription to cancel (checkout never completed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Payments not enabled on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pro/attach": { "post": { "operationId": "attachProDatabase", "summary": "Upgrade an existing database to Pro in place", "description": "Requires `Authorization: Bearer `. Body {\"capability\":\"s-...\"}. Keeps the same URL and data, removes the TTL, raises quotas.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "capability" ], "properties": { "capability": { "type": "string", "example": "s-..." } } } } } }, "responses": { "200": { "description": "Upgraded database." }, "400": { "description": "Overage acknowledgment required when attaching beyond the included allotment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing/unknown token, or database owned by another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Subscription not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "CreateResponse": { "type": "object", "description": "A new database. The `db` URL is the only credential (a bearer capability) — persist it immediately.", "required": [ "db", "admin", "expires_at", "limits", "docs", "skills" ], "properties": { "db": { "type": "string", "format": "uri", "description": "Database base URL — the only credential." }, "admin": { "type": "string", "format": "uri", "description": "Read-only web viewer for humans." }, "expires_at": { "type": "string", "format": "date-time" }, "limits": { "type": "object", "properties": { "ttl_hours": { "type": "integer", "example": 24 }, "max_docs": { "type": "integer", "example": 100 }, "max_writes": { "type": "integer", "example": 100 }, "max_doc_bytes": { "type": "integer", "example": 10240 } } }, "docs": { "type": "string", "format": "uri", "description": "Agent documentation (llms.txt)." }, "skills": { "type": "string", "format": "uri", "description": "Index of agent skills (SKILL.md playbooks) for building on TmpState." } } }, "Document": { "type": "object", "description": "A stored document. User fields are nested under `data`; id and timestamps are server-generated.", "required": [ "id", "collection", "data", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "example": "doc_c6berHy3g552PVg5dmMvHg" }, "collection": { "type": "string", "example": "tasks" }, "data": { "type": "object", "additionalProperties": true, "description": "Your JSON object, exactly as submitted." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DocumentList": { "type": "object", "description": "Collection listing. Documents are under `items` (NOT `data`). A missing or empty collection returns 200 with an empty `items` array, never 404.", "required": [ "collection", "items", "next_cursor" ], "properties": { "collection": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as ?cursor= to fetch the next page; null when done." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_json", "invalid_body", "invalid_collection", "invalid_document_id", "not_found", "db_not_found", "method_not_allowed", "expired", "payload_too_large", "quota_exceeded", "rate_limited", "invalid_plan", "payments_unavailable", "confirmation_required", "unauthorized", "payment_required", "internal_error" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } } } } }