Docs / API / Documents

Document interface

POST /doc stores JSON documents in your walk-in and queries them by path. Indexes are created for you.

Four operations, one query shape. There is no query language to learn: find takes JSON paths and the values they must equal, and every condition is ANDed. If you need more than that, use /sql — it is the same database.

Operations

CallBodyReturns
POST /doc/{collection}the document{"id":"..."}
POST /doc/{collection}/find{"where":{...},"limit":50}{"docs":[...],"count":n}
POST /doc/{collection}/get{"id":"..."}{"doc":{...}}
POST /doc/{collection}/delete{"id":"..."}{"deleted":true}
 
# Insert. No session header — this provisions a walk-in.
curl -i -X POST https://api.walkindb.com/doc/notes \
  -H "content-type: application/json" \
  -d '{"name":"ada","meta":{"rank":"admiral"},"tags":["math"]}'

# x-walkin-session: wkn_AZ159u9PdmS97ks7FnSmnRc6...
# {"id":"01a043fe-a12a-72aa-96b0-568704bd6284"}

# Query by path — nested paths work
curl -X POST https://api.walkindb.com/doc/notes/find \
  -H "X-Walkin-Session: wkn_..." \
  -H "content-type: application/json" \
  -d '{"where":{"$.meta.rank":"admiral"},"limit":10}'

# {"count":1,"docs":[{"id":"01a0...","name":"ada","meta":{"rank":"admiral"},...}]}

The generated id is a UUIDv7, so it sorts chronologically — find returns documents in insertion order without you storing a timestamp. The id is merged into each returned document, so you get one flat object rather than a wrapper.

Paths and indexes

A path looks like $.field, $.a.b, or $.items[0]. The first time you query a path, an index is created for it, so subsequent find calls on that path are index lookups rather than scans. You never create or manage an index.

Index growth is capped at 8 per walk-in. Past that, queries on further paths still work — they just scan. Bounding index count matters more than the speed of an unusual query inside a 10-minute database.

Limits

  • 64 KB per document.
  • Collection names must match [A-Za-z0-9_-]{1,64}.
  • find returns 50 documents by default, 200 maximum.
  • Conditions are equality only, ANDed. No ranges, no OR, no sorting beyond insertion order. Use /sql for anything richer.

It is the same database

Documents live in one ordinary table, _wk_doc, inside your walk-in — so you can query them with SQL, join them against tables you created, and use every JSON function SQLite has:

curl -X POST https://api.walkindb.com/sql \
  -H "X-Walkin-Session: wkn_..." \
  -d '{"sql":"SELECT json(body)->>'"'"'$.name'"'"' FROM _wk_doc WHERE coll='"'"'notes'"'"'"}'

Do not create your own table named _wk_doc.

A document with only top-level fields is interchangeable with a /kv hash. Nested documents are not — hashes are flat, so nesting is a /doc capability only.

Also see