Docs / Quickstart

Quickstart

Sixty seconds from nothing to a working SQL roundtrip. No signup, no API key.

1. Your first walk-in (curl)

walkindb provisions a private SQLite instance on the first request. You get the session token back in the X-Walkin-Session response header — include -i so curl prints headers.

# Create a table, insert a row, get a session token back
curl -i -X POST https://api.walkindb.com/sql \
  -H "content-type: application/json" \
  -d '{"sql":"CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT); INSERT INTO notes(body) VALUES(\"hello\")"}'

The response looks like this:

HTTP/2 200
x-walkin-session: wkn_AZ159u9PdmS97ks7FnSmnRc6vCwtR50stCEMZXqvz9koZmMQ3Kyk3zneZi4xMfw3PkzcDlRLR0RJajkeo6y6NaqyfTEBhJsGDFR1m_LHnhE
x-walkin-ttl: 1775868670
content-type: application/json

{"rows_affected": 1}

The token is a wkn_-prefixed base64url blob. Save it and pass it back as a request header on subsequent calls.

2. Reach the same database

curl -X POST https://api.walkindb.com/sql \
  -H "X-Walkin-Session: wkn_AZ159u9PdmS97ks7FnSmnRc6..." \
  -H "content-type: application/json" \
  -d '{"sql":"SELECT * FROM notes"}'

{"columns": ["id", "body"], "rows": [[1, "hello"]], "rows_affected": 0}
Ten minutes later, the database is gone. The X-Walkin-TTL header tells you the exact unix timestamp at which it will be deleted. If you need a fresh walk-in, drop the session token and repeat step 1.

3. Same flow in Python

pip install walkindb

from walkindb import Client

db = Client()
db.execute("CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT)")
db.execute("INSERT INTO notes(body) VALUES('hello')")

result = db.execute("SELECT * FROM notes")
print(result.columns)       # ['id', 'body']
print(result.rows)          # [[1, 'hello']]
print(db.session[:24])      # wkn_AZ159u9PdmS97ks7FnSm...

Zero runtime dependencies — the Python client uses only the standard library, so it installs cleanly in any agent sandbox. Full reference at Python SDK.

4. Same flow in JavaScript

npm install walkindb

import { Client } from "walkindb";

const db = new Client();

await db.execute("CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT)");
await db.execute("INSERT INTO notes(body) VALUES('hello')");

const result = await db.execute("SELECT * FROM notes");
console.log(result.columns);  // ['id', 'body']
console.log(result.rows);     // [[1, 'hello']]

ESM-only, TypeScript types ship in the package, works on Node 18+, Bun, Deno, Cloudflare Workers, and modern browsers. Full reference at JavaScript SDK.

What happens on errors

walkindb returns conventional HTTP status codes with a small JSON body:

{"error": "forbidden sql keyword: ATTACH"}

Common codes:

  • 400 — invalid JSON, missing sql, forbidden keyword (ATTACH, load_extension, readfile, ...), or SQL syntax error
  • 404 — session token unknown, tampered, or expired. walkindb returns 404, not 401, to prevent enumeration
  • 408 — query exceeded the 2-second wall-clock timeout
  • 413 — request body exceeded the 8 KB cap
  • 429 — per-IP rate limit exceeded (60 requests / min, 10 new instance creations / min)
  • 507 — instance storage quota exceeded (10 MB)

Full reference at Error codes.

Next