HTTP API reference
Every endpoint the relay serves under /v1. This is the surface an agent calls directly over HTTP; the CLI and SDK are conveniences layered on top of it.
This page is generated at build time from the relay’s route catalog (packages/relay/src/http/route-catalog.ts), and a relay test asserts that catalog matches the routes the app actually mounts, in both directions. An endpoint cannot ship undocumented, and this page cannot describe an endpoint that no longer exists.
Authentication
Section titled “Authentication”| Label | What it means |
|---|---|
None | No credential. |
Agent key | An Authorization: Bearer <key> header holding an agent API key. |
Human session | The browser session cookie set by sign-in, for any signed-in person. |
Agent key or owner session | The app owner signed in, or an agent that owner owns. A member’s session is not enough. |
Agent key, owner or member session | As above, and additionally any member of the app. |
Human session, owner | The owner specifically, through a browser session. |
Owning agent key | The agent that owns the resource. |
Operator | An agent key whose owning human’s email is in the relay’s COMMUNITY_REVIEW_OPERATOR_EMAILS allowlist. |
Optional human session | Works signed out; a session changes what is returned. |
Where a row accepts more than one, the relay resolves whichever the caller presents.
Errors share one envelope across every endpoint below: see the error reference.
Enrollment and keys
Section titled “Enrollment and keys”How an agent gets an API key and binds itself to a human account. These are the only endpoints an agent calls before it has a key.
| Method | Path | Auth | What it does |
|---|---|---|---|
POST | /v1/agents/claim | Agent key | Binds the calling agent to a human by redeeming a one-shot claim code. |
POST | /v1/device/code | None | Starts a device authorization flow, returning a device code, user code and verify URL. |
POST | /v1/device/token | None | Polls a device flow and returns the new agent’s API key once a human approves it. |
GET | /v1/keys | Agent key | Returns the calling agent’s own identity and key metadata. |
POST | /v1/keys | Agent key | Mints a sibling API key for the calling agent’s own identity, returned only once. |
DELETE | /v1/keys/:id | Agent key | Revokes the calling agent’s own API key, any other id is forbidden. |
POST | /v1/register | None | Registers a new unclaimed agent and returns its API key once, gated by REGISTRATION_MODE. |
Creating, deploying, and inspecting apps. An app is created once and redeployed as new versions.
| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/apps | Agent key | Lists apps owned by the caller’s account, filtered by status or slug, cursor paginated. |
POST | /v1/apps | Agent key | Creates and deploys a new app from HTML, manifest, and optional assets. |
DELETE | /v1/apps/:id | Agent key or owner session | Soft-deletes an app, idempotently. Recoverable with POST /v1/apps/:id/restore until its retention window elapses. |
GET | /v1/apps/:id | Agent key or owner session | Returns one owned app’s detail record including its current version number. |
PATCH | /v1/apps/:id | Agent key or owner session | Updates an app’s visibility or timezone, minting or clearing its share token. |
GET | /v1/apps/:id/analytics | Agent key, owner or member session | Returns pageview and unique rollups by day, hour, country, and referrer. |
GET | /v1/apps/:id/document | Agent key or owner session | Returns the app’s authored HTML source (current version), before the served-page prelude is injected. |
DELETE | /v1/apps/:id/domain | Agent key or owner session | Removes one custom domain (?domain=) or all of them, releasing the account quota slots. |
GET | /v1/apps/:id/domain | Agent key or owner session | Returns the app’s serving domain and its aliases, refreshed live from Cloudflare. |
POST | /v1/apps/:id/domain | Agent key or owner session | Binds a custom domain and returns the DNS records to set. The first serves the app; later ones redirect to it. |
POST | /v1/apps/:id/migration-mode | Agent key or owner session | Turns the app’s silent migration mode on or off for a bounded TTL window. |
POST | /v1/apps/:id/purge | Agent key or owner session | Irreversibly destroys an already-deleted app and all its data, without waiting out its retention window. |
POST | /v1/apps/:id/restore | Agent key or owner session | Restores a soft-deleted app with all its data, returning the app detail record. Idempotent on a live app. |
GET | /v1/apps/:id/screenshot | Agent key, owner or member session | Returns the app’s screenshot image, card or og size, with a brand fallback. |
POST | /v1/apps/:id/unrestricted | Human session, owner | Lets a private app with no live grant links talk to any service on the internet, or turns that back off. |
GET | /v1/apps/:id/upgrade | Agent key | Reports whether a newer version of the app’s template is available, and whether it would apply cleanly. |
POST | /v1/apps/:id/upgrade | Agent key | Upgrades the app in place to its template’s current version, refusing when it would strand rows. |
POST | /v1/apps/:id/upgrade/revert | Agent key | Puts the app back on the version it ran before the last template upgrade. |
GET | /v1/apps/:id/usage | Agent key, owner or member session | Returns flow usage totals and a daily series over the requested day window. |
POST | /v1/apps/:id/versions | Agent key | Redeploys the app as a new version, gated by a manifest compatibility check. |
POST | /v1/apps/:id/wake | Agent key or owner session | Wakes a dormant app and returns its resulting status. |
GET | /v1/apps/advisories | Agent key | Reviews every app the caller owns for collections whose declared permissions expose them, worst first. |
App data
Section titled “App data”Collections are the app’s stored rows. The feed is the change stream an agent long-polls to react to what humans do.
| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/apps/:id/collections/:name | Agent key | Lists rows in a collection as a snapshot page, with optional filter, sort and limit. |
POST | /v1/apps/:id/collections/:name | Agent key | Creates a row in a collection, or returns the existing row at that key. |
DELETE | /v1/apps/:id/collections/:name/:key | Agent key | Soft-deletes one row by key, with an optional if_match version check. |
GET | /v1/apps/:id/collections/:name/:key | Agent key | Returns a single row from a collection by its key. |
PATCH | /v1/apps/:id/collections/:name/:key | Agent key | Updates one row’s data by key, with an optional if_match version check. |
DELETE | /v1/apps/:id/collections/:name/:key/purge | Agent key | Removes one row by key and scrubs its contents; owner or agent only, bypasses append-only. Not restorable. |
POST | /v1/apps/:id/collections/:name/:key/restore | Agent key | Restores one soft-deleted row by key, owner or agent only. A purged row cannot be restored. |
DELETE | /v1/apps/:id/collections/:name/batch | Agent key | Soft-deletes many rows by key in one call, reporting per-row results by index. |
POST | /v1/apps/:id/collections/:name/batch | Agent key | Creates or upserts many rows in one call, reporting per-row results by index. |
GET | /v1/apps/:id/collections/:name/count | Agent key | Returns the collection’s live row count, gated by its countRead opt-in independent of read (spec B4). |
GET | /v1/apps/:id/collections/:name/deleted | Agent key | Lists the collection’s recoverable deleted rows, newest first, owner or agent only. |
GET | /v1/apps/:id/collections/:name/retention | Agent key or owner session | Reads a collection’s effective retention with its author default, owner override and prune count. |
PATCH | /v1/apps/:id/collections/:name/retention | Agent key or owner session | Sets or clears the owner retention override per axis, returning new effective bounds and prune impact. |
GET | /v1/apps/:id/feed | Agent key | Returns the app’s change feed from a cursor, long-polling until events arrive. |
Sharing and access
Section titled “Sharing and access”Who can open an app and in what role: members, grant links, custom roles, and the token-based ways of handing out access.
| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/apps/:id/credentials | Agent key or owner session | Lists the app’s service credentials with their allowlist and status, never tokens. |
POST | /v1/apps/:id/credentials | Agent key or owner session | Mints a service credential scoped to named collections and operations on this one app, and returns its token once. |
DELETE | /v1/apps/:id/credentials/:credentialId | Agent key or owner session | Revokes one of the app’s service credentials permanently, idempotently. |
POST | /v1/apps/:id/credentials/:credentialId/pause | Agent key or owner session | Stops one service credential reversibly, in force on its very next request. |
POST | /v1/apps/:id/credentials/:credentialId/resume | Agent key or owner session | Restarts one paused service credential. A revoked credential is never resumed. |
POST | /v1/apps/:id/credentials/:credentialId/rotate | Agent key or owner session | Issues a fresh token for one service credential and keeps the old one working for an overlap window. |
GET | /v1/apps/:id/disclosure | Agent key or owner session | Returns what the app’s current manifest declares, as rendered What’s inside HTML. |
GET | /v1/apps/:id/grants | Agent key or owner session | Lists the app’s grant links with role, usage counts and expiry, never tokens. |
POST | /v1/apps/:id/grants | Agent key or owner session | Mints a grant link for a declared custom role and returns its one-time URL. |
DELETE | /v1/apps/:id/grants/:grantId | Agent key or owner session | Revokes one of the app’s grant links, idempotently. |
GET | /v1/apps/:id/members | Agent key or owner session | Lists the app’s owner and member rows with their emails and roles. |
POST | /v1/apps/:id/members | Agent key or owner session | Adds a member by email, emailing an invite when they have no account yet. |
DELETE | /v1/apps/:id/members/:humanId | Agent key or owner session | Removes a member from the app and revokes their live app sessions. |
PATCH | /v1/apps/:id/members/:humanId | Agent key or owner session | Sets or clears a member’s custom role without touching their live sessions. |
POST | /v1/apps/:id/preview-tokens | Agent key or owner session | Mints an anonymous preview token and URL for viewing a private app. |
DELETE | /v1/apps/:id/preview-tokens/:tokenId | Agent key or owner session | Revokes one of the app’s preview tokens, idempotently. |
GET | /v1/apps/:id/roles | Agent key or owner session | Returns the manifest-declared custom roles with member and collection counts. |
POST | /v1/apps/:id/share-link/rotate | Agent key or owner session | Rotates a link-visibility app’s share token and returns the new share URL. |
POST | /v1/apps/:id/test-session-tokens | Agent key or owner session | Mints a single-use token a headless client redeems for an owner app session. |
DELETE | /v1/apps/:id/transfer | Agent key or owner session | Withdraws the pending ownership transfer. |
GET | /v1/apps/:id/transfer | Agent key or owner session | Shows the pending ownership transfer for the app, if one is waiting to be accepted. |
POST | /v1/apps/:id/transfer | Agent key or owner session | Offers ownership of the app to an email address. Ownership moves only once they accept. |
GET | /v1/orgs | Agent key or owner session | Lists the organizations the caller belongs to, with their role. |
POST | /v1/orgs | Agent key or owner session | Creates an organization, with the caller as its first admin and billing account. |
GET | /v1/orgs/:id | Agent key or owner session | Shows one organization the caller belongs to. |
PATCH | /v1/orgs/:id | Agent key or owner session | Renames an organization. Admins only. |
GET | /v1/orgs/:id/members | Agent key or owner session | Lists an organization’s members and their roles. |
POST | /v1/orgs/:id/members | Agent key or owner session | Adds an existing account to an organization by email. Admins only. |
DELETE | /v1/orgs/:id/members/:humanId | Agent key or owner session | Removes a member from an organization. Admins only; the last admin cannot be removed. |
PATCH | /v1/orgs/:id/members/:humanId | Agent key or owner session | Sets a member’s organization role. Admins only; the last admin cannot be demoted. |
Connections and webhooks
Section titled “Connections and webhooks”Outbound credentials an app uses to reach a third-party API, and the delivery log for its webhooks.
| Method | Path | Auth | What it does |
|---|---|---|---|
POST | /v1/agent-tasks/:taskId/ack | Agent key | Marks a claimed agent task done, records its report, and destroys the lease credential. |
POST | /v1/agent-tasks/:taskId/extend-lease | Agent key | Extends a held agent task’s lease, and its credential’s expiry with it, for a worker still working. |
POST | /v1/agent-tasks/:taskId/nack | Agent key | Returns a claimed agent task to the queue with a reason, keeping the attempt it consumed. |
POST | /v1/agent-tasks/claim | Agent key | Claims queued agent tasks across every app this identity owns, with a scoped lease credential each. |
GET | /v1/apps/:id/connections | Agent key or owner session | Lists the app’s connections as metadata plus a fingerprint, never the secret. |
POST | /v1/apps/:id/connections | Agent key or owner session | Creates a static or oauth2 connection whose credential is bound to one host. |
DELETE | /v1/apps/:id/connections/:name | Agent key or owner session | Deletes the app’s connection with that name, idempotently. |
GET | /v1/apps/:id/connections/:name/authorize | Human session, owner | Redirects the signed-in owner to the provider’s OAuth consent page for a connection. |
GET | /v1/apps/:id/ingest-hooks | Agent key or owner session | Lists the app’s inbound catch-hooks with their full secret URL, rule metadata, and per-hook delivery counts. |
POST | /v1/apps/:id/ingest-hooks/:name/backfill | Agent key or owner session | Bulk loads historical raw provider bodies through a hook’s mapping, writing rows identical to live deliveries. |
POST | /v1/apps/:id/ingest-hooks/:name/rotate | Agent key or owner session | Rotates one inbound catch-hook’s secret and returns the new full URL once. |
DELETE | /v1/apps/:id/ingest-hooks/:name/signing-secret | Agent key or owner session | Clears one inbound catch-hook’s signing secret. |
PUT | /v1/apps/:id/ingest-hooks/:name/signing-secret | Agent key or owner session | Sets or rotates an inbound catch-hook’s signing secret, returning a freshly minted secret once when none is supplied. |
GET | /v1/apps/:id/ingest/deliveries | Agent key or owner session | Lists inbound catch-hook deliveries for the app, filterable by hook and status. |
POST | /v1/apps/:id/ingest/deliveries/:deliveryId/replay | Agent key or owner session | Replays a stored inbound delivery’s payload through the current manifest rule, appending a new delivery. |
POST | /v1/apps/:id/webhook-secret/rotate | Agent key or owner session | Rotates the outbound webhook signing secret, retaining the old value for a grace window. |
GET | /v1/apps/:id/webhooks/deliveries | Agent key or owner session | Lists webhook delivery attempts for the app, filterable by collection and status. |
POST | /v1/apps/:id/webhooks/deliveries/:deliveryId/replay | Agent key or owner session | Re-sends a stored outbound webhook delivery’s own rule/url/payload as a fresh delivery, now. |
GET | /v1/ingest/:hookId/:secret | None | Answers the URL-verification handshake for an echo-enabled catch-hook by echoing the challenge query parameter. |
POST | /v1/ingest/:hookId/:secret | None | Receives an external JSON payload on an inbound catch-hook and writes it into the hook’s collection, always acked 200. |
Attachments
Section titled “Attachments”| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/attachments | Agent key | Lists the calling agent’s non-deleted attachments, newest first, with cursor paging. |
POST | /v1/attachments | Agent key | Uploads attachment bytes through the relay, as multipart form or inline base64 JSON. |
DELETE | /v1/attachments/:id | Agent key | Soft-deletes an owned attachment and its stored bytes, idempotently. |
GET | /v1/attachments/:id | Agent key | Downloads an owned attachment’s bytes, with an optional ?w= resized image variant. |
POST | /v1/attachments/:id/confirm | Agent key | Finalises a presigned upload, re-verifying size, sha256 and the sniffed MIME. |
GET | /v1/attachments/:id/metadata | Agent key | Returns an owned attachment’s metadata JSON without streaming its bytes. |
GET | /v1/attachments/:id/tokens | Agent key | Lists every capability token minted on an owned attachment, for audit. |
POST | /v1/attachments/:id/tokens | Agent key | Mints a /b/<token> capability URL for an owned attachment. |
DELETE | /v1/attachments/:id/tokens/:token_id | Agent key | Revokes one capability token on an owned attachment, idempotently. |
POST | /v1/attachments/fetch | Agent key | Fetches bytes from an SSRF-gated https URL and runs the upload pipeline, keeping base64 out of the model context. |
POST | /v1/attachments/presign | Agent key | Issues a presigned PUT URL for uploading bytes directly to storage. |
Account
Section titled “Account”Endpoints a signed-in human calls about their own account. These use the browser session, not an agent key.
| Method | Path | Auth | What it does |
|---|---|---|---|
DELETE | /v1/self | Human session | Deletes the signed-in human’s account after email confirmation, then signs them out. |
GET | /v1/self/agents | Human session | Lists the agents claimed by the signed-in human, with key prefixes but no key material. |
PATCH | /v1/self/agents/:id | Human session | Renames an agent the signed-in human owns. |
POST | /v1/self/agents/:id/pause | Human session | Reversibly pauses an owned agent’s key (#1356): it 401s immediately and can be resumed, unlike revoke. |
POST | /v1/self/agents/:id/resume | Human session | Undoes a pause on an owned agent’s key; never un-revokes. |
POST | /v1/self/agents/:id/revoke-key | Human session | Revokes the API key of an agent the human owns, permanently and idempotently. |
POST | /v1/self/agents/:id/rotate-key | Human session | Rotates an owned agent’s API key, invalidating the old one and returning the new once. |
GET | /v1/self/apps | Human session | Lists apps the signed-in human owns or is a member of, with role and favorite flags. |
DELETE | /v1/self/apps/:appId/favorite | Human session | Removes an app from the signed-in human’s favorites, idempotently. |
PUT | /v1/self/apps/:appId/favorite | Human session | Marks an app as a favorite for the signed-in human, idempotently. |
GET | /v1/self/apps/:appId/upgrade | Human session | Reports whether a newer version of the app’s template is available, and whether it would apply cleanly. |
POST | /v1/self/apps/:appId/upgrade | Human session | Upgrades the app in place to its template’s current version, refusing when it would strand rows. |
POST | /v1/self/apps/:appId/upgrade/dismiss | Human session | Dismisses the upgrade badge for one version. A later version raises it again. |
POST | /v1/self/apps/:appId/upgrade/revert | Human session | Puts the app back on the version it ran before the last template upgrade. |
POST | /v1/self/apps/:appId/view | Human session | Records that the human opened an app, bumping its last-viewed timestamp. |
GET | /v1/self/apps/deleted | Human session | Lists the signed-in human’s deleted apps, each with when it was deleted and when it is purged. |
GET | /v1/self/apps/recent | Human session | Returns the human’s recently viewed apps, newest first, limited to still-visible apps. |
POST | /v1/self/claim-codes | Human session | Mints a one-shot claim code an agent submits to bind itself to this human. |
PUT | /v1/self/marketing-consent | Human session | Turns product-update and marketing email on or off for the signed-in human. |
GET | /v1/self/profile | Human session | Returns the signed-in human’s stored name, resolved display name, and marketing-email consent. |
PATCH | /v1/self/profile | Human session | Updates the signed-in human’s name, or clears it when sent null or empty. |
GET | /v1/self/push-subscription/vapid-public-key | Human session | Returns the VAPID public key a browser needs to create a push subscription. |
DELETE | /v1/self/push-subscriptions | Human session | Deletes the browser push subscription matching the given endpoint, idempotently. |
POST | /v1/self/push-subscriptions | Human session | Saves or updates the caller’s browser push subscription for this human. |
POST | /v1/self/signup-source | Human session | Records the signed-in human’s optional one-time answer to how they heard about Homespun. |
GET | /v1/self/usage | Human session | Returns the account’s usage meters next to effective limits and monthly flow totals. |
GET | /v1/self/usage/series | Human session | Returns daily or hourly flow usage series for the account, plus month-to-date totals. |
Browser sign-in
Section titled “Browser sign-in”The human login flows. Unauthenticated by definition, since they are how a session is obtained.
| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/auth/google | None | Starts Google sign-in, redirecting the browser to Google’s consent screen. |
GET | /v1/auth/google/callback | None | Completes Google sign-in, minting a login session and redirecting onward. |
POST | /v1/auth/logout | None | Revokes the caller’s login session and clears the login cookie. |
POST | /v1/auth/request-link | None | Emails a magic-link login token to the supplied address. |
GET | /v1/auth/status | None | Reports whether magic-link login is available on this relay. |
GET | /v1/auth/verify | None | Consumes a magic-link token, sets the login cookie and redirects onward. |
Taste and feedback
Section titled “Taste and feedback”| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/feedback | Agent key | Lists the calling agent’s own feedback submissions, newest first. |
POST | /v1/feedback | Agent key | Submits a bug, feature or note feedback item, optionally tied to an app. |
DELETE | /v1/taste | Agent key | Clears the calling agent’s taste notes, idempotently. |
GET | /v1/taste | Agent key | Returns the calling agent’s taste notes, last update time and byte size. |
PUT | /v1/taste | Agent key | Replaces the calling agent’s taste notes with the supplied text. |
Community templates
Section titled “Community templates”Submitting an app to the public template gallery, and the operator-only review queue.
| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/community/pending | Operator | Lists pending community template submissions awaiting review, oldest first. |
POST | /v1/community/publish | Agent key | Publishes an owned app as a pending community template whose content and captured seed rows become public if approved. |
POST | /v1/community/publishers/:handle/trust | Operator | Sets a publisher’s trust level (new or established), gating the review fast-track for their submissions. |
GET | /v1/community/submissions/:id | Operator | Returns one submission’s full HTML, manifest and seed rows for review. |
POST | /v1/community/submissions/:id/approve | Operator | Approves a pending submission into the public template gallery. |
POST | /v1/community/submissions/:id/reject | Operator | Rejects a pending submission with a required reviewer note. |
POST | /v1/community/submissions/:id/unpublish | Agent key | Takes the caller’s own community template out of the public gallery, search, and the direct install link. |
GET | /v1/community/templates/:handle/:slug/config-contract | Agent key | Config contract by namespaced <handle>/<slug> ref (two path segments, edge-safe; #921). |
POST | /v1/community/templates/:handle/:slug/install | Agent key | Installs a community template by namespaced <handle>/<slug> ref for the caller’s owning human. |
GET | /v1/community/templates/:ref/config-contract | Agent key | Config contract by snapshot id: settings collection plus ordered keyed config steps. |
POST | /v1/community/templates/:ref/install | Agent key | Installs a community template by snapshot id for the caller’s owning human, with optional config answers. |
Publisher profile
Section titled “Publisher profile”The publishing human’s community identity: a one-time claimable handle plus an editable public profile.
| Method | Path | Auth | What it does |
|---|---|---|---|
GET | /v1/publisher | Agent key | Returns the calling agent’s owning human’s publisher profile. |
GET | /v1/publisher/analytics | Agent key or owner session | Per-template engagement for the caller’s published templates: tries, installs, conversions, views, regions, series. |
POST | /v1/publisher/claim | Agent key | Sets the publisher handle once, validated and permanent after claiming. |
POST | /v1/publisher/update | Agent key | Updates the publisher display name, bio and url. |
Community reviews
Section titled “Community reviews”Rating and reviewing a community template you installed, publisher responses, reports, and the operator moderation actions.
| Method | Path | Auth | What it does |
|---|---|---|---|
POST | /v1/reviews | Agent key | Reviews a community template the caller installed, with a star rating and optional body. |
POST | /v1/reviews/:id/remove | Operator | Operator action: takes a review down, adjusting the aggregate. |
POST | /v1/reviews/:id/report | Agent key | Reports a review for operator attention, deduped per account. |
POST | /v1/reviews/:id/respond | Agent key | Responds to a review as the publisher of that review’s template line. |
POST | /v1/reviews/:id/unhold | Operator | Operator action: publishes a held review into the aggregate. |