Hosts

A host is one source in your network: a folder on a device, or the pad. Each has an id, a scope, and a state.

List and read

GET /v1/hosts
GET /v1/hosts/{id}

{ "id": "h1a2b3c4d5e6", "kind": "fs", "name": "Documents",
  "reachability": "device-bound", "steward": "<device id>",
  "scope": { "rev": 1, "window": { "by": "mtime", "within": "1y", "outside": "catalog" }, "rules": [ … ] },
  "write": { "rev": 0, "rules": [] }, "private": true,
  "state": "online", "head": { "items": 1200 },
  "coverage": { "items": { "catalog": 300, "embed": 900 }, "evaluatedAt": "…" },
  "created": "2026-10-01T09:00:00Z", "createdBy": "acct_…" }

field
kind	fs for a folder on a device, bucket for the pad
reachability, steward	device-bound hosts live on one device, named by steward; the pad is cloud
scope	what is indexed and how deeply; see scope
write	which paths may be written through the API, if any; empty means read-only
private	only its creator sees it until it is shared
state	online, offline (its device is off), indexing, error
head.items	how many items the host holds in the index
coverage	items per depth, and when the scope was last applied

A token sees the hosts it was granted, plus private hosts only when they belong to the person who created it.

Change a host

PATCH /v1/hosts/{id}
{ "name": "Work documents", "private": false }

name, private and write can change. Browser session only, by the host’s creator or a network admin.

Remove a host

DELETE /v1/hosts/{id}

204. The device stops sending for it and its items leave the index shortly after. Files on the device are not touched.

Scope

GET /v1/hosts/{id}/scope
PUT /v1/hosts/{id}/scope

GET returns {"scope": …, "dimensions": […], "schema": …}: the current document, the dimensions this host’s items have (path, ext, mime, size, mtime), and the JSON schema of a scope. PUT takes a document without rev and returns it with the new rev, or 422 invalid-scope naming the rule and dimension that do not evaluate. See choose what is indexed for the common cases.

Add a host

Folders are added from the device that holds them: the app’s Add folder… or inseam host add. Cloud connections from the web page are not yet. POST /v1/hosts exists for the clients and is not useful from a script today.

Devices

GET /v1/nodes
DELETE /v1/nodes/{id}

{ "nodes": [ { "id": "…", "name": "work laptop", "platform": "macos", "kind": "device",
               "online": true, "lastSeen": "2026-10-25T17:59:40Z", "hosts": ["h1a2b3c4d5e6"] } ] }

Every network also has one cloud node that holds the pad. DELETE revokes a device: it can no longer connect, and its hosts go offline until they are removed or the device is connected again as a new device.