Deploy a multi-user web app from your agent: hosting, auth, database, and permissions.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Create a row in a v2 app's collection, or return the existing row when `key` is already present (deduped:true). Row creation goes through this tool; there is no separate strict-create verb. Omit `key` to add a new row with a server-generated key, or pass `key` to ensure a row exists at that key. Passing `key` is also what makes a retry safe: a call unsure whether it already landed can repeat it and get the same row back rather than a duplicate. Without `key`, a retry mints a second row with its own server-generated key, since there is nothing to dedup against. The collection must be declared in the app's manifest with a `write` list that reaches the caller, which is the list that gates creates. An agent acts with its owner's authority, so `owner` covers it; there is no separate 'agent' role, and a manifest that names one is rejected. When `key` matches a row the collection's `read` list does not reach for this caller, the result is row_not_found rather than the row, matching what get_row would return, so this never reads past `read`. Returns { row, deduped? }.
The row body - any JSON value valid against the collection's row schema (an object, or any JSON value for a schemaless collection).
The app id.
The collection name.
Optional stable key. Reusing an existing key returns the existing row (deduped:true), or row_not_found when the collection's read list does not reach that row for the caller.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Create a row in a v2 app's collection, or return the existing row when `key` is already present (deduped:true). Row creation goes through this tool; there is no separate strict-create verb. Omit `key` to add a new row with a server-generated key, or pass `key` to ensure a row exists at that key. Passing `key` is also what makes a retry safe: a call unsure whether it already landed can repeat it and get the same row back rather than a duplicate. Without `key`, a retry mints a second row with its own server-generated key, since there is nothing to dedup against. The collection must be declared in the app's manifest with a `write` list that reaches the caller, which is the list that gates creates. An agent acts with its owner's authority, so `owner` covers it; there is no separate 'agent' role, and a manifest that names one is rejected. When `key` matches a row the collection's `read` list does not reach for this caller, the result is row_not_found rather than the row, matching what get_row would return, so this never reads past `read`. Returns { row, deduped? }.
| Argument | Type | Description |
|---|---|---|
| key | string | Optional stable key. Reusing an existing key returns the existing row (deduped:true), or row_not_found when the collection's read list does not reach that row for the caller. |
| data* | any | The row body - any JSON value valid against the collection's row schema (an object, or any JSON value for a schemaless collection). |
| app_id* | string | The app id. |
| collection* | string | The collection name. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection",
"data"
],
"properties": {
"key": {
"type": "string",
"description": "Optional stable key. Reusing an existing key returns the existing row (deduped:true), or row_not_found when the collection's read list does not reach that row for the caller."
},
"data": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "array",
"items": {}
},
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "The row body - any JSON value valid against the collection's row schema (an object, or any JSON value for a schemaless collection)."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name."
}
}
}Agent identity and binding. Actions: whoami returns the resolved relay URL, the active profile and whether a key is configured, with no network call and no secrets; claim binds this agent to a human using a one-shot claim code from their Settings UI, and is one-way; logout clears the locally saved key and profile but does not revoke it on the relay, which is what the `key` tool's revoke action does.
| Argument | Type | Description |
|---|---|---|
| code | string | The one-shot claim code (required for claim). |
| action* | string | Agent identity. whoami: show the resolved relay URL, active profile, and whether a key is configured (no network, no secrets). claim: bind this agent to a human via a one-shot claim code the human generated in their Settings UI (one-way). logout: clears the locally-saved key/profile; the key is not revoked on the relay, which is what the key tool's revoke action does. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"code": {
"type": "string",
"description": "The one-shot claim code (required for claim)."
},
"action": {
"enum": [
"whoami",
"claim",
"logout"
],
"type": "string",
"description": "Agent identity. whoami: show the resolved relay URL, active profile, and whether a key is configured (no network, no secrets). claim: bind this agent to a human via a one-shot claim code the human generated in their Settings UI (one-way). logout: clears the locally-saved key/profile; the key is not revoked on the relay, which is what the key tool's revoke action does."
}
}
}The v2 app lifecycle apart from creation and redeploy, which deploy_app covers. Actions: list returns the owning human's apps; show returns full detail including manifest, timezone and has_share_token; audit is a read-only security review of every app the caller owns, computed from each app's stored manifest, which is what makes it see apps that were deployed once and never redeployed (a deploy-time warning never reaches those). It reports collections whose declared permissions expose them, worst first: severity 'high' means an anonymous visitor can exploit it today, typically a collection that admits "anyone" to write with no separate 'update' list, so any visitor can overwrite rows other people created rather than only adding their own. It changes nothing; the fix is a redeploy declaring the missing list, and the right list differs per app, so read the app before proposing one. update changes visibility and timezone, the slug being immutable, and switching to 'link' returns a share_url once; share_link_rotate issues a new share token for a 'link' app, returning a new share_url and revoking the old link, and generates one if the app has none; delete is an idempotent soft-delete, and it is recoverable: the app stops serving at once but keeps every version, collection, row, attachment, member and grant, and restore brings all of it back until the retention window elapses (list_deleted shows what is in the trash and each app's purges_at deadline, which is null when the account is never purged). restore is idempotent on a live app, and refuses with 409 when the account is at its app limit, when the app was an expired trial, or when the owning account is itself deleted; an app an operator suspended comes back suspended, not active. purge destroys a deleted app and all its data immediately and forever, with no restore afterwards, and requires the app to already be deleted, so no single call takes a serving app to unrecoverable; wake wakes a dormant app and is otherwise a no-op that reports the actual status; domain_set binds a custom domain and returns the DNS records the domain owner must publish, where the first domain bound serves the app and every later one redirects to it, which is how apex plus www is configured; domain_status returns the serving domain and its `aliases`, live-refreshed against Cloudflare when that is enabled, with last_error carrying the reason a domain is not activating; domain_remove unbinds one domain, or all of them when no `domain` is given, and is idempotent.
Binary attachments (images, PDFs, audio, video) referenced from event payloads and input_data via `format: homespun-attachment-id`. Actions: upload, fetch, presign, finalize, download, show, list, delete, mint_token, revoke_token, list_tokens. Choosing an upload path matters for cost. An inline upload with `content_base64` carries the bytes in the tool-call arguments, so they enter the model context at a token cost proportional to file size, paid again on every retry; a few-hundred-KB image is already expensive. Two paths avoid that entirely: fetch, when the bytes are reachable at a URL, and presign plus finalize, when the client can PUT the raw bytes out of band. Inline upload suits small assets and clients that have neither a URL nor an out-of-band PUT. fetch takes { source_url (https), scope } and the relay downloads the URL itself behind an SSRF guard (https only, no private, loopback or metadata hosts, DNS pinned, redirects refused, size-capped and timed out), then runs the same byte-sniff, allowlist, size, quota and scan checks as any upload. It works on any storage backend. upload takes either `content_base64` (base64 bytes, no filesystem) or `file_path` (an absolute path read on the relay host, so it only applies when the file is local to the relay). presign plus finalize is token-free: presign with { mime, size, sha256, scope } returns { put_url, attachment_id }, the caller PUTs the raw bytes to put_url over plain HTTP out of band, then finalize with the attachment_id. At finalize the relay re-reads the stored bytes, sniffs the real type, and enforces the same allowlist, size, sha256, quota and scan checks, so a presign that misstates its mime is caught and never served inline. The presigned path requires the Azure storage backend; a filesystem-backed relay returns a clear not-supported error and fetch or inline upload apply there instead. download writes to an absolute out_path or returns base64. An upload is scoped to agent (the default, reusable) or app. mint_token returns a /b/<token> capability URL, shown once, that a browser can GET without the caller's API key.
| Argument | Type | Description |
|---|---|---|
| mime | string |
Publishing an app as a community template, taking your own listing back down, installing a template, and, for relay operators, reviewing submissions. Actions: publish, unpublish, get_config_contract, install, list_pending, get_submission, approve, reject, set_trust_level. publish captures a live app (html, manifest, the seed rows of its seedOnInstall collections, and listing metadata) into a pending template. It is installable by the returned direct link but is not listed in the public gallery until an operator approves it, and it requires a verified email and no more than a few pending submissions at once. Privacy consequence: an approved template's content and its captured seed rows become public to every platform user, so seed data in a published app must be example-only rather than real personal data. attest_example_only:true records that this was checked. A template may take a per-publisher `slug` (namespaced as <handle>/<slug>) and a semver `version` defaulting to 1.0.0, and a republish under the same slug must bump the version. unpublish is the publisher's own undo for a live listing, taken down by snapshot_id: it leaves the public gallery, search, and the direct snapshot install link. It works only on your own submissions, and a snapshot that does not exist or belongs to someone else reads as not found either way. Existing installs are unaffected, because an install is a fresh private copy rather than a live reference, so unpublishing never breaks an app someone already installed. It is idempotent, and publishing a new version is the way to put the listing back. get_config_contract reads what a template needs at install, meaning its settings collection and its ordered config and upload steps, by `ref`. install creates a fresh private copy of a template for the caller's owning human, passing answers as `config`, where a 'config' value is a string and an 'upload' value is a pre-uploaded attachment id from the attachments tool. The review actions are limited to the relay's configured community reviewers: list_pending returns the queue; get_submission returns a submission's full content by snapshot_id; approve lists it in the gallery, where a re-publish supersedes the app's prior approved version; reject takes a required note that lands in the publisher's app feed.
| Argument | Type |
|---|
A v2 app's Connections: the stored credential (a static header token, or a full generic OAuth2 client) a manifest webhook rule authenticates its delivery target with, bound to a host so the credential can never be exfiltrated to another one. There is no update action: change a connection by deleting and recreating it. Actions: create stores a static or oauth2 connection and returns its metadata, never the secret; list returns the app's connections as metadata plus a non-reversible fingerprint, never any secret; delete is idempotent; consent_url builds (never fetches) the browser URL that completes an oauth2 connection's consent, since that is inherently a human-in-a-browser step an agent key cannot complete. A newly created oauth2 connection starts in `pending_auth` until the owner opens the consent_url and approves.
| Argument | Type | Description |
|---|---|---|
| kind | string | create only. Defaults to `static`. |
| name | string | create / delete / consent_url. The connection name (lowercase, starting alphanumeric, up to 64 chars) that a manifest webhook rule's `connection` field references. |
| label | string | create only. Optional owner-facing label. |
| action* | string | create: store a webhook connection, a stored credential (static header token or a full generic OAuth2 client) a manifest webhook rule authenticates its target with (app_id+name+allowed_host, plus kind-specific fields). list: the app's connections as metadata plus a non-reversible fingerprint, never any secret (app_id). delete: idempotent (app_id+name). consent_url: build (never fetch) the browser URL that completes an oauth2 connection's owner consent (app_id+name); hand it to the signed-in owner to open, since an agent key cannot complete OAuth consent itself. |
The live row count of a v2 app's collection (spec B4, issue #1056), a whole-scope total with no filter and no paging. Gated by the collection's countRead opt-in, independent of its read list: a collection that opted in returns its count even to a caller who cannot list the rows (the '3 spots left' shape), and a collection that never opted in refuses with collection_count_forbidden even for a caller who could otherwise list. Returns { count }.
| Argument | Type | Description |
|---|---|---|
| app_id* | string | The app id. |
| collection* | string | The collection name declared in the app's manifest. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection"
],
"properties": {
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name declared in the app's manifest."
}
}
}A v2 app's scoped service credentials (#1354, #1355): the bearer token an app owner points a backend they host themselves at, so their own server can read and write the app's data without holding the owner's full authority. Effective permission is always the intersection of the allowlist and what the app's owner could do, so a credential can only ever narrow, never widen, and it carries no role. Actions: mint creates one and returns its raw `token` shown once, never recoverable afterward (only its hash is stored); list returns the app's credentials with their allowlist and status, never any token material; pause reversibly stops one; resume undoes a pause (never a revoke, which is permanent); rotate issues a fresh token while the old one keeps working for an overlap window, so a running backend picks up the new token with no outage; revoke kills one permanently. Every action here is owner-or-owning-agent only: a service credential itself can reach none of these, by construction, so it can never mint or widen a sibling of itself.
| Argument | Type | Description |
|---|---|---|
| mode | string | mint only. Defaults to explicit: an unnamed collection is denied, so the credential can never reach anything it was not handed (the shape for a contractor's backend). following: an unnamed collection falls through to the owner's own authority, so the credential tracks the app as it grows and each `grants` entry only narrows one collection (the shape for the owner's own backend). Neither mode can ever exceed what the app's owner could do; the effective permission is always the intersection. |
| label | string | mint only. Optional owner-facing label shown in the credential list. |
| action* | string | mint: create a scoped service credential, the bearer token an app owner points a backend they host themselves at (app_id; optional mode/grants/members/label/ttl_seconds). list: the app's credentials, their allowlist and status, never a token (app_id). pause: reversibly stop one, in force on its very next request (app_id+credential_id). resume: undo a pause; never undoes a revoke, which is permanent (app_id+credential_id). rotate: issue a fresh token and keep the old one working for an overlap window so a running backend picks it up without a gap (app_id+credential_id; optional overlap_seconds). revoke: kill one permanently and idempotently (app_id+credential_id). |
Soft-delete a row from a v2 app's collection. Recoverable: the row is tombstoned, not destroyed, and restore_row brings it back for 30 days (see list_deleted_rows). A watcher sees the deletion live as op:delete on the change feed. Pass if_match for an optimistic-locked delete. Returns { deleted: true }.
| Argument | Type | Description |
|---|---|---|
| key* | string | The key of the row to delete. |
| app_id* | string | The app id. |
| if_match | integer | Optional optimistic-lock version. |
| collection* | string | The collection name. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection",
"key"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "The key of the row to delete."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"if_match": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Optional optimistic-lock version."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name."
}
}
}Deploy a v2 app: an HTML document plus a capability manifest, hosted at its own URL. For sandbox-authored files in hosted chat, native file editing and shell tools can create and validate the document. Its UTF-8 byte length and SHA-256 go to `document_upload`; the exact raw bytes are PUT to the returned `upload_url` with `Authorization: Bearer <upload_token>`, and the returned `document_id` is passed here. This works from any network-capable shell and does not require installing the Homespun CLI. Use `dry_run:true` first, then deploy with the same document_id and parameters. The 15-minute ticket accepts only the declared bytes; identical ticket + deploy parameters replay the original result for 24 hours, while changed bytes or deploy parameters require a fresh upload. If the shell cannot reach the upload host, send inline `html`. A redeploy only needs the content that changed. Every content field is optional when `app_id` is given, and an omitted one keeps what is live: omit `manifest` for an HTML-only change, omit `html` or `document_id` for a manifest-only change, omit `assets` to keep the current files. This is the cheap path and the default, because an omitted field costs no output tokens at all: a one-line colour change does not resend the whole document, and a manifest edit does not resend it either. A field only needs sending when its content differs from what is live. `assets: []` is the explicit way to clear the asset set, and omitting every content field is refused, since there would be nothing to change. The extension keys used most often: app metadata; collections, with per-collection write, update, read and delete role lists, where write gates creates and also gates updates unless an update list is declared; externalHosts, a fetch allowlist; cdn, to allow CDN scripts and styles; capabilities, for Permissions-Policy opt-ins; embeds, an iframe frame-src allowlist; notify, for email-on-row rules; webhooks, for signed HTTP POST on-row rules; and agentTasks, to queue work for an agent running on the owner's own machine, described as a prompt rather than as code. The manifest grammar is documented in the Homespun guide that get_skill returns. Pass no `app_id` to create, which mints a slug and URL and requires a document source (`html`, `html_path`, or `document_id`) and `manifest`, or pass `app_id` to redeploy an existing app. `document_id` is mutually exclusive with `html` and `html_path`. Supply the HTML inline as `html`, through `document_id`, or as `html_path`, an absolute path read on the MCP-server host, which is the relay for a hosted connector or the CLI host for a locally-run one, and not the remote agent's machine; it avoids retransmitting a large HTML file on every deploy, only a locally-run connector can read it, and inline `html` wins if both are given. `dry_run:true` (alias `check`) validates only: it runs the full manifest and asset validation, the redeploy compat gate and the schedule-timezone advisory, then returns { ok, warnings, compat?, breaks? } without creating a version or mutating anything, and it resolves omitted fields the same way a real deploy would, so it reports on exactly the deploy that would run. A redeploy is refused with manifest_incompatible_redeploy, unless force:true, when it would strand rows already written (dropping a collection, tightening a schema, flipping appendOnly), or when it would widen what the app's install screen discloses: a collection's read reaching further than the live manifest, a capability added, cdn turned on, or a host added to externalHosts, embeds or a webhook target. The break quotes the sentence a user would now be asked to approve. Taking access away never prompts: dropping a role, dropping a capability, host or webhook, turning cdn off, or adding update:[\"creator\"] to a write:[\"anyone\"] collection, all redeploy clean. A removed collection is detached rather than deleted. Images, fonts, audio, video and data files ship with the app in the same call via `assets[]`. Each is validated and stored app-scoped and served at its `path` on the app's own origin, so the HTML references it by a stable same-origin path such as `<img src=\"frames/000.jpg\">`; media and font paths support HTTP Range for seeking. A redeploy's assets replace the previous version's set when sent, carry over when omitted, and are cleared by `assets: []`. Returns { app_id, slug, url, version, visibility, created } on create, or { app_id, version, compat, breaks? } on redeploy.
Create a short-lived, byte-scoped upload session for an HTML document authored in a native editor or shell. The caller supplies the exact UTF-8 byte length and SHA-256 hex digest as { size, sha256, app_id? }. The returned `upload_url` accepts a PUT of those raw UTF-8 bytes with `Authorization: Bearer <upload_token>`; this ticket can upload only the declared bytes and is not an account credential. The returned `document_id` is used by `deploy_app` and is mutually exclusive with `html` and `html_path`. The ticket expires after 15 minutes. A retry with the same ticket and deploy parameters returns the original deployed result for 24 hours; changed content or deploy parameters need a fresh upload session. If the shell cannot reach the upload URL, inline deployment remains available. The PUT works from any network-capable shell and does not require the Homespun CLI.
| Argument | Type | Description |
|---|---|---|
| size* | integer | UTF-8 byte length of the HTML document. |
| app_id | string | Existing app id when this upload is for a redeploy; omit for a create. |
| sha256* | string | SHA-256 hex digest of the exact UTF-8 HTML bytes to upload. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"size",
"sha256"
],
"properties": {
"size": {
"type": "integer",
"maximum": 9007199254740991,
"description": "UTF-8 byte length of the HTML document.",
"exclusiveMinimum": 0
},
"app_id": {
"type": "string",
"description": "Existing app id when this upload is for a redeploy; omit for a create."
},
"sha256": {
"type": "string",
"pattern": "^[a-fA-F0-9]{64}$",
"description": "SHA-256 hex digest of the exact UTF-8 HTML bytes to upload."
}
}
}Reports a problem with homespun itself to the relay operator, and lists what this agent has already reported. A report is the operator's only visibility into a failure that happened inside an agent's session, so an unreported one is a failure nobody can fix. The channel covers homespun's own behaviour: a 5xx, or an error code the guide does not describe; a disagreement between documented and observed behaviour; something the tool surface cannot express, such as a missing capability or a schema that contradicts itself; an app misbehaving in a way that traces back to the platform (the bridge, the runtime, serving, the data API) rather than to authored HTML; or a guide that was wrong, ambiguous or silent. Outside its scope: the human's own task; bugs in an app the agent authored; presentation preferences, which belong in `taste`; the human's own configuration, such as a missing API key or the wrong account; and a 4xx caused by the agent's own arguments, except where the error message itself was misleading, which is a documentation problem best filed as a `note`. Duplicates cost the operator triage rather than adding signal. Action `list` returns this agent's own submissions, newest first, so a failure already recorded needs no second row: one report covers one distinct failure, however many times it was retried. The operator sees the row and not the session, so a bare "deploy failed" is not actionable. An actionable `message` carries the surface (mcp, cli, relay or app-runtime); where it happened (the tool or route); the skill version, from the `<!-- homespun skill vX.Y.Z -->` comment at the top of the guide; what was expected, in one line; what was observed, in one line carrying the exact error code and message; and the minimal steps or arguments that reproduce it. `type` is bug for something broken, feature for something missing, note for a rough edge or a confusing doc. `app_id` scopes a report to one app. There is no reply channel, so a report is not a route to an answer. Actions: create files one report; list returns this agent's own submissions, newest first, paginated by `before`.
| Argument | Type | Description |
|---|---|---|
| type | string | Feedback category (required for create). |
Poll a v2 app's change feed for what has happened: row creates, updates and deletes, from any writer, agent or human. It is the long-poll analogue of `homespun apps watch`, since MCP has no streaming. The loop is: call with no `since` first, process the returned entries, keep the cursor, then call again passing it as `since` to get only newer entries. Passing wait (around 25) holds the request open until an entry arrives or it times out, which is how the feed is waited on rather than busy-polled. A `since` older than the retention floor returns resync_required, and the collections are then re-listed with list_rows. Returns { entries, cursor, truncated }.
| Argument | Type | Description |
|---|---|---|
| wait | integer | Optional long-poll: how long the relay holds the request open waiting for a new entry (0-30s). Use ~25 when waiting for activity, then call again with the same cursor. |
| limit | integer | Max entries per page (capped server-side by FEED_PAGE_MAX). |
| since | integer | Opaque numeric cursor from a previous call's cursor. Omit (or 0) to read from the beginning. |
| app_id* | string | The app id. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id"
],
"properties": {
"wait": {
"type": "integer",
"maximum": 30,
"minimum": 0,
"description": "Optional long-poll: how long the relay holds the request open waiting for a new entry (0-30s). Use ~25 when waiting for activity, then call again with the same cursor."
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Max entries per page (capped server-side by FEED_PAGE_MAX).",
"exclusiveMinimum": 0
},
"since": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Opaque numeric cursor from a previous call's cursor. Omit (or 0) to read from the beginning."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
}
}
}Fetch a single row by its key from a v2 app collection, through a dedicated relay route rather than a client-side scan. Returns { row }, or an isError row_not_found.
| Argument | Type | Description |
|---|---|---|
| key* | string | The key of the row to fetch. |
| app_id* | string | The app id. |
| collection* | string | The collection name. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection",
"key"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "The key of the row to fetch."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name."
}
}
}The relay's SKILL.md, a generated guide to the Homespun workflow covering events versus records, the schema grammars and the poll loop. Needs no API key. Useful when working out how the other tools fit together, or to refresh a cached copy. Pass version_only:true to return just the relay's skill version string, which is enough to tell whether a cached copy is current.
| Argument | Type | Description |
|---|---|---|
| version_only | boolean | If true, return only the relay's current skill version string instead of the full SKILL.md markdown. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"version_only": {
"type": "boolean",
"description": "If true, return only the relay's current skill version string instead of the full SKILL.md markdown."
}
}
}A v2 app's grant links (M5). A grant link is a capability URL that confers a declared custom role (x-homespun-manifest.roles) on a stable per-holder anonymous identity, so a holder's own rows are isolated by author/:own scoping. A grant does not escalate to owner, member or agent. Actions: mint creates a link and returns a `grant_url` carrying the token in its #g= fragment, shown once and not recoverable afterwards; list returns the app's links and never a token; revoke is idempotent. mode 'once' is one-time, claimed by the first browser to open it; 'multi' is shared, capped by max_uses within expiry. An optional pin (pin_row_key or pin_where) narrows a holder to specific rows and never widens their access. One consequence worth knowing when minting: a write-only grant pinned to a single row key can still read that row's existing data back through create dedup, so such a grant exposes that row's current contents to the holder.
| Argument | Type | Description |
|---|---|---|
| mode | string | mint only. once: one-time link, claimed by the first browser that opens it (a real per-person link; later opens by others are inert). multi (default): a shared link, capped by max_uses within expiry. |
| role | string | mint only. A declared custom role for the app (an x-homespun-manifest.roles key). A built-in role (owner/member/agent/anyone) is rejected: a grant can never escalate. |
| label | string | mint only. Optional owner label shown in the grant list. |
| action* | string | mint: create a grant link carrying a declared custom role (app_id+role). list: the app's grant links (app_id). revoke: revoke one link (app_id+grant_id). |
A v2 app's inbound catch-hooks (inbound-webhooks). A catch-hook lets an external system such as Stripe, Zapier, Make, Home Assistant or an email router POST JSON to a secret URL that writes into a declared collection, so the app receives data with no agent online. Hooks are declared in the manifest (x-homespun-manifest.ingest) and materialized at deploy, so this tool has no create or delete: it reads back the URL, rotates a leaked one, and manages the opt-in signing secret. After deploying a manifest that declares a hook, list is what yields the exact URL to paste into the external system. Actions: list returns the app's hooks, each with its full secret URL, current rule collection, mode, wake and handshake settings, per-status delivery counts and signing-secret state; rotate mints a fresh URL secret for one hook by name and returns the new url once, after which the old url stops working immediately with no redeploy needed; set_signing_secret provisions or rotates a hook's signing secret, which is a different secret from the URL and is what a provider HMACs the body with, minting one returned once when `secret` is omitted or storing a provider value verbatim when it is passed, and never echoing it back; clear_signing_secret removes it. Signature verification currently ships dark: nothing verifies a signature yet.
| Argument | Type | Description |
|---|---|---|
| name | string | rotate / set_signing_secret / clear_signing_secret. The manifest ingest hook name (an x-homespun-manifest.ingest[].name). See list's `name` field. |
| action* | string | list: the app's inbound catch-hooks, each with its full secret URL, current rule (collection/mode/wake/handshake), and per-status delivery counts (app_id). rotate: mint a fresh URL secret for one hook and return its new URL once, invalidating the old URL immediately (app_id+name). set_signing_secret: provision or rotate a hook's opt-in signing secret, distinct from the URL secret (it is what a provider HMACs the body with); omit `secret` to mint one (returned once) or pass `secret` to store a provider-generated value verbatim (never echoed) (app_id+name). clear_signing_secret: remove a hook's signing secret (app_id+name). |
The calling agent's API key. Actions: list returns key info (agent_id, key_prefix, timestamps); mint creates a sibling API key for the caller's own agent identity with the same scope and ownership and returns its raw value once, which is how an MCP-driven agent hands a CLI or child process a working credential, and the raw value is not retrievable afterwards, the sibling appears in a later list made with it, and the owner can revoke it; revoke destroys the agent's own key, which stops working immediately and cannot be undone, so it requires confirm:true. The relay derives identity from the caller's token, so every action applies to the caller's own agent and mint cannot target another agent's id.
| Argument | Type | Description |
|---|---|---|
| action* | string | The calling agent's API key. list: key info (agent_id, key_prefix, timestamps). mint: mints a sibling API key for the calling agent's own identity (same scope/ownership) and returns its raw value once, which is what hands a CLI or child process a working credential; the sibling is a distinct key that shows up in a subsequent `list` made with it, the owner can revoke it, and the raw value is never retrievable again. mint always acts on the calling agent, never another agent's id. revoke: self-destructs the agent's own key, which stops working immediately and is irreversible (requires confirm:true). |
| confirm | boolean | Required (true) for revoke. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"action": {
"enum": [
"list",
"revoke",
"mint"
],
"type": "string",
"description": "The calling agent's API key. list: key info (agent_id, key_prefix, timestamps). mint: mints a sibling API key for the calling agent's own identity (same scope/ownership) and returns its raw value once, which is what hands a CLI or child process a working credential; the sibling is a distinct key that shows up in a subsequent `list` made with it, the owner can revoke it, and the raw value is never retrievable again. mint always acts on the calling agent, never another agent's id. revoke: self-destructs the agent's own key, which stops working immediately and is irreversible (requires confirm:true)."
},
"confirm": {
"type": "boolean",
"description": "Required (true) for revoke."
}
}
}List a collection's recently deleted rows: the recovery bin. Deleting a row is a soft delete, so it can be restored with restore_row until recoverable_until passes (30 days after deletion by default). Owner or agent only, and deliberately independent of the collection's read permissions. Rows already purged appear with purged:true and cannot be restored. Returns { rows, next_before }.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max rows to return (default 100). |
| app_id* | string | The app id. |
| before | string | Cursor for the next page: pass back the previous page's next_before. |
| collection* | string | The collection name. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Max rows to return (default 100)."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"before": {
"type": "string",
"description": "Cursor for the next page: pass back the previous page's next_before."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name."
}
}
}List rows in a v2 app's mutable collection. This is also how a collection's current state is polled, since MCP has no streaming: pass the prior next_cursor as `since` to fetch only rows that are new or changed. Returns { rows, next_cursor, has_more }.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Page size. |
| since | string | Opaque cursor from a previous call's next_cursor. Also the poll handle: pass it back to fetch only newer/changed rows. |
| app_id* | string | The app id. |
| collection* | string | The collection name declared in the app's manifest. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 1000,
"description": "Page size.",
"exclusiveMinimum": 0
},
"since": {
"type": "string",
"description": "Opaque cursor from a previous call's next_cursor. Also the poll handle: pass it back to fetch only newer/changed rows."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name declared in the app's manifest."
}
}
}A v2 app's membership (auth spec section 6): who besides the owner can sign in to a private app and write to member-scoped collections. Actions: add invites or attaches a member by email, attaching immediately when the email already has a Human and otherwise sending a magic-link invite; list returns the app's owner and members; set_role changes an existing member's declared custom role in place, or clears it when null, and leaves their sessions intact, which is what makes it the way to re-role someone rather than removing and re-adding them; remove is idempotent and also revokes the human's live sessions on this app, and the app owner cannot be removed; roles returns the derived roles summary, giving the effective access a holder actually has per declared role and collection, reported separately for signed-in members and for grant-link holders because their role floors differ, along with member and active-grant-link counts.
| Argument | Type | Description |
|---|---|---|
| role | string | add only. Defaults to 'member' server-side — no other role is assignable via this API (ownership transfer is not available here). |
| string | add only. The email to invite/attach. If a Human already exists for it, the member row is attached immediately; otherwise the relay emails a magic-link invite. | |
| action* | string | add: invite-or-attach a member by email (app_id+email; optional custom_roles). list: the app's owner + members (app_id). set_role: replace an existing member's declared roles in place without signing them out (app_id+human_id+custom_roles, an empty list to clear). remove: drop a member (app_id+human_id). roles: the app's declared roles with what each one includes and, per collection, the effective access a holder has (separately for members and grant-link holders, whose role floors differ) plus how many members and live grant links hold each role (app_id). |
The caller's community publisher identity: the @-handle and public profile shown in the template gallery. Actions: get returns the profile, including the handle, whether it has been claimed, tenure, and the rating and template counters; claim sets the handle from a lowercase 3-to-32-character string and may be used only once, after which the handle is permanent, and it refuses a handle that is reserved or already taken; update changes display_name, bio or url at any time. claim and update require a verified email. An existing publisher may hold a provisional `maker-...` handle assigned automatically, which claim renames on its one allowed use.
| Argument | Type | Description |
|---|---|---|
| bio | any | update only. Short public bio (up to 500 chars); null clears it. |
| url | any | update only. Public http(s) URL (up to 200 chars); null clears it. |
| action* | string | get: returns the caller's publisher profile (handle, tenure, counters). claim: sets the caller's @-handle, once (handle arg; lowercase, 3 to 32 chars, permanent after claiming; needs a verified email). update: changes the caller's public display_name/bio/url (any of them; needs a verified email). |
| handle | string | claim only. The lowercase @-handle to claim (^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$). Permanent once claimed. |
| display_name | any | update only. Public display name (up to 80 chars); null clears it. |
Restore a soft-deleted row, undoing delete_row. The row comes back with its original data and creator, its version bumped. Find restorable keys with list_deleted_rows. Owner or agent only. Fails with restore_expired if the row was purged, or restore_conflict if another live row took a unique value this one held while it was deleted. Returns { row }.
| Argument | Type | Description |
|---|---|---|
| key* | string | The key of the deleted row to restore. |
| app_id* | string | The app id. |
| collection* | string | The collection name. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection",
"key"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "The key of the deleted row to restore."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name."
}
}
}Ratings and reviews of community templates, responses from a template's own publisher, and, for relay operators, moderation. Actions: create leaves a 1-to-5 star rating and an optional written body on a template the caller has installed, identifying it by `template` (\"<handle>/<slug>\") or by `handle` plus `slug`, and requires a verified email; each install yields exactly one review, and the aggregate carries across template versions. A body containing a link or a contact email is held automatically for a moderator before it appears. respond replies to a review of the caller's own template line (review_id plus response, or null to clear it), with one editable response per review. report flags a review for the relay's moderators (review_id plus reason) and is deduped per account. remove and unhold are limited to the relay's configured community reviewers: remove takes a review down and adjusts the rating aggregate, and unhold publishes a previously held review into the aggregate.
| Argument | Type | Description |
|---|---|---|
| body | string | create only. Optional written review (up to 2000 chars). |
| slug | string | create only. Per-publisher slug (with `handle`). |
| stars | integer | create only. Star rating, an integer 1 to 5. |
| action* | string | create: leaves a star rating (1..5) and optional body on a community template the caller has installed (identified by `template` "<handle>/<slug>" or by `handle`+`slug`); requires a verified email, and one review per install. A body containing a link or contact email is auto-held for a moderator before it shows. respond: replies to a review of one of the caller's own templates (review_id + response; null clears it). report: flags a review for the relay's moderators (review_id + reason; one report per account). remove / unhold are relay-operator-only moderation actions on a review_id: remove takes a review down (adjusting the aggregate), unhold publishes a previously auto-held review. |
The agent's UI taste notes: a short freeform markdown document of presentation preferences gathered from human feedback, such as 'denser layout' or 'no rounded corners'. Reading it before generating or revising an app is what carries earlier feedback into new output. Actions: get returns the current document; set replaces it in whole, so it does not append; clear discards it. Scoped to presentation preferences rather than general storage.
| Argument | Type | Description |
|---|---|---|
| taste | string | The full markdown notes (required for set; whole-document replace, not append). |
| action* | string | The agent's freeform UI taste notes (markdown) — presentation preferences learned from human feedback. get: read them before generating an app. set: whole-document replace (taste, non-empty). clear: delete them. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"taste": {
"type": "string",
"description": "The full markdown notes (required for set; whole-document replace, not append)."
},
"action": {
"enum": [
"get",
"set",
"clear"
],
"type": "string",
"description": "The agent's freeform UI taste notes (markdown) — presentation preferences learned from human feedback. get: read them before generating an app. set: whole-document replace (taste, non-empty). clear: delete them."
}
}
}A v2 app's ownership transfer (issue #1847): handing the app, and the quota and billing responsibility that come with it, to a different human. This is two steps, and `start` completing is only the first one. start mints a pending offer and emails the named person an accept link; the app is still owned here when the call returns, stays owned here while the offer is pending, and only moves once that person opens the link and accepts it. Reporting the transfer as done after `start` would be wrong: check `status` to see whether it is still pending or has dropped to null (accepted, expired, or withdrawn), and the caller's own agent key stops being able to deploy this app only at the moment it actually moves. Actions: start offers the app to an email address, 409ing if a transfer is already pending or the email already owns the app; status returns the pending transfer, or null if none; cancel withdraws a pending transfer and is idempotent, so cancelling with nothing pending is still a success.
| Argument | Type | Description |
|---|---|---|
| string | start only. The email to offer ownership to. The relay sends that address an accept link; ownership moves only when they open it and accept, never at start itself. 409s if a transfer is already pending for this app, or if the email already owns it. | |
| action* | string | A v2 app's ownership transfer (issue #1847). start does not move ownership: it only mints a pending offer and emails the named person an accept link, and the app stays owned here until they open it and accept (app_id+email; optional keep_as_member). status: the app's pending transfer, or null if none is pending (app_id). cancel: withdraw a pending transfer; idempotent, so cancelling with none pending is still a success (app_id). |
| app_id* | string |
Update an existing row in a v2 app's collection, replacing its data. Gated by the collection's `update` role list when it declares one, and by its `write` list otherwise, so a collection that scopes updates to the row's `creator` refuses an edit on someone else's row. Pass if_match with the row's current version for an optimistic-locked update; on a version mismatch the relay returns the current row, which is what a retry needs. Returns { row }.
| Argument | Type | Description |
|---|---|---|
| key* | string | The key of the row to update. |
| data* | any | The new row body (replaces the row's data) - any JSON value valid against the collection's row schema. |
| app_id* | string | The app id. |
| if_match | integer | Optional optimistic-lock version. On mismatch the update is rejected with the current row in details.current. |
| collection* | string | The collection name. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app_id",
"collection",
"key",
"data"
],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "The key of the row to update."
},
"data": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "array",
"items": {}
},
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "The new row body (replaces the row's data) - any JSON value valid against the collection's row schema."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"if_match": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Optional optimistic-lock version. On mismatch the update is rejected with the current row in details.current."
},
"collection": {
"type": "string",
"minLength": 1,
"description": "The collection name."
}
}
}| Argument | Type | Description |
|---|
| slug | string | list only. Exact-match slug filter. |
| limit | integer | list only. Page size. |
| action* | string | list: the caller's owning human's apps. show/update/delete/wake: act on one app (app_id). audit: read-only security review of every app the caller owns. share_link_rotate: rotate a 'link' app's share token, returning a new share_url (the old link stops working); also generates one if the app has none yet. list_deleted: the apps in the trash, each with when it is purged for good. restore: bring a deleted app back with all its data (app_id). purge: destroy a deleted app forever, now (app_id). domain_set/domain_status/domain_remove: manage the app's custom domains (app_id; domain_set also needs domain). |
| app_id | string | Required for show/update/share_link_rotate/delete/restore/purge/wake/domain_set/domain_status/domain_remove. |
| cursor | string | list only. Opaque cursor from a previous next_cursor. |
| domain | string | domain_set: the bare custom domain to bind (e.g. app.example.com); the response's dns_records lists the DNS entries the domain owner must publish. domain_remove: optional, the one domain to unbind - omit it to unbind them all. |
| status | string | list only. Default: active. 'all' means every live status; deleted apps are never in this list, use action list_deleted for those. |
| severity | string | audit only. Return findings of this severity only. The response's `counts` always describe the whole audit, so filtering never hides that other findings exist. |
| timezone | string | update only. The app's IANA timezone for `schedules` reminders (e.g. Europe/Berlin). An app that declares schedules with no timezone fires reminders at 08:00 UTC. |
| visibility | string | update only. The new visibility (slug is immutable). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"slug": {
"type": "string",
"description": "list only. Exact-match slug filter."
},
"limit": {
"type": "integer",
"maximum": 200,
"description": "list only. Page size.",
"exclusiveMinimum": 0
},
"action": {
"enum": [
"list",
"show",
"audit",
"update",
"share_link_rotate",
"delete",
"list_deleted",
"restore",
"purge",
"wake",
"domain_set",
"domain_status",
"domain_remove"
],
"type": "string",
"description": "list: the caller's owning human's apps. show/update/delete/wake: act on one app (app_id). audit: read-only security review of every app the caller owns. share_link_rotate: rotate a 'link' app's share token, returning a new share_url (the old link stops working); also generates one if the app has none yet. list_deleted: the apps in the trash, each with when it is purged for good. restore: bring a deleted app back with all its data (app_id). purge: destroy a deleted app forever, now (app_id). domain_set/domain_status/domain_remove: manage the app's custom domains (app_id; domain_set also needs domain)."
},
"app_id": {
"type": "string",
"description": "Required for show/update/share_link_rotate/delete/restore/purge/wake/domain_set/domain_status/domain_remove."
},
"cursor": {
"type": "string",
"description": "list only. Opaque cursor from a previous next_cursor."
},
"domain": {
"type": "string",
"description": "domain_set: the bare custom domain to bind (e.g. app.example.com); the response's dns_records lists the DNS entries the domain owner must publish. domain_remove: optional, the one domain to unbind - omit it to unbind them all."
},
"status": {
"enum": [
"active",
"dormant",
"archived",
"suspended",
"all"
],
"type": "string",
"description": "list only. Default: active. 'all' means every live status; deleted apps are never in this list, use action list_deleted for those."
},
"severity": {
"enum": [
"high",
"medium",
"low"
],
"type": "string",
"description": "audit only. Return findings of this severity only. The response's `counts` always describe the whole audit, so filtering never hides that other findings exist."
},
"timezone": {
"type": "string",
"description": "update only. The app's IANA timezone for `schedules` reminders (e.g. Europe/Berlin). An app that declares schedules with no timezone fires reminders at 08:00 UTC."
},
"visibility": {
"enum": [
"private",
"link",
"public"
],
"type": "string",
"description": "update only. The new visibility (slug is immutable)."
}
}
}| upload/presign: advisory Content-Type. The relay byte-sniffs the actual bytes and stores/serves that sniffed type regardless (a lying mime is caught, never served inline). Required for presign (scopes the upload URL + fails fast against the allowlist). |
| once | boolean | mint_token: token self-deletes on first GET. |
| size | integer | presign: the exact byte length you will PUT. Committed at presign and re-verified against the uploaded bytes at finalize. |
| limit | integer | list page size (1..100). |
| scope | string | upload scope (default agent). |
| action* | string | Binary attachment operations. The upload path affects token cost: `fetch` and presign plus finalize keep the bytes out of the model context entirely, while upload with `content_base64` carries them in the tool-call arguments at a cost proportional to file size, paid again on every retry. fetch takes { source_url, scope } and the relay downloads the bytes itself (https only, SSRF-guarded), running the same sniff, allowlist, size, quota and scan checks as any upload. upload takes `content_base64` (base64 bytes, no filesystem) or `file_path` (absolute, read on the relay host), scoped agent or app. presign plus finalize is three steps: presign with { mime, size, sha256, scope }, PUT the bytes to put_url out of band, then finalize, which re-sniffs and re-checks them. download fetches bytes by attachment_id to an absolute out_path or returns base64. show returns metadata only. list returns the agent's attachments. delete is a soft-delete. mint_token mints a /b/<token> capability URL, returned once. revoke_token and list_tokens manage those tokens. |
| app_id | string | Required when scope=app. |
| cursor | string | list pagination cursor. |
| sha256 | string | presign: the hex SHA-256 (64 chars) of the exact bytes you will PUT. Committed at presign and re-verified against the uploaded bytes at finalize. |
| filename | string | upload: display filename (defaults to the file's basename). |
| out_path | string | download: absolute path to write the bytes to. If omitted, the bytes are returned base64-encoded in the result. |
| token_id | string | revoke_token: the token id to revoke. |
| file_path | string | upload: absolute path to a file read on the server host running this MCP connector (the relay), not the calling agent's machine. It resolves only when the file is local to the relay (e.g. a locally-run CLI); a hosted or remote agent supplies the bytes as `content_base64` instead. |
| source_url | string | fetch: an https URL the relay downloads server-side, so the bytes do not enter the model context and cost no tokens. SSRF-guarded: https only, no private, loopback, link-local or metadata hosts, DNS pinned, redirects refused, size-capped and timed out. The downloaded bytes run the same byte-sniff, allowlist, size, quota and scan checks as any upload. This and presign plus finalize are the zero-context paths for real images and media. |
| ttl_seconds | integer | mint_token: per-token TTL (clamped by scope default). |
| attachment_id | string | Attachment id. Required for download/show/delete/mint_token/revoke_token/list_tokens. |
| content_base64 | string | upload: the file bytes as base64, sent inline with no filesystem access. The base64 rides in the tool-call arguments and enters the model context, costing tokens proportional to file size; a few-hundred-KB image is already expensive, and the cost repeats on every retry. presign plus finalize avoids that for any real image or media whenever the client can do an out-of-band HTTP PUT, which leaves `content_base64` suited to small assets such as a tiny icon, and to clients that cannot PUT out of band. If both `content_base64` and `file_path` are given, `content_base64` wins. The relay sniffs the real type and enforces the same size, allowlist and quota checks as a file upload. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"mime": {
"type": "string",
"description": "upload/presign: advisory Content-Type. The relay byte-sniffs the actual bytes and stores/serves that sniffed type regardless (a lying mime is caught, never served inline). Required for presign (scopes the upload URL + fails fast against the allowlist)."
},
"once": {
"type": "boolean",
"description": "mint_token: token self-deletes on first GET."
},
"size": {
"type": "integer",
"maximum": 9007199254740991,
"description": "presign: the exact byte length you will PUT. Committed at presign and re-verified against the uploaded bytes at finalize.",
"exclusiveMinimum": 0
},
"limit": {
"type": "integer",
"maximum": 100,
"description": "list page size (1..100).",
"exclusiveMinimum": 0
},
"scope": {
"enum": [
"agent",
"app"
],
"type": "string",
"description": "upload scope (default agent)."
},
"action": {
"enum": [
"upload",
"fetch",
"presign",
"finalize",
"download",
"show",
"list",
"delete",
"mint_token",
"revoke_token",
"list_tokens"
],
"type": "string",
"description": "Binary attachment operations. The upload path affects token cost: `fetch` and presign plus finalize keep the bytes out of the model context entirely, while upload with `content_base64` carries them in the tool-call arguments at a cost proportional to file size, paid again on every retry. fetch takes { source_url, scope } and the relay downloads the bytes itself (https only, SSRF-guarded), running the same sniff, allowlist, size, quota and scan checks as any upload. upload takes `content_base64` (base64 bytes, no filesystem) or `file_path` (absolute, read on the relay host), scoped agent or app. presign plus finalize is three steps: presign with { mime, size, sha256, scope }, PUT the bytes to put_url out of band, then finalize, which re-sniffs and re-checks them. download fetches bytes by attachment_id to an absolute out_path or returns base64. show returns metadata only. list returns the agent's attachments. delete is a soft-delete. mint_token mints a /b/<token> capability URL, returned once. revoke_token and list_tokens manage those tokens."
},
"app_id": {
"type": "string",
"description": "Required when scope=app."
},
"cursor": {
"type": "string",
"description": "list pagination cursor."
},
"sha256": {
"type": "string",
"description": "presign: the hex SHA-256 (64 chars) of the exact bytes you will PUT. Committed at presign and re-verified against the uploaded bytes at finalize."
},
"filename": {
"type": "string",
"description": "upload: display filename (defaults to the file's basename)."
},
"out_path": {
"type": "string",
"description": "download: absolute path to write the bytes to. If omitted, the bytes are returned base64-encoded in the result."
},
"token_id": {
"type": "string",
"description": "revoke_token: the token id to revoke."
},
"file_path": {
"type": "string",
"description": "upload: absolute path to a file read on the server host running this MCP connector (the relay), not the calling agent's machine. It resolves only when the file is local to the relay (e.g. a locally-run CLI); a hosted or remote agent supplies the bytes as `content_base64` instead."
},
"source_url": {
"type": "string",
"description": "fetch: an https URL the relay downloads server-side, so the bytes do not enter the model context and cost no tokens. SSRF-guarded: https only, no private, loopback, link-local or metadata hosts, DNS pinned, redirects refused, size-capped and timed out. The downloaded bytes run the same byte-sniff, allowlist, size, quota and scan checks as any upload. This and presign plus finalize are the zero-context paths for real images and media."
},
"ttl_seconds": {
"type": "integer",
"maximum": 9007199254740991,
"description": "mint_token: per-token TTL (clamped by scope default).",
"exclusiveMinimum": 0
},
"attachment_id": {
"type": "string",
"description": "Attachment id. Required for download/show/delete/mint_token/revoke_token/list_tokens."
},
"content_base64": {
"type": "string",
"description": "upload: the file bytes as base64, sent inline with no filesystem access. The base64 rides in the tool-call arguments and enters the model context, costing tokens proportional to file size; a few-hundred-KB image is already expensive, and the cost repeats on every retry. presign plus finalize avoids that for any real image or media whenever the client can do an out-of-band HTTP PUT, which leaves `content_base64` suited to small assets such as a tiny icon, and to clients that cannot PUT out of band. If both `content_base64` and `file_path` are given, `content_base64` wins. The relay sniffs the real type and enforces the same size, allowlist and quota checks as a file upload."
}
}
}| Description |
|---|
| ref | string | get_config_contract/install only. The template to read or install: a namespaced '<handle>/<slug>' or a community snapshot id. |
| note | string | reject only. The required rejection note shown to the publisher (delivered to their app feed). |
| slug | string | publish only. Optional per-publisher slug (lowercase, 3 to 48 chars, hyphens). Gives the template a namespaced id <handle>/<slug>; a republish reuses the slug and must bump the version. If omitted, a slug is derived from the title instead of leaving the template unnamed, so this field matters only when a specific url is wanted. Slugs are immutable: renaming the template later does not move its url, so the slug chosen here is permanent. |
| tags | array | publish only. Up to 6 curation tags. |
| limit | integer | list_pending only. Page size (1..200). |
| title | string | publish only. Listing title (1 to 80 chars). Defaults to the app's manifest name. |
| action* | string | publish: publishes one of the caller's apps as a community template (app_id; optional title/description/category/tags). Privacy consequence: publishing makes the template content and the captured seed rows (the live rows of every seedOnInstall collection, captured at publish time) public to every platform user once approved, so an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private) is not safe to publish: seed data must be example-only. attest_example_only:true records that this was checked. The capture (html + manifest + seed rows) lands pending review, installable by its returned direct link but not listed until approved; an established publisher is fast-tracked, and the response's expedited/auto_approved fields report which path it took. unpublish: takes one of the caller's own published templates back down (snapshot_id). It removes the listing from the public gallery, from search, and from the direct snapshot install link. Existing installs keep working untouched, because an install is a fresh private copy rather than a live reference. It is idempotent (unpublishing an already-unpublished template is a no-op), and a snapshot that does not exist or belongs to someone else reads as not found either way. Publishing a new version is what puts the listing back. get_config_contract: read a template's install-time config contract by `ref` (a namespaced '<handle>/<slug>' or a snapshot id): its settings_collection, ordered config_steps (each with key/kind/required/secret/choices/default), and connect_steps (inbound hooks the app receives on). An 'upload' step wants a file, pre-uploaded with the attachments tool (scope agent) and passed as its attachment id. A template installed with connect_steps provisions hook URLs, which the `ingest` tool's list action returns for the new app_id, ready to wire into the external service. install: installs a template by `ref` for the caller, whose owning human becomes the owner. `config` is { stepKey: value } from the contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. An omitted required step is rejected. Returns the new app's id, slug, and url; installs always create a fresh private copy. list_pending / get_submission / approve / reject / set_trust_level are relay-operator-only review actions: list_pending (the review queue, expedited submissions first), get_submission (a submission's full html+manifest+seedRows plus external_destinations, the hosts it can send data to or pull data from, by snapshot_id), approve (snapshot_id, lists it in the gallery + supersedes the app's prior approved version), reject (snapshot_id + a required note that lands in the publisher's app feed), set_trust_level (promote/demote a publisher by handle: handle + trust_level 'new'|'established'). upgrade_check / upgrade / revert keep an already-installed app current with its source template (app_id). An install is a one-shot fork, so nothing updates on its own and there is no follow/pin: you have to ask. upgrade_check reports whether a newer live version of that app's template line exists, whether it would apply cleanly, and what it would newly be allowed to reach. upgrade applies it in place, keeping the app's address, collections and rows, and landing as a new version you can undo. It refuses outright, with no override, when the new version would strand rows the app already holds; when the new version merely asks for more than the installed one, pass accept_permissions:true, but only after showing the owner what `permission_lines` says. revert puts the app back on the version it ran before the last update, and refuses when rows written since would have nowhere to live under the older one. |
| app_id | string | publish / upgrade_check / upgrade / revert. For publish, the app to publish. For the three upgrade actions, the installed app to act on: an installed template is a fork, so the question is whether a newer version of the template that app came from exists, which only the app can answer. |
| config | object | install only. The install-time answers as { stepKey: value } from the config contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. Omit for a template with no config steps. |
| cursor | string | list_pending only. Opaque cursor from a prior next_cursor. |
| handle | string | set_trust_level only. The @-handle of the publisher to promote or demote. |
| version | string | publish only. Semver MAJOR.MINOR.PATCH (default '1.0.0'). A republish under the same slug must be strictly greater than the current version. |
| category | string | publish only. Optional single-word category (e.g. 'household'). |
| description | string | publish only. Listing blurb (up to 200 chars). Defaults to the manifest description. |
| setup_steps | array | publish only. Ordered typed setup steps an installing agent follows after install (up to 20). A 'config'/'upload' step may carry a `key` naming a field of the manifest's settingsCollection that its install-time answer is written into; a 'connect' step may carry an `ingestRule` naming a manifest ingest rule it wires up. Read back via get_submission and rendered on the template detail page. |
| snapshot_id | string | Required for get_submission/unpublish/approve/reject. The submission's snapshot id (from publish's response or list_pending). |
| trust_level | string | set_trust_level only. 'established' fast-tracks the publisher's future submissions through review; 'new' reverts to full review. |
| changelog_note | string | publish only. A short note recorded in this version's changelog. |
| expect_version | string | upgrade only. The version upgrade_check reported. When given, the upgrade is refused if the offer has moved since, so a publisher shipping again mid-flight cannot slip a version past you that you never showed anyone. |
| long_description | string | publish only. Optional long-form description (up to 4000 chars) shown on the template detail page below the short blurb, for readers and search ranking. Plain text: blank lines become paragraphs, and it is escaped (never rendered as raw HTML), so write prose, not markup. |
| accept_permissions | boolean | upgrade only. Required when upgrade_check reports a non-empty `permissions` diff, meaning the new version asks for more than the installed one (new hosts it can send data to, new device capabilities, a service worker, CDN scripts). Never assume it: show the owner `permission_lines` and set this only once they have agreed. It does not clear a version that would strand rows, which nothing can. |
| attest_example_only | boolean | publish only. True attests that the template content and the captured seed rows contain no real personal data. Publishing makes both public to every platform user, so seed data (the live rows of the app's seedOnInstall collections) must be example-only, never real names/emails/addresses/private messages. Recorded and shown to the reviewer; omitting it still publishes but is flagged to the operator as not attested. |
| derived_from_snapshot_id | string | publish only. Optional remix/fork lineage: the snapshot id this template was derived from. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"ref": {
"type": "string",
"description": "get_config_contract/install only. The template to read or install: a namespaced '<handle>/<slug>' or a community snapshot id."
},
"note": {
"type": "string",
"description": "reject only. The required rejection note shown to the publisher (delivered to their app feed)."
},
"slug": {
"type": "string",
"description": "publish only. Optional per-publisher slug (lowercase, 3 to 48 chars, hyphens). Gives the template a namespaced id <handle>/<slug>; a republish reuses the slug and must bump the version. If omitted, a slug is derived from the title instead of leaving the template unnamed, so this field matters only when a specific url is wanted. Slugs are immutable: renaming the template later does not move its url, so the slug chosen here is permanent."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "publish only. Up to 6 curation tags."
},
"limit": {
"type": "integer",
"maximum": 200,
"description": "list_pending only. Page size (1..200).",
"exclusiveMinimum": 0
},
"title": {
"type": "string",
"description": "publish only. Listing title (1 to 80 chars). Defaults to the app's manifest name."
},
"action": {
"enum": [
"publish",
"unpublish",
"get_config_contract",
"install",
"upgrade_check",
"upgrade",
"revert",
"list_pending",
"get_submission",
"approve",
"reject",
"set_trust_level"
],
"type": "string",
"description": "publish: publishes one of the caller's apps as a community template (app_id; optional title/description/category/tags). Privacy consequence: publishing makes the template content and the captured seed rows (the live rows of every seedOnInstall collection, captured at publish time) public to every platform user once approved, so an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private) is not safe to publish: seed data must be example-only. attest_example_only:true records that this was checked. The capture (html + manifest + seed rows) lands pending review, installable by its returned direct link but not listed until approved; an established publisher is fast-tracked, and the response's expedited/auto_approved fields report which path it took. unpublish: takes one of the caller's own published templates back down (snapshot_id). It removes the listing from the public gallery, from search, and from the direct snapshot install link. Existing installs keep working untouched, because an install is a fresh private copy rather than a live reference. It is idempotent (unpublishing an already-unpublished template is a no-op), and a snapshot that does not exist or belongs to someone else reads as not found either way. Publishing a new version is what puts the listing back. get_config_contract: read a template's install-time config contract by `ref` (a namespaced '<handle>/<slug>' or a snapshot id): its settings_collection, ordered config_steps (each with key/kind/required/secret/choices/default), and connect_steps (inbound hooks the app receives on). An 'upload' step wants a file, pre-uploaded with the attachments tool (scope agent) and passed as its attachment id. A template installed with connect_steps provisions hook URLs, which the `ingest` tool's list action returns for the new app_id, ready to wire into the external service. install: installs a template by `ref` for the caller, whose owning human becomes the owner. `config` is { stepKey: value } from the contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. An omitted required step is rejected. Returns the new app's id, slug, and url; installs always create a fresh private copy. list_pending / get_submission / approve / reject / set_trust_level are relay-operator-only review actions: list_pending (the review queue, expedited submissions first), get_submission (a submission's full html+manifest+seedRows plus external_destinations, the hosts it can send data to or pull data from, by snapshot_id), approve (snapshot_id, lists it in the gallery + supersedes the app's prior approved version), reject (snapshot_id + a required note that lands in the publisher's app feed), set_trust_level (promote/demote a publisher by handle: handle + trust_level 'new'|'established').\n\nupgrade_check / upgrade / revert keep an already-installed app current with its source template (app_id). An install is a one-shot fork, so nothing updates on its own and there is no follow/pin: you have to ask. upgrade_check reports whether a newer live version of that app's template line exists, whether it would apply cleanly, and what it would newly be allowed to reach. upgrade applies it in place, keeping the app's address, collections and rows, and landing as a new version you can undo. It refuses outright, with no override, when the new version would strand rows the app already holds; when the new version merely asks for more than the installed one, pass accept_permissions:true, but only after showing the owner what `permission_lines` says. revert puts the app back on the version it ran before the last update, and refuses when rows written since would have nowhere to live under the older one."
},
"app_id": {
"type": "string",
"description": "publish / upgrade_check / upgrade / revert. For publish, the app to publish. For the three upgrade actions, the installed app to act on: an installed template is a fork, so the question is whether a newer version of the template that app came from exists, which only the app can answer."
},
"config": {
"type": "object",
"description": "install only. The install-time answers as { stepKey: value } from the config contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. Omit for a template with no config steps.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"cursor": {
"type": "string",
"description": "list_pending only. Opaque cursor from a prior next_cursor."
},
"handle": {
"type": "string",
"description": "set_trust_level only. The @-handle of the publisher to promote or demote."
},
"version": {
"type": "string",
"description": "publish only. Semver MAJOR.MINOR.PATCH (default '1.0.0'). A republish under the same slug must be strictly greater than the current version."
},
"category": {
"type": "string",
"description": "publish only. Optional single-word category (e.g. 'household')."
},
"description": {
"type": "string",
"description": "publish only. Listing blurb (up to 200 chars). Defaults to the manifest description."
},
"setup_steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"label"
],
"properties": {
"key": {
"type": "string",
"description": "The settings-collection field this answer is written into (letters, digits, '_', up to 64 chars). Required for an 'upload' step, optional for a 'config' step, not allowed on the others. Must name a declared top-level field of the manifest's x-homespun-manifest.settingsCollection; an 'upload' target must be a string-typed field."
},
"kind": {
"enum": [
"config",
"seed-data",
"connect",
"note",
"upload"
],
"type": "string",
"description": "config = set a value; upload = an install-time file/image the app stores as an attachment id; connect = wire up an external data source; seed-data = review/replace captured starter data; note = a plain instruction."
},
"label": {
"type": "string",
"description": "Short step label (<= 80 chars)."
},
"secret": {
"type": "boolean",
"description": "Mark a step whose value is sensitive (an API key/token). Its default is MASKED on the public detail page; publish only your own example default, never a real secret."
},
"choices": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of allowed values (up to 12)."
},
"default": {
"type": "string",
"description": "Optional example/default value (<= 200 chars)."
},
"required": {
"type": "boolean",
"description": "Whether this step is required (default false)."
},
"valueHint": {
"type": "string",
"description": "Optional format hint (<= 120 chars)."
},
"ingestRule": {
"type": "string",
"description": "The manifest `ingest` rule this step wires up. Allowed only on a 'connect' step, and optional there; publish rejects a name that x-homespun-manifest.ingest does not declare. Each install mints that rule its own hook URL, which the installer pastes into the external service."
},
"description": {
"type": "string",
"description": "Optional longer instruction (<= 300 chars)."
}
}
},
"description": "publish only. Ordered typed setup steps an installing agent follows after install (up to 20). A 'config'/'upload' step may carry a `key` naming a field of the manifest's settingsCollection that its install-time answer is written into; a 'connect' step may carry an `ingestRule` naming a manifest ingest rule it wires up. Read back via get_submission and rendered on the template detail page."
},
"snapshot_id": {
"type": "string",
"description": "Required for get_submission/unpublish/approve/reject. The submission's snapshot id (from publish's response or list_pending)."
},
"trust_level": {
"enum": [
"new",
"established"
],
"type": "string",
"description": "set_trust_level only. 'established' fast-tracks the publisher's future submissions through review; 'new' reverts to full review."
},
"changelog_note": {
"type": "string",
"description": "publish only. A short note recorded in this version's changelog."
},
"expect_version": {
"type": "string",
"description": "upgrade only. The version upgrade_check reported. When given, the upgrade is refused if the offer has moved since, so a publisher shipping again mid-flight cannot slip a version past you that you never showed anyone."
},
"long_description": {
"type": "string",
"description": "publish only. Optional long-form description (up to 4000 chars) shown on the template detail page below the short blurb, for readers and search ranking. Plain text: blank lines become paragraphs, and it is escaped (never rendered as raw HTML), so write prose, not markup."
},
"accept_permissions": {
"type": "boolean",
"description": "upgrade only. Required when upgrade_check reports a non-empty `permissions` diff, meaning the new version asks for more than the installed one (new hosts it can send data to, new device capabilities, a service worker, CDN scripts). Never assume it: show the owner `permission_lines` and set this only once they have agreed. It does not clear a version that would strand rows, which nothing can."
},
"attest_example_only": {
"type": "boolean",
"description": "publish only. True attests that the template content and the captured seed rows contain no real personal data. Publishing makes both public to every platform user, so seed data (the live rows of the app's seedOnInstall collections) must be example-only, never real names/emails/addresses/private messages. Recorded and shown to the reviewer; omitting it still publishes but is flagged to the operator as not attested."
},
"derived_from_snapshot_id": {
"type": "string",
"description": "publish only. Optional remix/fork lineage: the snapshot id this template was derived from."
}
}
}| app_id* | string | The app id. |
| scopes | string | create only (oauth2). Space-delimited scopes for the authorize request. |
| provider | string | create only. Freeform display label only, e.g. "hubspot"; not validated against any allowlist. |
| client_id | string | create only, required for kind=oauth2. Your OAuth2 app's client id. |
| auth_params | object | create only (oauth2). Extra key/values merged into the authorize redirect (e.g. to request offline access). |
| auth_scheme | string | create only (oauth2). The scheme the access token is sent under. Defaults to "Bearer"; set e.g. "Zoho-oauthtoken" for a non-Bearer provider. |
| header_name | string | create only (static). The header the credential rides in. Defaults to "Authorization". |
| allowed_host | string | create only, required for both kinds. The host-binding exfiltration defence: an exact DNS host ("api.hubapi.com") or a single leftmost wildcard ("*.zohoapis.com"). The stored credential is attached to a delivery only when its url host matches; a rule later repointed elsewhere fails delivery rather than sending the secret to the wrong host. |
| header_value | string | create only, required for kind=static. The header value to send, e.g. "Bearer sk_live_...". Encrypted at rest and never returned by any call. |
| token_params | object | create only (oauth2). Extra key/values merged into the token POST. |
| authorize_url | string | create only, required for kind=oauth2. The provider's OAuth2 authorize endpoint (https; rejected if it resolves to a private/loopback/metadata address). |
| client_secret | string | create only, required for kind=oauth2. Your OAuth2 app's client secret. Encrypted at rest and never returned by any call. |
| instance_field | string | create only (oauth2). The name of a token-response JSON field holding the API base URL (e.g. "instance_url"). When set, the relay re-binds allowed_host to that host after consent and resolves relative rule urls against it. |
| token_endpoint | string | create only, required for kind=oauth2. The provider's OAuth2 token endpoint (same https + SSRF rules as authorize_url). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action",
"app_id"
],
"properties": {
"kind": {
"enum": [
"static",
"oauth2"
],
"type": "string",
"description": "create only. Defaults to `static`."
},
"name": {
"type": "string",
"description": "create / delete / consent_url. The connection name (lowercase, starting alphanumeric, up to 64 chars) that a manifest webhook rule's `connection` field references."
},
"label": {
"type": "string",
"description": "create only. Optional owner-facing label."
},
"action": {
"enum": [
"create",
"list",
"delete",
"consent_url"
],
"type": "string",
"description": "create: store a webhook connection, a stored credential (static header token or a full generic OAuth2 client) a manifest webhook rule authenticates its target with (app_id+name+allowed_host, plus kind-specific fields). list: the app's connections as metadata plus a non-reversible fingerprint, never any secret (app_id). delete: idempotent (app_id+name). consent_url: build (never fetch) the browser URL that completes an oauth2 connection's owner consent (app_id+name); hand it to the signed-in owner to open, since an agent key cannot complete OAuth consent itself."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"scopes": {
"type": "string",
"description": "create only (oauth2). Space-delimited scopes for the authorize request."
},
"provider": {
"type": "string",
"description": "create only. Freeform display label only, e.g. \"hubspot\"; not validated against any allowlist."
},
"client_id": {
"type": "string",
"description": "create only, required for kind=oauth2. Your OAuth2 app's client id."
},
"auth_params": {
"type": "object",
"description": "create only (oauth2). Extra key/values merged into the authorize redirect (e.g. to request offline access).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"auth_scheme": {
"type": "string",
"description": "create only (oauth2). The scheme the access token is sent under. Defaults to \"Bearer\"; set e.g. \"Zoho-oauthtoken\" for a non-Bearer provider."
},
"header_name": {
"type": "string",
"description": "create only (static). The header the credential rides in. Defaults to \"Authorization\"."
},
"allowed_host": {
"type": "string",
"description": "create only, required for both kinds. The host-binding exfiltration defence: an exact DNS host (\"api.hubapi.com\") or a single leftmost wildcard (\"*.zohoapis.com\"). The stored credential is attached to a delivery only when its url host matches; a rule later repointed elsewhere fails delivery rather than sending the secret to the wrong host."
},
"header_value": {
"type": "string",
"description": "create only, required for kind=static. The header value to send, e.g. \"Bearer sk_live_...\". Encrypted at rest and never returned by any call."
},
"token_params": {
"type": "object",
"description": "create only (oauth2). Extra key/values merged into the token POST.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"authorize_url": {
"type": "string",
"description": "create only, required for kind=oauth2. The provider's OAuth2 authorize endpoint (https; rejected if it resolves to a private/loopback/metadata address)."
},
"client_secret": {
"type": "string",
"description": "create only, required for kind=oauth2. Your OAuth2 app's client secret. Encrypted at rest and never returned by any call."
},
"instance_field": {
"type": "string",
"description": "create only (oauth2). The name of a token-response JSON field holding the API base URL (e.g. \"instance_url\"). When set, the relay re-binds allowed_host to that host after consent and resolves relative rule urls against it."
},
"token_endpoint": {
"type": "string",
"description": "create only, required for kind=oauth2. The provider's OAuth2 token endpoint (same https + SSRF rules as authorize_url)."
}
}
}| app_id* | string | The app id. |
| grants | array | mint only. The allowlist: one entry per collection naming which of read/create/update/delete this credential may attempt there (an entry may name zero ops, which under `following` is how one collection is carved out of an otherwise app-wide credential). A collection named here must be a real declared collection on the app; a typo is rejected with a 400 rather than silently doing nothing. |
| members | boolean | mint only. Opt in to the app's member directory appearing in this credential's boot/hello payloads. Defaults to false: a credential that never learns a member id cannot stamp one into a relation field. |
| ttl_seconds | any | mint only. Omit for the server's bounded default (365 days, clamped to a server maximum). null means no expiry, the explicit opt-in a long-running backend asks for; it is never the default. |
| credential_id | string | pause / resume / rotate / revoke. The credential id (see list's `id` field). |
| overlap_seconds | integer | rotate only. How long the superseded token keeps resolving, so a running backend can pick up the new one with no gap. Defaults to the server default (1 day); 0 kills the old token immediately, the "this leaked" case. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action",
"app_id"
],
"properties": {
"mode": {
"enum": [
"explicit",
"following"
],
"type": "string",
"description": "mint only. Defaults to explicit: an unnamed collection is denied, so the credential can never reach anything it was not handed (the shape for a contractor's backend). following: an unnamed collection falls through to the owner's own authority, so the credential tracks the app as it grows and each `grants` entry only narrows one collection (the shape for the owner's own backend). Neither mode can ever exceed what the app's owner could do; the effective permission is always the intersection."
},
"label": {
"type": "string",
"description": "mint only. Optional owner-facing label shown in the credential list."
},
"action": {
"enum": [
"mint",
"list",
"pause",
"resume",
"rotate",
"revoke"
],
"type": "string",
"description": "mint: create a scoped service credential, the bearer token an app owner points a backend they host themselves at (app_id; optional mode/grants/members/label/ttl_seconds). list: the app's credentials, their allowlist and status, never a token (app_id). pause: reversibly stop one, in force on its very next request (app_id+credential_id). resume: undo a pause; never undoes a revoke, which is permanent (app_id+credential_id). rotate: issue a fresh token and keep the old one working for an overlap window so a running backend picks it up without a gap (app_id+credential_id; optional overlap_seconds). revoke: kill one permanently and idempotently (app_id+credential_id)."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"grants": {
"type": "array",
"items": {
"type": "object",
"required": [
"collection",
"ops"
],
"properties": {
"ops": {
"type": "array",
"items": {
"enum": [
"read",
"create",
"update",
"delete"
],
"type": "string"
}
},
"scope": {
"type": "string",
"const": "own",
"description": "Narrows every row-addressed op to rows this credential itself wrote last. Inert for create."
},
"collection": {
"type": "string",
"minLength": 1
}
}
},
"description": "mint only. The allowlist: one entry per collection naming which of read/create/update/delete this credential may attempt there (an entry may name zero ops, which under `following` is how one collection is carved out of an otherwise app-wide credential). A collection named here must be a real declared collection on the app; a typo is rejected with a 400 rather than silently doing nothing."
},
"members": {
"type": "boolean",
"description": "mint only. Opt in to the app's member directory appearing in this credential's boot/hello payloads. Defaults to false: a credential that never learns a member id cannot stamp one into a relation field."
},
"ttl_seconds": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"description": "mint only. Omit for the server's bounded default (365 days, clamped to a server maximum). null means no expiry, the explicit opt-in a long-running backend asks for; it is never the default."
},
"credential_id": {
"type": "string",
"description": "pause / resume / rotate / revoke. The credential id (see list's `id` field)."
},
"overlap_seconds": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "rotate only. How long the superseded token keeps resolving, so a running backend can pick up the new one with no gap. Defaults to the server default (1 day); 0 kills the old token immediately, the \"this leaked\" case."
}
}
}| Argument | Type | Description |
|---|---|---|
| html | string | The app's UI as a complete HTML document (single file, with CSS and JS inline), sent inline. Capped at 2 MB of UTF-8; over that the deploy is refused with 413 document_size_exceeded. A document near the cap is almost always carrying a file inlined as a data: URI; the same file in `assets[]` is served from the app's own origin, cached separately, and does not count toward this cap. The document comes from this field, `html_path`, or `document_id`. Inline is the only form a hosted or remote connector can use unless it uploads through `document_upload`; when no `document_id` is given and both `html` and `html_path` are present, inline `html` wins. On a redeploy an omitted `html` keeps the live document, so a manifest-only change (adding a collection, widening externalHosts) costs nothing in HTML. |
| slug | string | Create only. Accepted with visibility private or public, including the private default; rejected with explicit visibility 'link', where the slug is always server-generated. |
| check | boolean | Alias for `dry_run`. |
| force | boolean | Redeploy only. Bypasses the compat gate, whether it fired on a stranded-rows narrowing or on a widening of what the install screen discloses (a removed collection is detached, never deleted). |
| app_id | string | Omit to create a new app; pass an existing app's id to redeploy it (a new version, compat-gated unless force:true). |
| assets | array | Optional bundle of files shipped with the app in one deploy: images, fonts, audio/video, data. Each asset either carries its bytes inline as `content_base64` or references an already-uploaded attachment by `attachment_id`; the reference form suits real images and media, where the file is uploaded once via `attachments fetch` or presign and then bound here, with no base64 in the deploy body. Each asset is validated + stored app-scoped exactly like a normal attachment (byte-sniff, allowlist, size cap, quota, scan) and served at its `path` on the app's own origin, so the page references it by a stable same-origin path (`<img src="frames/000.jpg">`, `<video src="media/intro.mp4">`; media/font paths support HTTP Range). The whole deploy is rejected atomically if any asset fails validation. On a redeploy, sent assets replace the previous version's set, an omitted `assets` keeps the live set (no re-upload, no re-encoding), and `assets: []` is the explicit way to clear it. Bounded by the relay's per-deploy asset-count cap; total bytes by the per-app blob quota. |
| dry_run | boolean | Validate only: run the full manifest + asset-shape validation, the compat gate (for a redeploy), and the schedule-timezone advisory, then return { ok, warnings, compat?, breaks? } without creating a version or mutating anything. An invalid manifest returns the same error a real deploy would; a redeploy the compat gate would refuse reports the break instead of applying it. `check` is an accepted alias. |
| manifest | object | The x-homespun-manifest capability document (a JSON object). Required to create; on a redeploy an omitted `manifest` keeps the live one, which fits most redeploys (the manifest was byte-identical to the previous version in 71% of real redeploys). The extension keys used most often: app metadata; collections (+ per-collection write/update/read/delete role lists, where write gates creates and also updates unless the optional update list is declared); externalHosts (fetch allowlist); cdn (allow CDN scripts/styles); capabilities (Permissions-Policy opt-ins); embeds (iframe frame-src allowlist); notify (email-on-row rules); webhooks (signed HTTP POST on-row rules); agentTasks (queue work for an agent on the owner's own machine, described as a prompt). The full grammar is documented in the Homespun guide that get_skill returns. |
| html_path | string | Absolute path to the app's HTML document, read on the MCP-server host (the machine running this connector: the relay for a hosted connector, or the CLI host for a locally-run one), not on the remote agent's machine. An alternative to inline `html` that avoids retransmitting a large HTML file on every deploy. It resolves only when the file is local to the MCP server, so it serves a locally-run connector rather than a hosted or remote one, where the path does not exist and the call returns a clean error; inline `html` is the form that works there. If both `html` and `html_path` are given, inline `html` wins. |
| visibility | string | Create only. Default 'private' (owner plus invited members, sign-in gated). 'link' shares with anyone holding the returned share_url, whose #k= fragment carries a secret key that can be reset (rotate it via the apps tool, action share_link_rotate) to cut off everyone with the old link; a 'link' app always gets a server-generated unguessable slug. 'private' and 'public' accept an owner-chosen `slug`. |
| document_id | string | Reference returned by `document_upload` after you PUT the exact UTF-8 HTML bytes to its upload_url with `Authorization: Bearer <upload_token>`. Mutually exclusive with `html` and `html_path`. Use this for sandbox-authored files when the shell can reach the upload URL; the scoped upload token is not a Homespun account key. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"html": {
"type": "string",
"minLength": 1,
"description": "The app's UI as a complete HTML document (single file, with CSS and JS inline), sent inline. Capped at 2 MB of UTF-8; over that the deploy is refused with 413 document_size_exceeded. A document near the cap is almost always carrying a file inlined as a data: URI; the same file in `assets[]` is served from the app's own origin, cached separately, and does not count toward this cap. The document comes from this field, `html_path`, or `document_id`. Inline is the only form a hosted or remote connector can use unless it uploads through `document_upload`; when no `document_id` is given and both `html` and `html_path` are present, inline `html` wins. On a redeploy an omitted `html` keeps the live document, so a manifest-only change (adding a collection, widening externalHosts) costs nothing in HTML."
},
"slug": {
"type": "string",
"description": "Create only. Accepted with visibility private or public, including the private default; rejected with explicit visibility 'link', where the slug is always server-generated."
},
"check": {
"type": "boolean",
"description": "Alias for `dry_run`."
},
"force": {
"type": "boolean",
"description": "Redeploy only. Bypasses the compat gate, whether it fired on a stranded-rows narrowing or on a widening of what the install screen discloses (a removed collection is detached, never deleted)."
},
"app_id": {
"type": "string",
"description": "Omit to create a new app; pass an existing app's id to redeploy it (a new version, compat-gated unless force:true)."
},
"assets": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"path",
"content_base64"
],
"properties": {
"mime": {
"type": "string",
"description": "Advisory content-type. The relay sniffs the REAL type from the bytes and enforces the attachment allowlist; omit it (or set application/octet-stream) for data files like CSV that don't magic-byte-sniff, so they are stored + served as an inert download."
},
"path": {
"type": "string",
"description": "App-relative, same-origin reference the HTML uses, for example 'frames/000.jpg' or 'media/intro.mp4'. Must be relative: no leading '/', no '..' segment, no backslash, charset [A-Za-z0-9._/-], and not under a reserved prefix (_hs, b)."
},
"content_base64": {
"type": "string",
"description": "Standard base64 of the asset's raw bytes."
}
}
},
{
"type": "object",
"required": [
"path",
"attachment_id"
],
"properties": {
"path": {
"type": "string",
"description": "App-relative, same-origin reference the HTML uses (same rules as the inline form)."
},
"attachment_id": {
"type": "string",
"description": "Id of an ALREADY-uploaded attachment to bind at this path, instead of carrying base64. Use with `attachments fetch` (URL, zero model-context cost) or presign + finalize: the attachment must be owned by YOU, app-scoped to THIS app (upload it with scope=app, app_id=this app), and ready. Skips decode/upload; the deploy just maps path -> attachment_id."
}
}
}
]
},
"description": "Optional bundle of files shipped with the app in one deploy: images, fonts, audio/video, data. Each asset either carries its bytes inline as `content_base64` or references an already-uploaded attachment by `attachment_id`; the reference form suits real images and media, where the file is uploaded once via `attachments fetch` or presign and then bound here, with no base64 in the deploy body. Each asset is validated + stored app-scoped exactly like a normal attachment (byte-sniff, allowlist, size cap, quota, scan) and served at its `path` on the app's own origin, so the page references it by a stable same-origin path (`<img src=\"frames/000.jpg\">`, `<video src=\"media/intro.mp4\">`; media/font paths support HTTP Range). The whole deploy is rejected atomically if any asset fails validation. On a redeploy, sent assets replace the previous version's set, an omitted `assets` keeps the live set (no re-upload, no re-encoding), and `assets: []` is the explicit way to clear it. Bounded by the relay's per-deploy asset-count cap; total bytes by the per-app blob quota."
},
"dry_run": {
"type": "boolean",
"description": "Validate only: run the full manifest + asset-shape validation, the compat gate (for a redeploy), and the schedule-timezone advisory, then return { ok, warnings, compat?, breaks? } without creating a version or mutating anything. An invalid manifest returns the same error a real deploy would; a redeploy the compat gate would refuse reports the break instead of applying it. `check` is an accepted alias."
},
"manifest": {
"type": "object",
"description": "The x-homespun-manifest capability document (a JSON object). Required to create; on a redeploy an omitted `manifest` keeps the live one, which fits most redeploys (the manifest was byte-identical to the previous version in 71% of real redeploys). The extension keys used most often: app metadata; collections (+ per-collection write/update/read/delete role lists, where write gates creates and also updates unless the optional update list is declared); externalHosts (fetch allowlist); cdn (allow CDN scripts/styles); capabilities (Permissions-Policy opt-ins); embeds (iframe frame-src allowlist); notify (email-on-row rules); webhooks (signed HTTP POST on-row rules); agentTasks (queue work for an agent on the owner's own machine, described as a prompt). The full grammar is documented in the Homespun guide that get_skill returns.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"html_path": {
"type": "string",
"description": "Absolute path to the app's HTML document, read on the MCP-server host (the machine running this connector: the relay for a hosted connector, or the CLI host for a locally-run one), not on the remote agent's machine. An alternative to inline `html` that avoids retransmitting a large HTML file on every deploy. It resolves only when the file is local to the MCP server, so it serves a locally-run connector rather than a hosted or remote one, where the path does not exist and the call returns a clean error; inline `html` is the form that works there. If both `html` and `html_path` are given, inline `html` wins."
},
"visibility": {
"enum": [
"private",
"link",
"public"
],
"type": "string",
"description": "Create only. Default 'private' (owner plus invited members, sign-in gated). 'link' shares with anyone holding the returned share_url, whose #k= fragment carries a secret key that can be reset (rotate it via the apps tool, action share_link_rotate) to cut off everyone with the old link; a 'link' app always gets a server-generated unguessable slug. 'private' and 'public' accept an owner-chosen `slug`."
},
"document_id": {
"type": "string",
"description": "Reference returned by `document_upload` after you PUT the exact UTF-8 HTML bytes to its upload_url with `Authorization: Bearer <upload_token>`. Mutually exclusive with `html` and `html_path`. Use this for sandbox-authored files when the shell can reach the upload URL; the scoped upload token is not a Homespun account key."
}
}
}| limit |
| integer |
| list page size (default 50, max 100). |
| action* | string | Reports a problem with homespun itself to the relay operator. create: files one bug|feature|note with a message and an optional app_id. list: this agent's own submissions, newest first, which is what distinguishes a new failure from one already reported. |
| app_id | string | Optional app this feedback relates to (create). |
| before | string | list cursor from a prior page's next_before. |
| message | string | Message body (required for create). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"type": {
"enum": [
"bug",
"feature",
"note"
],
"type": "string",
"description": "Feedback category (required for create)."
},
"limit": {
"type": "integer",
"maximum": 100,
"description": "list page size (default 50, max 100).",
"exclusiveMinimum": 0
},
"action": {
"enum": [
"create",
"list"
],
"type": "string",
"description": "Reports a problem with homespun itself to the relay operator. create: files one bug|feature|note with a message and an optional app_id. list: this agent's own submissions, newest first, which is what distinguishes a new failure from one already reported."
},
"app_id": {
"type": "string",
"description": "Optional app this feedback relates to (create)."
},
"before": {
"type": "string",
"description": "list cursor from a prior page's next_before."
},
"message": {
"type": "string",
"description": "Message body (required for create)."
}
}
}| app_id* | string | The app id. |
| grant_id | string | revoke only. The grant link id (see list's `id` field). |
| max_uses | integer | mint only (multi mode). Cap total claims; omit for unlimited within expiry. Ignored for once (forced to 1). |
| pin_where | array | mint only. Optional narrowing pin as Wave C2 where conditions ({field, op, value}[]). Narrows within the role (never widens). Mutually exclusive with pin_row_key. |
| pin_row_key | string | mint only. Optional narrowing pin to a single row key. Narrows within the role (never widens). Mutually exclusive with pin_where. |
| ttl_seconds | integer | mint only. Grant lifetime in seconds; defaults to the server default (30 days) and is clamped to the server max. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action",
"app_id"
],
"properties": {
"mode": {
"enum": [
"once",
"multi"
],
"type": "string",
"description": "mint only. once: one-time link, claimed by the first browser that opens it (a real per-person link; later opens by others are inert). multi (default): a shared link, capped by max_uses within expiry."
},
"role": {
"type": "string",
"description": "mint only. A declared custom role for the app (an x-homespun-manifest.roles key). A built-in role (owner/member/agent/anyone) is rejected: a grant can never escalate."
},
"label": {
"type": "string",
"description": "mint only. Optional owner label shown in the grant list."
},
"action": {
"enum": [
"mint",
"list",
"revoke"
],
"type": "string",
"description": "mint: create a grant link carrying a declared custom role (app_id+role). list: the app's grant links (app_id). revoke: revoke one link (app_id+grant_id)."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"grant_id": {
"type": "string",
"description": "revoke only. The grant link id (see list's `id` field)."
},
"max_uses": {
"type": "integer",
"maximum": 9007199254740991,
"description": "mint only (multi mode). Cap total claims; omit for unlimited within expiry. Ignored for once (forced to 1).",
"exclusiveMinimum": 0
},
"pin_where": {
"type": "array",
"items": {},
"description": "mint only. Optional narrowing pin as Wave C2 where conditions ({field, op, value}[]). Narrows within the role (never widens). Mutually exclusive with pin_row_key."
},
"pin_row_key": {
"type": "string",
"description": "mint only. Optional narrowing pin to a single row key. Narrows within the role (never widens). Mutually exclusive with pin_where."
},
"ttl_seconds": {
"type": "integer",
"maximum": 9007199254740991,
"description": "mint only. Grant lifetime in seconds; defaults to the server default (30 days) and is clamped to the server max.",
"exclusiveMinimum": 0
}
}
}| app_id* | string | The app id. |
| secret | string | set_signing_secret only. A provider-generated signing secret to store verbatim (the Stripe path). Omit to have the relay mint one (the GitHub path), returned once in the response. |
| grace_seconds | number | set_signing_secret only. On a rotation, how long the previous secret stays valid so deliveries verify while you update the provider (default 3600, max 86400). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action",
"app_id"
],
"properties": {
"name": {
"type": "string",
"description": "rotate / set_signing_secret / clear_signing_secret. The manifest ingest hook name (an x-homespun-manifest.ingest[].name). See list's `name` field."
},
"action": {
"enum": [
"list",
"rotate",
"set_signing_secret",
"clear_signing_secret"
],
"type": "string",
"description": "list: the app's inbound catch-hooks, each with its full secret URL, current rule (collection/mode/wake/handshake), and per-status delivery counts (app_id). rotate: mint a fresh URL secret for one hook and return its new URL once, invalidating the old URL immediately (app_id+name). set_signing_secret: provision or rotate a hook's opt-in signing secret, distinct from the URL secret (it is what a provider HMACs the body with); omit `secret` to mint one (returned once) or pass `secret` to store a provider-generated value verbatim (never echoed) (app_id+name). clear_signing_secret: remove a hook's signing secret (app_id+name)."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"secret": {
"type": "string",
"description": "set_signing_secret only. A provider-generated signing secret to store verbatim (the Stripe path). Omit to have the relay mint one (the GitHub path), returned once in the response."
},
"grace_seconds": {
"type": "number",
"description": "set_signing_secret only. On a rotation, how long the previous secret stays valid so deliveries verify while you update the provider (default 3600, max 86400)."
}
}
}| app_id* | string | The app id. |
| human_id | string | remove and set_role. The Human id to target — see list's `humanId` field. The app owner can be neither removed nor re-roled. |
| custom_roles | array | add (optional) and set_role (required). The declared roles (x-homespun-manifest.roles keys) attached to the member alongside their base member powers. A member may hold several and holds the union of what each grants, plus everything those roles `includes`. A built-in/reserved role or an undeclared role is rejected. Omit on add for an ordinary member; pass [] on set_role to clear the roles back to a plain member. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action",
"app_id"
],
"properties": {
"role": {
"enum": [
"member"
],
"type": "string",
"description": "add only. Defaults to 'member' server-side — no other role is assignable via this API (ownership transfer is not available here)."
},
"email": {
"type": "string",
"description": "add only. The email to invite/attach. If a Human already exists for it, the member row is attached immediately; otherwise the relay emails a magic-link invite."
},
"action": {
"enum": [
"add",
"list",
"set_role",
"remove",
"roles"
],
"type": "string",
"description": "add: invite-or-attach a member by email (app_id+email; optional custom_roles). list: the app's owner + members (app_id). set_role: replace an existing member's declared roles in place without signing them out (app_id+human_id+custom_roles, an empty list to clear). remove: drop a member (app_id+human_id). roles: the app's declared roles with what each one includes and, per collection, the effective access a holder has (separately for members and grant-link holders, whose role floors differ) plus how many members and live grant links hold each role (app_id)."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"human_id": {
"type": "string",
"description": "remove and set_role. The Human id to target — see list's `humanId` field. The app owner can be neither removed nor re-roled."
},
"custom_roles": {
"type": "array",
"items": {
"type": "string"
},
"description": "add (optional) and set_role (required). The declared roles (x-homespun-manifest.roles keys) attached to the member alongside their base member powers. A member may hold several and holds the union of what each grants, plus everything those roles `includes`. A built-in/reserved role or an undeclared role is rejected. Omit on add for an ordinary member; pass [] on set_role to clear the roles back to a plain member."
}
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"bio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "update only. Short public bio (up to 500 chars); null clears it."
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "update only. Public http(s) URL (up to 200 chars); null clears it."
},
"action": {
"enum": [
"claim",
"get",
"update"
],
"type": "string",
"description": "get: returns the caller's publisher profile (handle, tenure, counters). claim: sets the caller's @-handle, once (handle arg; lowercase, 3 to 32 chars, permanent after claiming; needs a verified email). update: changes the caller's public display_name/bio/url (any of them; needs a verified email)."
},
"handle": {
"type": "string",
"description": "claim only. The lowercase @-handle to claim (^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$). Permanent once claimed."
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "update only. Public display name (up to 80 chars); null clears it."
}
}
}| handle | string | create only. Publisher handle (with `slug`), an alternative to `template`. |
| reason | string | report only. Why you are reporting this review (up to 500 chars). |
| response | any | respond only. The publisher's public response (up to 2000 chars); null clears it. |
| template | string | create only. The namespaced template id <handle>/<slug> to review. |
| review_id | string | Required for respond/report/remove/unhold. The review's id. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action"
],
"properties": {
"body": {
"type": "string",
"description": "create only. Optional written review (up to 2000 chars)."
},
"slug": {
"type": "string",
"description": "create only. Per-publisher slug (with `handle`)."
},
"stars": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"description": "create only. Star rating, an integer 1 to 5."
},
"action": {
"enum": [
"create",
"respond",
"report",
"remove",
"unhold"
],
"type": "string",
"description": "create: leaves a star rating (1..5) and optional body on a community template the caller has installed (identified by `template` \"<handle>/<slug>\" or by `handle`+`slug`); requires a verified email, and one review per install. A body containing a link or contact email is auto-held for a moderator before it shows. respond: replies to a review of one of the caller's own templates (review_id + response; null clears it). report: flags a review for the relay's moderators (review_id + reason; one report per account). remove / unhold are relay-operator-only moderation actions on a review_id: remove takes a review down (adjusting the aggregate), unhold publishes a previously auto-held review."
},
"handle": {
"type": "string",
"description": "create only. Publisher handle (with `slug`), an alternative to `template`."
},
"reason": {
"type": "string",
"description": "report only. Why you are reporting this review (up to 500 chars)."
},
"response": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "respond only. The publisher's public response (up to 2000 chars); null clears it."
},
"template": {
"type": "string",
"description": "create only. The namespaced template id <handle>/<slug> to review."
},
"review_id": {
"type": "string",
"description": "Required for respond/report/remove/unhold. The review's id."
}
}
}| The app id. |
| keep_as_member | boolean | start only. Whether the current owner stays on as an ordinary member once the transfer is accepted, losing owner powers but keeping app access. Defaults to true. Has no effect unless and until the transfer is actually accepted. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"action",
"app_id"
],
"properties": {
"email": {
"type": "string",
"description": "start only. The email to offer ownership to. The relay sends that address an accept link; ownership moves only when they open it and accept, never at start itself. 409s if a transfer is already pending for this app, or if the email already owns it."
},
"action": {
"enum": [
"start",
"status",
"cancel"
],
"type": "string",
"description": "A v2 app's ownership transfer (issue #1847). start does not move ownership: it only mints a pending offer and emails the named person an accept link, and the app stays owned here until they open it and accept (app_id+email; optional keep_as_member). status: the app's pending transfer, or null if none is pending (app_id). cancel: withdraw a pending transfer; idempotent, so cancelling with none pending is still a success (app_id)."
},
"app_id": {
"type": "string",
"minLength": 1,
"description": "The app id."
},
"keep_as_member": {
"type": "boolean",
"description": "start only. Whether the current owner stays on as an ordinary member once the transfer is accepted, losing owner powers but keeping app access. Defaults to true. Has no effect unless and until the transfer is actually accepted."
}
}
}