Skip to content
inseam

Objects

The bytes behind an address. Reads and writes go through your network to the host that holds the object: a device, or the pad.

GET    /v1/o/{address}
PUT    /v1/o/{address}
DELETE /v1/o/{address}

{address} is the location address URL-encoded, or the short form {host}/{path} under the token’s network: /v1/o/h1a2b3c4d5e6/Reports/Q3.md.

Read

Section titled “Read”
Terminal window
curl https://app.inseam.io/v1/o/h1a2b3c4d5e6/Reports/Q3.md -H "Authorization: Bearer ias_…"

The body is the object, with its Content-Type, Content-Length and ETag. Needs the read scope.
Range: bytes=0-1023 honoured; the answer is 206 with Content-Range
Content-Location set when the address was a forward: the current address of the object
410 the address was moved or deleted and nothing readable is behind it; the body lists candidates when there are any
503 steward-offline the device that holds the bytes is off. The index still has the record; try again when it is on
413 the object is over 4 MiB. Reads are limited to 4 MiB per object for now; larger objects are not yet readable over the API, only on their device

Write

Section titled “Write”
Terminal window
curl -X PUT https://app.inseam.io/v1/o/pad/notes/today.md \
  -H "Authorization: Bearer ias_…" -H "Content-Type: text/markdown" \
  --data-binary @today.md

The body is the object. Needs the write scope on the host, or the token’s own pad folder. 201 for a new address, 200 for an update, both with the new catalog entry:

{ "entry": { "address": "inseam://n7q2…/pad/notes/today.md", "content": "b3:…", "etag": "…", "size": 412,
             "depth": "embed", "created": "2026-10-25T18:00:00Z" } }

The object is searchable when the call returns.
If-Match: {etag} write only if the object is still that version; else 412 with the current etag in details
415 the host does not accept that content type; details.mimes lists what it does
403 the host is not writable with this token; details names the rule
402 over-limit the network is over its item limit. The bytes are stored; the record waits until there is room

Today the pad accepts writes. A folder on a device is read-only over the API unless writes are turned on for it (its write rules; see hosts).

Delete

Section titled “Delete”
Terminal window
curl -X DELETE https://app.inseam.io/v1/o/pad/notes/today.md -H "Authorization: Bearer ias_…"

204. The address keeps a forward with deleted: true for a while, so a stale link says what happened instead of vanishing.