Search

Three reads over the index. None of them touches your devices: the index lives in your network, so they work while a device is off.

Search

POST /v1/search
{ "q": "quarterly report", "hosts": ["h1a2b3c4d5e6"], "topK": 10 }

field
q	the query. Plain words; phrases in quotes
hosts	optional; limit to these host ids. Absent means every host the token may search
topK	optional, default 10, at most 100
filter	optional: {"kind": "text/markdown"}, {"ext": "pdf"}, {"deleted": true} to include forwards
snippets	optional, default true; false leaves out snippet for a smaller answer

{
  "hits": [
    { "address": "inseam://n7q2…/h1a2b3c4d5e6/Reports/Q3.md", "host": "h1a2b3c4d5e6", "score": 0.0312,
      "title": "Q3 report", "snippet": "…revenue for the quarter was…",
      "meta": { "size": 18234, "mtime": "2026-09-30T14:02:00Z", "mime": "text/markdown", "depth": "embed" } }
  ],
  "hosts": [
    { "id": "h1a2b3c4d5e6", "name": "Documents", "searched": true, "coverage": { "items": { "catalog": 10, "embed": 900 } } },
    { "id": "h9z8y7x6w5v4", "name": "Archive", "searched": false, "reason": "not in hosts" }
  ],
  "tookMs": 41
}

Results are ranked by relevance across every host that was searched. hosts says what was and was not covered, so a tool can tell the difference between “nothing matched” and “that host was not searched”. Search is by words today; semantic search is not yet.

An item at depth catalog matches by its title and path only. An item at embed matches by its text too. See scope.

One record

GET /v1/get?address=inseam://n7q2…/h1a2b3c4d5e6/Reports/Q3.md

{ "record": {
    "content": "b3:9f2c…", "size": 18234, "mtime": "2026-09-30T14:02:00Z", "mime": "text/markdown",
    "title": "Q3 report", "added": "2026-09-30T14:03:11Z", "depth": "embed", "deleted": false } }

404 when the address is not in the index. Add text=1 to get the indexed text too, when the item has it. An address that was moved or deleted keeps a forward for a while: its record has deleted: true and, after a move, movedTo. Add follow=1 to get the record at the new address instead.

field
content	the content address of the bytes: b3: and a hash. Two items with the same content are the same bytes
size, mtime, mime	from the host
title	from the document, else the file name
depth	how deeply the item is indexed: catalog or embed
etag	the host’s version id, when it has one. Use it with If-Match on a write

List a prefix

GET /v1/list?prefix=inseam://n7q2…/h1a2b3c4d5e6/Reports/&limit=100

{ "entries": [ { "address": "inseam://n7q2…/h1a2b3c4d5e6/Reports/Q3.md", "id": "…" } ], "more": true, "next": "…" }

Everything under the prefix, in address order, deleted items left out. Pass after={next} for the next page. limit is at most 1000.

Addresses in a URL

Where an address goes in a URL, URL-encode it, or use the short form {host}/{path} under the token’s network: GET /v1/get?address=h1a2b3c4d5e6/Reports/Q3.md. See addresses.