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

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

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.

Apps

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 returning 204 even if already deleted.
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 the app’s custom domain binding and releases the account quota slot.
GET	/v1/apps/:id/domain	Agent key or owner session	Returns the app’s custom domain record, refreshed live from Cloudflare.
POST	/v1/apps/:id/domain	Agent key or owner session	Binds a custom domain to the app and returns the DNS records to configure.
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.
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.
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.

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	Hard-deletes one row by key, owner or agent only, bypassing append-only.
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/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

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/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.

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
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.
GET	/v1/apps/:id/webhooks/deliveries	Agent key or owner session	Lists webhook delivery attempts for the app, filterable by collection and status.
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

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

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/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.
POST	/v1/self/apps/:appId/view	Human session	Records that the human opened an app, bumping its last-viewed timestamp.
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.
GET	/v1/self/profile	Human session	Returns the signed-in human’s stored name and resolved display name.
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.
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

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

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

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.
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

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

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.