MCP tool reference
Every MCP tool with its exact input schema and side-effect annotations.
Every MCP tool with its exact input schema and side-effect annotations.
Launch farthershore-mcp as a stdio server. Tools inherit the saved CLI credential and its live permissions. Read the ownership and authentication guides before operating.
List every business in the authenticated FartherShore workspace (id, name, status). Read-only; use this to discover business ids for the other tools.
Operation: business.list. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Check whether a candidate slug is free to use as a business subdomain (normalized, blocked-word and collision checked). Read-only; run before fs_business_create.
Operation: business.subdomain_availability.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "Candidate business slug (normalized to the subdomain)."
}
},
"required": [
"slug"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Verify lifecycle, release, and the complete environment edge generation by id or slug. Reports Core G, published G, observed G, the expected/observed manifest digests, and whether they cohere. Read-only.
Operation: business.status. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to check."
},
"env": {
"description": "Environment name; omit for production.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Enable Managed RBAC for a business — a platform-owned flag (like docsEnabled) toggled via PUT /businesses/:id/rbac. Subscriber orgs can then manage roles in their portal. Idempotent if RBAC is already enabled.
Operation: rbac.enable. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to enable Managed RBAC on."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Disable Managed RBAC for a business — flips the platform-owned flag back off via PUT /businesses/:id/rbac. Subscriber role/assignment state is kept server-side; re-enabling is a pure flag flip. Idempotent if RBAC is already disabled.
Operation: rbac.disable. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to disable Managed RBAC on."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
List a business's raw permission vocabulary (subject, verbs, escalatory verbs, description). The SDK/compiler do not create roles: each subscribing organization assembles this catalog into its own CUSTOM roles, default, and assignments. Subjects are declared via permission-carrying fs.group(id, routes, { permission }) in the business/ repo; run farthershore validate and push to change them. Read-only.
Operation: rbac.subjects.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to list subjects for."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Update a business's brand and presentation — display name, description, icon, logo (wordmark), key prefix, and organization-page visibility. Plans, pricing, routes, and backend origins are managed through their dedicated surfaces. Only the fields you pass are changed.
Operation: brand.update. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to update."
},
"displayName": {
"description": "Display name.",
"type": "string"
},
"description": {
"description": "Short business description.",
"type": "string"
},
"iconUrl": {
"description": "Square icon/favicon URL, or null to clear it.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logoUrl": {
"description": "Wordmark/logo URL, or null to clear it.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"keyPrefix": {
"description": "White-label prefix for subscriber API keys (fsk_ → e.g. acme_). 2-12 lowercase letters/digits; fs/fsk/fsc/fsm reserved. Null clears to the default fsk.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"listedOnOrganizationPage": {
"description": "Show (true) or hide (false) this product on the organization's public page at /organization/<slug>. Listed by default.",
"type": "boolean"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
Publish a business — validate its current spec and queue a versioned release with an auto-computed semver. Use business status to prove it is live.
Operation: business.publish. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id to publish."
},
"bump": {
"description": "Force the semver bump. Omit to auto-derive from the change.",
"type": "string",
"enum": [
"major",
"minor",
"patch"
]
},
"version": {
"description": "Pin the exact next release tag (vX.Y.Z).",
"type": "string"
},
"acceptBreaking": {
"description": "Consent to publish a breaking (blocking-risk) change as major.",
"type": "boolean"
},
"dryRun": {
"description": "Preview the change (computed semver + reasons) without cutting a release.",
"type": "boolean"
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Configure automatic preview environment creation for a business. Modes: BRANCH_PREFIX creates previews from matching env branches, PULL_REQUEST creates previews for PRs against the default branch, and DISABLED stops automatic creation while explicit farthershore env create continues to work. Pass envBranchPrefix to customize the branch-prefix mode, or null to reset to env/.
Operation: business.preview_env.set. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to update."
},
"previewEnvTrigger": {
"description": "Automatic preview mode: BRANCH_PREFIX, PULL_REQUEST, or DISABLED.",
"type": "string",
"enum": [
"BRANCH_PREFIX",
"PULL_REQUEST",
"DISABLED"
]
},
"envBranchPrefix": {
"description": "Branch prefix for BRANCH_PREFIX mode, or null for env/.",
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 50
},
{
"type": "null"
}
]
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
Enable docs for a business — opens the publish/sync gate so docs are served from R2 and boot.docsEnabled=true is emitted to the portal. Idempotent if docs are already enabled.
Operation: business.docs.enable. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to enable docs on."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Disable docs for a business — closes the publish/sync gate so docs are no longer served and boot.docsEnabled=false is emitted to the portal. The docs scaffold stays in the repo; re-enabling is a pure flag flip. Idempotent if docs are already disabled.
Operation: business.docs.disable. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug to disable docs on."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Propose a governed ChangeSet against a subscriber's live RBAC state (Agent Proposal Flow). Creates a DRAFT proposal that a HUMAN in the subscriber org must preview, approve, and apply in the portal — an agent can propose but never self-approve or apply. Operate-class live-state action; does not edit repo-authored business behavior.
Operation: change_set.propose. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber (client org) id — from `consumer list`."
},
"intent": {
"type": "string",
"description": "Human-readable description of the proposed change."
},
"operations": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Governed operations, e.g. [{ type: 'update_role_permissions', schemaVersion: 1, target: { resourceType: 'subscriber_business_role', resourceId: '<roleKey>' }, payload: { permissions: [...] } }]."
},
"env": {
"description": "Environment name/id to scope the proposal to.",
"type": "string"
},
"idempotencyKey": {
"description": "Replay-safe idempotency key for the proposal.",
"type": "string"
}
},
"required": [
"businessId",
"subscriberId",
"intent",
"operations"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}
}
Simulate the impact of a proposed ChangeSet and store the preview (Agent Proposal Flow). Enforced by the same authority as propose — there is no separate preview permission. Read-shaped but writes the stored simulation; does not apply the change.
Operation: change_set.preview. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber (client org) id — from `consumer list`."
},
"changeSetId": {
"type": "string",
"description": "The governed ChangeSet id."
},
"env": {
"description": "Environment name/id.",
"type": "string"
}
},
"required": [
"businessId",
"subscriberId",
"changeSetId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}
}
List governed ChangeSets proposed against a subscriber (Agent Proposal Flow). Read-only; use it to discover proposal ids + their status before previewing.
Operation: change_set.proposal_list. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber (client org) id — from `consumer list`."
},
"status": {
"description": "Filter by status (e.g. draft, approval_required).",
"type": "string"
},
"env": {
"description": "Environment name/id.",
"type": "string"
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true
}
}
Read one governed ChangeSet proposed against a subscriber (Agent Proposal Flow) — its operations, risk, simulation, approvals, and status. Read-only.
Operation: change_set.proposal_read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber (client org) id — from `consumer list`."
},
"changeSetId": {
"type": "string",
"description": "The governed ChangeSet id."
},
"env": {
"description": "Environment name/id.",
"type": "string"
}
},
"required": [
"businessId",
"subscriberId",
"changeSetId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true
}
}
List a business's pricing plans (read-only). Plans are managed as code in the business's GitHub repo — to add/change/remove a plan, edit business/ and push; this tool only reads the current state. Without environmentId the PRODUCTION plans are returned; pass environmentId to see what a preview environment serves. Pass the business id from fs_business_list.
Operation: plan.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id whose plans to list."
},
"environmentId": {
"description": "Return the plans this environment serves; omit for production.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
List a business's environments (name, branch, hostnames). The first row is always the production scope, which has id: null and no branch — it is the live business, not a preview environment row, and --env production addresses it on every verb that takes --env. Read-only.
Operation: environment.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id whose environments to list."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Create a preview environment bound to a git branch. Provide a name and the git branch it tracks.
Operation: environment.create. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id to create the environment in."
},
"name": {
"type": "string",
"description": "Environment name (e.g. 'staging', 'preview-pr-42')."
},
"branch": {
"type": "string",
"description": "The git branch this environment tracks."
}
},
"required": [
"businessId",
"name",
"branch"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
List a business's backends (origins) — id, scope (production|environment), environmentId, name, slug, transport (direct|tunnel), default flag, and derived status. Backends are per-(business, environment) rows, so the same declared backend can legitimately appear once per scope and be default in each. Read-only.
Operation: backend.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id whose backends to list."
},
"environmentId": {
"description": "Only backends in this environment id, or 'production' for the production scope. Omit for every scope.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Create a backend (origin) for a business. Pick a transport mode: direct (public HTTPS URL, secured by Ed25519 request signing) or tunnel (private outbound-only cloudflared, secure bring-your-own-backend). Mark it default to route traffic to it.
Operation: backend.create. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id to create the backend in."
},
"name": {
"type": "string",
"description": "Backend name (e.g. 'prod-origin')."
},
"slug": {
"description": "URL-safe slug; derived from name if omitted.",
"type": "string"
},
"transportMode": {
"description": "How the gateway reaches the origin; defaults to direct.",
"type": "string",
"enum": [
"direct",
"tunnel"
]
},
"originUrl": {
"description": "The origin URL (for direct mode).",
"type": "string"
},
"isDefault": {
"description": "Route traffic to this backend by default.",
"type": "boolean"
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId",
"name"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
Bind a logical backend id to a concrete direct upstream URL in one environment. Previews inherit the production backend until a concrete override is bound. Omit environmentId for production.
Operation: backend.bind. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"backend": {
"type": "string",
"description": "Logical backend slug."
},
"environmentId": {
"description": "Preview environment id; omit for production.",
"type": "string"
},
"originUrl": {
"type": "string",
"format": "uri",
"description": "Concrete direct upstream URL."
}
},
"required": [
"businessId",
"backend",
"originUrl"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Delete a backend (origin). Traffic routed to it stops; re-create to restore.
Operation: backend.delete. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"backendId": {
"type": "string",
"description": "The backend id to delete."
}
},
"required": [
"businessId",
"backendId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}
List a business's runtime tokens (fsrt_) — id, last-four, operations, status, and env scope. Read-only; secrets are never shown.
Operation: runtime_token.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"environmentId": {
"description": "Only tokens scoped to this environment id, or 'production' for the production scope. Omit for every scope.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Mint a new runtime token (fsrt_) for a backend. Returns the plaintext token ONCE — store it now (e.g. as FS_RUNTIME_TOKEN). Operations default to the backend's needs (gateway_verification, metering, health).
Operation: runtime_token.mint. Side effect: write. One-time secret: true.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"backendId": {
"description": "Bind the token to this backend, by slug or id. Resolved in the selected environment, falling back to the production row.",
"type": "string"
},
"environmentId": {
"description": "Scope to a preview environment (omit for production).",
"type": "string"
},
"kind": {
"description": "Token kind; defaults from the env scope.",
"type": "string",
"enum": [
"live",
"test"
]
},
"operations": {
"description": "Operations (gateway_verification, metering, health, tunnel).",
"type": "array",
"items": {
"type": "string"
}
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
Rotate a runtime token: mint a fresh secret carrying the same scope and revoke the old one. Returns the new plaintext token ONCE.
Operation: runtime_token.rotate. Side effect: write. One-time secret: true.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"tokenId": {
"type": "string",
"description": "The runtime token id to rotate."
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId",
"tokenId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
Revoke a runtime token. The backend using it stops verifying.
Operation: runtime_token.revoke. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"tokenId": {
"type": "string",
"description": "The runtime token id to revoke."
}
},
"required": [
"businessId",
"tokenId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}
Read a business's current frontend serve state (uiMode, active release hash + producing build, pin flag), the recent SUCCEEDED releases (rollback targets), and the recent builds — a FAILED build's error explains why a deploy didn't go live. Read-only.
Operation: frontend.status. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"environmentId": {
"description": "Scope to a preview environment (omit for production).",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Roll a business's frontend back to a prior release by its releaseId (manifest hash, from fs_frontend_status). Flips the live pointer back and pins it. The releaseId must belong to this target's build history.
Operation: frontend.rollback. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"releaseId": {
"type": "string",
"description": "The prior release id (manifest hash) to re-activate."
},
"environmentId": {
"description": "Scope to a preview environment (omit for production).",
"type": "string"
}
},
"required": [
"businessId",
"releaseId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
List API-managed outbound webhook endpoints for a business. Read-only; signing secrets are never returned.
Operation: webhook.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"limit": {
"description": "Max rows to return.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Create an outbound webhook endpoint for a business. Returns the signing secret once.
Operation: webhook.create. Side effect: write. One-time secret: true.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"url": {
"type": "string",
"format": "uri",
"description": "HTTPS receiver URL."
},
"events": {
"minItems": 1,
"type": "array",
"items": {
"type": "string"
},
"description": "Webhook event names to subscribe to."
},
"environmentId": {
"description": "Only deliver events from this environment (default: every environment).",
"type": "string"
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId",
"url",
"events"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}
}
Update an API-managed webhook endpoint's URL, event list, environment scope and/or enabled state. Use fs_webhook_rotate_secret for a new signing secret.
Operation: webhook.update. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"webhookId": {
"type": "string",
"description": "The webhook endpoint id."
},
"url": {
"description": "Replacement HTTPS receiver URL.",
"type": "string",
"format": "uri"
},
"events": {
"description": "Replacement webhook event list.",
"minItems": 1,
"type": "array",
"items": {
"type": "string"
}
},
"environmentId": {
"description": "Only deliver events from this environment; null clears the scope (every environment).",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"description": "Enable or disable delivery.",
"type": "boolean"
}
},
"required": [
"businessId",
"webhookId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Delete an outbound webhook endpoint.
Operation: webhook.delete. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"webhookId": {
"type": "string",
"description": "The webhook endpoint id."
}
},
"required": [
"businessId",
"webhookId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
Send a signed test event to an API-managed webhook endpoint and persist the delivery result.
Operation: webhook.test. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"webhookId": {
"type": "string",
"description": "The webhook endpoint id."
},
"type": {
"description": "Envelope type to send: one of subscription.created, subscription.updated, subscription.canceled, payment.succeeded, payment.failed, entitlement.changed, usage.threshold_reached, webhook.test. A catalog event is delivered with a realistic sample payload. Defaults to webhook.test.",
"type": "string"
}
},
"required": [
"businessId",
"webhookId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": true
}
}
Issue a replacement signing secret for a webhook endpoint. Returns the new secret once; deliveries carry both signatures for 24 hours so the receiver can roll over without a gap.
Operation: webhook.rotate_secret. Side effect: write. One-time secret: true.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"webhookId": {
"type": "string",
"description": "The webhook endpoint id."
}
},
"required": [
"businessId",
"webhookId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
List the event names a webhook endpoint can subscribe to, with descriptions.
Operation: webhook.event_type.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
List recent delivery attempts for a webhook endpoint. Payload and response body are intentionally omitted by Core.
Operation: webhook.delivery.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"webhookId": {
"type": "string",
"description": "The webhook endpoint id."
},
"limit": {
"description": "Max rows to return.",
"type": "string"
}
},
"required": [
"businessId",
"webhookId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
The agent roster for a business: the enabled/disabled Operator plus any roles that can still be enabled. Read-only.
Operation: agents.list. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
The Operator's activation state, recent run history (newest-first), and lifetime usage totals (LLM tokens + actions). Read-only.
Operation: agents.status. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
One run's full audit view: the orchestrator's trace summary (composed launches, verify flags, catalog changes), the per-launch performance ledger, and every platform-action receipt. Read-only.
Operation: agents.runs.show. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"runId": {
"type": "string",
"description": "The agent run id."
}
},
"required": [
"businessId",
"runId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Turn the business's Operator agent on (created on first enable). It runs autonomously on its cadence; agent-work billing accrues while enabled.
Operation: agents.enable. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Turn the Operator off: the dispatcher stops scheduling runs and agent-work billing stops accruing. Re-enable at any time.
Operation: agents.disable. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
The agents' bulletin feed for a business: trend/insight posts (aggregated data + deltas) and change_request posts (the coding agent's backlog — filter --kind change_request --status open). Read-only.
Operation: bulletin.list. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"kind": {
"description": "Filter by post kind.",
"type": "string",
"enum": [
"trend",
"insight",
"change_request"
]
},
"status": {
"description": "Filter by post status.",
"type": "string",
"enum": [
"open",
"acknowledged",
"resolved"
]
},
"limit": {
"description": "Max rows to return.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
One bulletin post in full: markdown body, the dataJson payload backing the claim, and for change requests the referenced ChangeSet id + proposal. Read-only.
Operation: bulletin.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"postId": {
"type": "string",
"description": "The bulletin post id."
}
},
"required": [
"businessId",
"postId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Mark a bulletin post acknowledged — the hand-off signal that the coding agent (or builder) has picked the item up. Forward-only; idempotent on an already-acknowledged post.
Operation: bulletin.ack. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"postId": {
"type": "string",
"description": "The bulletin post id."
}
},
"required": [
"businessId",
"postId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Mark a bulletin post resolved — the referenced work landed (or the trend was addressed). Terminal state.
Operation: bulletin.resolve. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"postId": {
"type": "string",
"description": "The bulletin post id."
}
},
"required": [
"businessId",
"postId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
List API-managed promo codes for a business. Promo codes are checkout operational state, not repo-authored Business SDK state.
Operation: promo_code.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Create an API-managed checkout promo code. Use percent for percent_off, amountCents for amount_off, and no amount for free_months.
Operation: promo_code.create. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"kind": {
"type": "string",
"enum": [
"percent_off",
"amount_off",
"free_months"
]
},
"percent": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"amountCents": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"durationMonths": {
"type": "integer",
"minimum": 1,
"maximum": 24
},
"maxRedemptions": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"activeFrom": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"activeUntil": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"applicablePlanIds": {
"type": "array",
"items": {
"type": "string"
}
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Required live-attempt key. Reuse this exact value only when retrying the same uncertain promo-code creation."
}
},
"required": [
"businessId",
"code",
"kind",
"durationMonths",
"idempotencyKey"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"openWorldHint": true
}
}
Update an API-managed checkout promo code. Spec changes rotate the Stripe coupon/promotion code behind the scenes.
Operation: promo_code.update. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"promoCodeId": {
"type": "string",
"description": "The promo code id."
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"kind": {
"type": "string",
"enum": [
"percent_off",
"amount_off",
"free_months"
]
},
"percent": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"amountCents": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"durationMonths": {
"type": "integer",
"minimum": 1,
"maximum": 24
},
"maxRedemptions": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"activeFrom": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
{
"type": "null"
}
]
},
"activeUntil": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
{
"type": "null"
}
]
},
"applicablePlanIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"businessId",
"promoCodeId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"openWorldHint": true
}
}
Archive an API-managed checkout promo code.
Operation: promo_code.archive. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"promoCodeId": {
"type": "string",
"description": "The promo code id."
}
},
"required": [
"businessId",
"promoCodeId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
Reactivate an archived API-managed checkout promo code.
Operation: promo_code.reactivate. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"promoCodeId": {
"type": "string",
"description": "The promo code id."
}
},
"required": [
"businessId",
"promoCodeId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"openWorldHint": false
}
}
List users/consumers for a business. Read-only; use this to discover subscriber ids before blocking or removing a user.
Operation: consumer.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"env": {
"description": "Environment name for preview-scoped consumers.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Block a user/consumer for a business and revoke their active API keys. Destructive live-state operation; it does not edit repo-authored business behavior.
Operation: consumer.block. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": true
}
}
List one consumer's API keys for a business. Read-only and metadata only — the response never contains key material. Use it to discover the keyId needed to revoke a single key.
Operation: consumer.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Revoke ONE of a consumer's API keys for a business. The surgical alternative to blocking the whole consumer (which revokes every key). Irreversible: the credential stops working at the edge and cannot be un-revoked — mint a new key instead. Destructive live-state operation; it does not edit repo-authored business behavior.
Operation: consumer.block. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
},
"keyId": {
"type": "string",
"description": "The API key id from `consumer keys list`."
}
},
"required": [
"businessId",
"subscriberId",
"keyId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": true
}
}
Move one consumer onto the current head of their plan lineage immediately. Operates on live subscription state.
Operation: consumer.migrate_latest. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}
}
Remove a user/consumer from live business access: cancel subscriptions, revoke credentials, purge related live state, and archive the subscriber while retaining billing/audit history. Destructive and convergent on retry; it does not edit repo-authored business behavior.
Operation: consumer.remove. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": true
}
}
Support override: replace a client-org member's Managed-RBAC business-role assignment on a business (set-replace — the given list becomes the member's full assignment; an empty list clears it). Role keys must exist in the org's role set. Live-state operation; it does not edit repo-authored business behavior.
Operation: consumer.roles.assign. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
},
"userExternalId": {
"type": "string",
"description": "The member's external identity id (Clerk userId) within the client org."
},
"roles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Business-role keys to set (replaces the current assignment; [] clears it)."
}
},
"required": [
"businessId",
"subscriberId",
"userExternalId",
"roles"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}
}
Turn Managed-RBAC enforcement ON for ONE subscriber, and optionally set the org's default role. Enforcement requires BOTH this flag and the product flag (fs_business_rbac_enable); with the product flag off this returns 400 RBAC_NOT_ENABLED_BY_PRODUCT. Returns 409 GOVERNED_BY_CHANGE_SET when the subscriber org has mandatory change control on — that org must approve a governed ChangeSet instead. Live-state operation; it does not edit repo-authored business behavior.
Operation: consumer.roles.assign. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
},
"defaultRoleKey": {
"description": "Role key new members fall back to when they have no explicit role. Omit to clear it.",
"type": "string"
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}
}
Turn Managed-RBAC enforcement OFF for ONE subscriber. This is an access EXPANSION — with enforcement off, credential permission resolution can return ['*']. Role definitions are preserved for re-enable. Returns 409 GOVERNED_BY_CHANGE_SET when the subscriber org has mandatory change control on. Live-state operation; it does not edit repo-authored business behavior.
Operation: consumer.roles.assign. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": true
}
}
List ONE subscriber's Managed-RBAC role rows (ACCOUNT and CUSTOM), with each role's permission keys. Read-only; use it to discover role keys before creating, updating, deleting, or assigning them. Returns 400 RBAC_NOT_ENABLED_BY_PRODUCT when the product's RBAC flag is off.
Operation: consumer.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
}
},
"required": [
"businessId",
"subscriberId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Create a CUSTOM Managed-RBAC role for ONE subscriber from the business's derived permission catalog. An unknown permission is rejected with 400 UNKNOWN_PERMISSION; the reserved key owner is rejected with 409 OWNER_ROLE_IMMUTABLE (owners always hold every permission); a duplicate key is a 409. Live-state operation; it does not edit repo-authored business behavior.
Operation: consumer.roles.assign. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
},
"roleKey": {
"type": "string",
"description": "The subscriber-owned role key (lowercase slug). `owner` is reserved and immutable."
},
"name": {
"type": "string",
"description": "Human-readable role name."
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Permission keys from the business's derived catalog. Grant-by-exact-name; a custom subject's `<subject>:*` is never grantable."
}
},
"required": [
"businessId",
"subscriberId",
"roleKey",
"name",
"permissions"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": true
}
}
Rename and/or re-permission ONE subscriber Managed-RBAC role. permissions is set-replace — the given list becomes the role's full grant. Provide name and/or permissions. An unknown permission is rejected with 400 UNKNOWN_PERMISSION; the reserved key owner is rejected with 409 OWNER_ROLE_IMMUTABLE. Role edits republish live-bound key claims asynchronously, so retest EXISTING credentials after the change reaches the edge.
Operation: consumer.roles.assign. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
},
"roleKey": {
"type": "string",
"description": "The subscriber-owned role key (lowercase slug). `owner` is reserved and immutable."
},
"name": {
"description": "New human-readable role name.",
"type": "string"
},
"permissions": {
"description": "Replacement permission keys (set-replace, from the derived catalog).",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"businessId",
"subscriberId",
"roleKey"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}
}
Delete ONE subscriber Managed-RBAC role. Atomic and convergent: the key is stripped from every member and credential that holds it and cleared as the org default. The reserved key owner is rejected with 409 OWNER_ROLE_IMMUTABLE. Destructive live-state operation; it does not edit repo-authored business behavior.
Operation: consumer.roles.assign. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subscriberId": {
"type": "string",
"description": "The subscriber id from `consumer list`."
},
"roleKey": {
"type": "string",
"description": "The subscriber-owned role key (lowercase slug). `owner` is reserved and immutable."
}
},
"required": [
"businessId",
"subscriberId",
"roleKey"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": true
}
}
Lists variables. Returns readable FS_PUBLIC_* values; every other variable is a write-only secret and only its lifecycle metadata is returned.
Operation: business_variable.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"environmentId": {
"description": "Preview environment slug or id (omit for Main).",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Creates an immutable variable generation. An FS_PUBLIC_-prefixed name is public (inlined into the frontend bundle); any other name is a write-only secret whose plaintext is accepted once and never returned.
Operation: business_variable.create. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"name": {
"type": "string",
"description": "Variable name, e.g. POSTHOG_TOKEN. The name is the class: an FS_PUBLIC_ prefix makes it public (inlined into the frontend bundle, readable by every visitor); any other name is a write-only secret."
},
"value": {
"type": "string",
"minLength": 1,
"description": "The value."
},
"environmentId": {
"description": "Preview environment slug or id (omit for Main).",
"type": "string"
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId",
"name",
"value"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Creates an immutable variable generation. An FS_PUBLIC_-prefixed name is public (inlined into the frontend bundle); any other name is a write-only secret whose plaintext is accepted once and never returned.
Operation: business_variable.rotate. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"name": {
"type": "string",
"description": "Variable name, e.g. POSTHOG_TOKEN. The name is the class: an FS_PUBLIC_ prefix makes it public (inlined into the frontend bundle, readable by every visitor); any other name is a write-only secret."
},
"value": {
"type": "string",
"minLength": 1,
"description": "The value."
},
"environmentId": {
"description": "Preview environment slug or id (omit for Main).",
"type": "string"
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId",
"name",
"value"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Revokes runtime access after explicit confirmation and returns a durable operation.
Operation: business_variable.revoke. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string"
},
"name": {
"type": "string"
},
"environmentId": {
"type": "string"
},
"confirmation": {
"type": "string",
"const": "REVOKE"
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId",
"name",
"confirmation"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}
Permanently destroys ciphertext after acknowledged revocation. Main and preview use the same contract.
Operation: business_variable.delete. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string"
},
"name": {
"type": "string"
},
"environmentId": {
"type": "string"
},
"confirmation": {
"type": "string",
"const": "DELETE"
},
"idempotencyKey": {
"description": "One caller-persisted key for this exact live intent. Reuse it only when retrying the same request; a replay is historical and must be followed by the operation's reconcile read when current state matters.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"businessId",
"name",
"confirmation"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}
Reads publication status and frozen impact metadata.
Operation: business_variable.operation.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string"
},
"operationId": {
"type": "string"
}
},
"required": [
"businessId",
"operationId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
List a business's economic agreements (subject-scoped usage-pricing bindings and their append-only contract pricing versions).
Operation: agreement.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"subjectId": {
"description": "Filter by subject id.",
"type": "string"
},
"environmentId": {
"description": "Preview environment slug or id (omit for production).",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Fetch one economic agreement with every contract pricing version.
Operation: agreement.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"agreementId": {
"type": "string",
"description": "The agreement id."
}
},
"required": [
"businessId",
"agreementId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
Read a business's usage summary — metered request counts and tier utilization. Without environmentId this rolls up EVERY environment. Read-only.
Operation: usage.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id whose usage to read."
},
"environmentId": {
"description": "Narrow the summary to this environment; omit for the product-wide rollup.",
"type": "string"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Issue a one-time test bootstrap key for a business environment — use it to provision a test persona. Returns the key ONCE; store it now.
Operation: persona.bootstrap. Side effect: write. One-time secret: true.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"environmentId": {
"type": "string",
"description": "The environment id to scope the persona to."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Required live-attempt key. Reuse this exact value only when retrying the same uncertain persona bootstrap."
},
"subscriberId": {
"type": "string",
"minLength": 1
},
"planKey": {
"description": "Plan key to assign. Required when creating a new subscriber; omit only when subscriberId joins an existing subscriber.",
"type": "string",
"minLength": 1
},
"accountRole": {
"type": "string",
"enum": [
"owner",
"admin",
"member"
]
},
"roleKeys": {
"description": "Subscriber-owned product role keys. Omit to use its configured default role.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"businessId",
"environmentId",
"idempotencyKey"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
List a business environment's test personas (id, label, status). Read-only.
Operation: persona.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"environmentId": {
"type": "string",
"description": "The environment id whose personas to list."
}
},
"required": [
"businessId",
"environmentId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Rotate a test persona's API key. Returns the replacement key once.
Operation: persona.rotate. Side effect: write. One-time secret: true.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"environmentId": {
"type": "string",
"description": "The environment id."
},
"personaId": {
"type": "string",
"description": "The persona id to rotate."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Required live-attempt key. Reuse this exact value only when retrying the same uncertain persona rotation."
}
},
"required": [
"businessId",
"environmentId",
"personaId",
"idempotencyKey"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": false
}
}
Delete a temporary test persona, including its credential, browser access, and test-owned identity state.
Operation: persona.delete. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id."
},
"environmentId": {
"type": "string",
"description": "The environment id."
},
"personaId": {
"type": "string",
"description": "The persona id to delete."
}
},
"required": [
"businessId",
"environmentId",
"personaId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}
Event volume bucketed over time for one business, from the event archive. Read-only. Scoped to production unless environmentId is given.
Operation: analytics.timeseries. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"pattern": "^[^/?#\\s]+$",
"description": "The business whose archive to query."
},
"range": {
"default": "24h",
"description": "Relative window.",
"type": "string",
"enum": [
"1h",
"24h",
"7d",
"30d"
]
},
"environmentId": {
"description": "Environment id to scope to. Omit for production. Never returns all environments summed.",
"type": "string"
},
"domain": {
"default": "usage",
"type": "string",
"enum": [
"usage",
"telemetry",
"denials",
"lifecycle",
"consumer_activity",
"audit"
]
},
"interval": {
"default": "hour",
"type": "string",
"enum": [
"hour",
"day"
]
}
},
"required": [
"businessId",
"range",
"domain",
"interval"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Gateway request latency at p50/p95/p99 for one business. NOTE: this is the WHOLE request including the builder's own backend, so a high number is not necessarily platform overhead. Read-only.
Operation: analytics.latency. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"pattern": "^[^/?#\\s]+$",
"description": "The business whose archive to query."
},
"range": {
"default": "24h",
"description": "Relative window.",
"type": "string",
"enum": [
"1h",
"24h",
"7d",
"30d"
]
},
"environmentId": {
"description": "Environment id to scope to. Omit for production. Never returns all environments summed.",
"type": "string"
}
},
"required": [
"businessId",
"range"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Ranked breakdown of archive events by caller, event type, or environment. Read-only.
Operation: analytics.top. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"pattern": "^[^/?#\\s]+$",
"description": "The business whose archive to query."
},
"range": {
"default": "24h",
"description": "Relative window.",
"type": "string",
"enum": [
"1h",
"24h",
"7d",
"30d"
]
},
"environmentId": {
"description": "Environment id to scope to. Omit for production. Never returns all environments summed.",
"type": "string"
},
"by": {
"default": "actor_id",
"type": "string",
"enum": [
"actor_id",
"type",
"environment_id"
]
},
"domain": {
"default": "usage",
"type": "string",
"enum": [
"usage",
"telemetry",
"denials",
"lifecycle",
"consumer_activity",
"audit"
]
},
"k": {
"default": 10,
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"required": [
"businessId",
"range",
"by",
"domain",
"k"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
The most recent archived events for one business, newest first. Each row's payload carries the request detail (path, statusCode, latencyMs, orgId). Read-only.
Operation: analytics.log. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"pattern": "^[^/?#\\s]+$",
"description": "The business whose archive to query."
},
"range": {
"default": "24h",
"description": "Relative window.",
"type": "string",
"enum": [
"1h",
"24h",
"7d",
"30d"
]
},
"environmentId": {
"description": "Environment id to scope to. Omit for production. Never returns all environments summed.",
"type": "string"
},
"domain": {
"default": "usage",
"type": "string",
"enum": [
"usage",
"telemetry",
"denials",
"lifecycle",
"consumer_activity",
"audit"
]
},
"limit": {
"default": 25,
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"businessId",
"range",
"domain",
"limit"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Transfer primary ownership of a team or company organization to another existing member. Destructive and irreversible for the caller; requires the signed-in owner's session.
Operation: organization.ownership.transfer. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"organizationId": {
"type": "string",
"description": "Builder organization id."
},
"newOwnerUserId": {
"type": "string",
"description": "User id of the existing member who becomes primary owner."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Required live-attempt key. Reuse this exact value only when retrying the same uncertain ownership transfer."
}
},
"required": [
"organizationId",
"newOwnerUserId",
"idempotencyKey"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}
Read the Stripe Connect account a business bills through — a per-business override when present, otherwise the organization default — including onboarding and tax-enrollment state. Read-only. Connecting Stripe is browser-only and has no tool.
Operation: stripe_connection.read. Side effect: read. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
Remove a business's per-business Stripe Connect override so it bills through the organization default again. Refused while any subscription is still money-bearing. Destructive live-state operation; it does not edit repo-authored business behavior.
Operation: stripe_connection.delete. Side effect: write. One-time secret: false.
{
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"businessId": {
"type": "string",
"description": "The business id or slug."
},
"deleteAccount": {
"description": "Also delete the platform-created Express account at Stripe.",
"type": "boolean"
}
},
"required": [
"businessId"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}