API reference

Everything the app does, you can do over HTTPS. The API is plain JSON over one base URL:

https://app.inseam.io

page	covers
Authentication	API tokens, their permissions, the network header, who you are
Search	search, one record, list a prefix
Objects	read, write and delete the bytes behind an address
Hosts	the hosts in a network, their scope, the devices
Networks	create a network, its status, its plan and usage
Addresses	the inseam:// address and the short form
Scope	the scope document, exactly
MCP and OAuth	the agent endpoint, the tools, and how an agent gets its permission

Conventions

• JSON in and out, Content-Type: application/json, UTF-8. Object reads and writes carry raw bytes instead.
• Times are RFC 3339 in UTC: 2026-10-25T18:00:00Z.
• Ids are short lowercase strings. A network id has 16 characters, a host id 12.
• Errors are one shape with a matching HTTP status:

{ "error": { "code": "forbidden", "message": "not allowed: write inseam://…", "details": { "action": "write", "address": "inseam://…" } } }

status	code	when
400	invalid	the body or a parameter is malformed; message says what
401	unauthenticated	no token, or a token that is expired or revoked
402	over-limit	the network is over its item limit and this write was held
403	forbidden	the token lacks the action on the target; details names both
404	not-found	no such record, host, network or route
409	conflict	the request contradicts the current state
410	gone	the address was moved or deleted and nothing readable is behind it
412	precondition-failed	If-Match did not match; details.etag is the current one
413	too-large	the body or the object is over the limit
415	unsupported-media-type	the host does not accept this content type; details.mimes lists what it does
422	invalid-scope	a scope document that does not evaluate; details names the rule
429	rate-limited	too many requests; slow down
503	steward-offline	the device that holds the bytes is off; try again later

• Lists that can be long take after and limit and return more with a next cursor.
• Pending work is reported, not hidden: a search answer says which hosts were searched and which were not, and why.

Status

inseam is in private beta. Routes on these pages work today. Where a field or a route is not built yet, the page says not yet, and the API answers 404 or an isError result rather than pretending.