{
  "openapi": "3.1.0",
  "info": {
    "title": "walkindb",
    "version": "0.1.0",
    "summary": "Disposable SQLite for LLM agents. No signup, 10-minute TTL.",
    "description": "walkindb provisions a private SQLite database on the first POST /sql request and returns a session token in the X-Walkin-Session response header. Subsequent requests reuse the token to reach the same database. Each instance has a default lifetime of 10 minutes, after which it is deleted automatically. See https://walkindb.com/legal/ for the AUP, terms, privacy notice, and DMCA procedure.",
    "contact": {
      "name": "walkindb",
      "url": "https://walkindb.com/",
      "email": "hello@walkindb.com"
    },
    "license": {
      "name": "Apache-2.0",
      "identifier": "Apache-2.0"
    }
  },
  "servers": [
    {"url": "https://api.walkindb.com", "description": "Production"}
  ],
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "getHealth",
        "summary": "Liveness probe",
        "description": "Returns 200 when the server is accepting requests.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Health"}
              }
            }
          }
        }
      }
    },
    "/sql": {
      "post": {
        "operationId": "executeSQL",
        "summary": "Execute a SQL statement",
        "description": "Executes one SQL statement against the current walk-in instance. Omit the X-Walkin-Session header on the first call; walkindb will provision a fresh instance and return the session token in the response header. Include the same header on subsequent calls to reach the same database.",
        "parameters": [
          {
            "name": "X-Walkin-Session",
            "in": "header",
            "required": false,
            "description": "Session token returned by the first call. Omit to provision a new instance.",
            "schema": {"type": "string", "example": "wkn_AZ159u9PdmS97ks7FnSmnRc6..."}
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/SQLRequest"},
              "examples": {
                "create": {
                  "summary": "CREATE + INSERT in one statement",
                  "value": {"sql": "CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT); INSERT INTO notes(body) VALUES('hello')"}
                },
                "select": {
                  "summary": "SELECT",
                  "value": {"sql": "SELECT * FROM notes"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query executed successfully",
            "headers": {
              "X-Walkin-Session": {
                "description": "Set on the FIRST call that provisioned the instance. Save it and pass it as a request header on subsequent calls.",
                "schema": {"type": "string"}
              },
              "X-Walkin-TTL": {
                "description": "Unix timestamp at which this instance will be deleted.",
                "schema": {"type": "integer", "format": "int64"}
              }
            },
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/SQLResponse"}
              }
            }
          },
          "400": {
            "description": "Invalid JSON, missing sql, forbidden keyword, or SQL syntax/semantic error.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {
            "description": "Session token unknown, tampered, or expired. Walkindb returns 404 (not 401) on all session failures to prevent enumeration.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "408": {
            "description": "Query exceeded the 2-second wall-clock timeout.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {
            "description": "Request body exceeded the 8 KB cap.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Per-IP rate limit exceeded (60 req/min, 10 new-instance creations/min).",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "507": {
            "description": "Instance storage quota exceeded (10 MB per walk-in).",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Health": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": {"type": "string", "enum": ["ok"]}
        }
      },
      "SQLRequest": {
        "type": "object",
        "required": ["sql"],
        "properties": {
          "sql": {
            "type": "string",
            "description": "SQL statement to execute. Up to 8 KB. Multiple statements separated by ; are supported.",
            "maxLength": 8192
          },
          "args": {
            "type": "array",
            "description": "Reserved for future bound parameters. Currently ignored.",
            "items": {}
          }
        }
      },
      "SQLResponse": {
        "type": "object",
        "required": ["rows_affected"],
        "properties": {
          "columns": {
            "type": "array",
            "description": "Column names for query results. Absent on non-SELECT statements.",
            "items": {"type": "string"}
          },
          "rows": {
            "type": "array",
            "description": "Result rows. Each row is an array of values in column order. Absent on non-SELECT.",
            "items": {"type": "array", "items": {}}
          },
          "rows_affected": {
            "type": "integer",
            "format": "int64",
            "description": "Number of rows affected by INSERT/UPDATE/DELETE. 0 for SELECT."
          },
          "truncated": {
            "type": "boolean",
            "description": "True if the result was capped at 10k rows or 1 MB."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {"type": "string"}
        }
      }
    }
  }
}