{ "openapi": "3.1.0", "jsonSchemaDialect": "http://json-schema.org/draft-07/schema#", "info": { "title": "Goosy Bear API", "version": "1.0.0-beta", "summary": "Manage workspace content, projects, Data tables, Pages, library and credits.", "description": "BETA. This API is in beta: paths, request shapes and response envelopes may change, and every response carries an `x-goosy-api: beta` header for as long as that is true. A change is additive, or it is deprecated first: a response to a call that uses a deprecated feature carries `Deprecation` and `Sunset` headers, and nothing is removed until at least 90 days after its deprecation. Pin the OpenAPI document you generated against and re-generate when it changes." }, "servers": [ { "url": "https://app.goosybear.ai", "description": "Production" } ], "security": [ { "tenantApiKey": [] } ], "components": { "securitySchemes": { "tenantApiKey": { "type": "http", "scheme": "bearer", "description": "An API key minted at Settings › API & MCP. Send it as `Authorization: Bearer `. A key carries its holder's own permissions, resolved on every call — revoking a membership closes the key's reach immediately. Keep it in an environment variable (`GOOSY_API_KEY`), never in a committed file." } }, "schemas": { "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "code": { "type": "string", "description": "The typed refusal code — e.g. `tenant_mcp.surface_disabled`, `tenant_mcp.rate_limited`." }, "message": { "type": "string", "description": "A sentence a person can act on." }, "retry_after_seconds": { "description": "On a 429: whole seconds to wait. Mirrors `Retry-After`.", "type": "number" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry_after_seconds": { "type": "number" } }, "required": [ "code", "message" ], "description": "Deprecated: the same values as the top-level fields, kept until 2026-12-31. Read `code` and `message` at the top level.", "additionalProperties": false } }, "required": [ "ok", "code", "message", "error" ], "description": "A request the boundary refused before dispatching anything. The same shape the MCP endpoint answers its own refusals with, and the same top-level fields a dispatched call's refusal carries, so one client branch covers both.", "additionalProperties": false }, "ToolRefusal": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "code": { "type": "string", "description": "The typed reason — e.g. `workspace_ambiguous`, `invalid_arguments`, or the tool's own failure code." }, "message": { "type": "string", "description": "A sentence a person can act on." }, "workspaces": { "description": "On a workspace refusal: the slugs this key may pass as `workspace`.", "type": "array", "items": { "type": "string" } }, "issues": { "description": "On `invalid_arguments`: which fields failed, and why.", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "path": { "description": "On an authoring refusal: where in your call's input it points, e.g. `steps..params.`.", "type": "string" }, "fix": { "description": "On an authoring refusal: the change to your call that would pass.", "type": "string" }, "instruction": { "description": "On an authoring refusal: what to do next with it.", "type": "string" } }, "required": [ "ok", "code", "message" ], "description": "A call that was admitted and dispatched, and did not succeed.", "additionalProperties": false }, "PagePreviewLinkError": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry_after_seconds": { "type": "integer", "minimum": 1 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "ok", "error" ], "description": "A Pages preview-link request that did not succeed.", "additionalProperties": false }, "PageAssetError": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry_after_seconds": { "type": "integer", "minimum": 1 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "ok", "error" ], "description": "A Pages asset upload that did not succeed.", "additionalProperties": false }, "PageIngestError": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "ok", "error" ], "description": "A Pages import that did not succeed. ⚠️ Unlike a tool refusal, this envelope has NO `workspaces` array — on `workspace_ambiguous` and `workspace_unreachable` the slugs you may pass are appended to `error.message` instead.", "additionalProperties": false }, "PagesDeployManifest": { "type": "object", "properties": { "entry": { "description": "The Worker module that answers `routes`, relative to the bundle root. Omit it for a static site.", "type": "string", "minLength": 1, "maxLength": 512 }, "assets": { "description": "The directory holding the site's static files, relative to the bundle root.", "type": "string", "minLength": 1, "maxLength": 512 }, "routes": { "description": "Which paths the Worker answers; everything else is served as a static file. A route whose `access` is `members` is gated by the platform before anything answers it, so a static site with no `entry` may declare members routes and nothing else.", "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A site-root-relative path the Worker answers. `*` is allowed only as a trailing `/*`." }, "access": { "description": "Who may reach this route. `members` requires a member of this site's workspace, signed in to Goosy; the platform enforces it before your code runs. Defaults to `public`.", "type": "string", "enum": [ "public", "members" ] } }, "required": [ "pattern" ], "additionalProperties": false } }, "bindings": { "description": "What this bundle asks to be wired to.", "type": "object", "properties": { "database": { "description": "The site's own database. Declaring it provisions one on the first build.", "type": "object", "properties": { "migrations": { "description": "Directory of `.sql` migrations for this site's own database, applied in filename order.", "type": "string", "minLength": 1, "maxLength": 512 }, "tables": { "description": "The tables this site's code owns.", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 63 } }, "stagedMigrationsPrefix": { "description": "PLATFORM-WRITTEN. Where the migrations above were actually staged, once the bundle was relocated into the reserved prefix. Never write this yourself — a manifest that carries it on upload is refused.", "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "projectDatabase": { "description": "How this site reaches the PROJECT database shared by its project's sites. Defaults to `none`.", "type": "string", "enum": [ "none", "read", "readwrite" ] }, "secrets": { "description": "Secret NAMES this Worker reads. Values are set on the site, never in this file.", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "submissions": { "description": "A table that platform form posts are also written to, so a static site keeps its own entries.", "type": "string", "minLength": 1, "maxLength": 63 }, "storage": { "description": "The site's own object store. Declaring it provisions one bucket on the first publish and binds it.", "type": "object", "properties": { "name": { "description": "The identifier your Worker reads the bucket through. Defaults to `BUCKET`.", "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "images": { "description": "Attach the image-transform binding, so your Worker can resize and re-encode bytes it already holds. Defaults to `false`.", "type": "boolean" }, "kv": { "description": "The site's own key-value store. Declaring it provisions one namespace on the first publish and binds it.", "type": "object", "properties": { "name": { "description": "The identifier your Worker reads the key-value store through. Defaults to `KV`.", "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false } }, "additionalProperties": false }, "limits": { "description": "The caps this bundle asks for. The platform decides the ceilings and refuses anything over them.", "type": "object", "properties": { "cpuMs": { "description": "CPU milliseconds per invocation. Defaults to 10000; the platform ceiling is 30000.", "type": "integer", "exclusiveMinimum": 0 }, "subRequests": { "description": "Outbound sub-requests per invocation. Defaults to 20; the platform ceiling is 50.", "type": "integer", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "runtime": { "description": "What this bundle's Worker needs from the Workers runtime. Read from your bundle's own `wrangler.json` when it ships one; declare it here otherwise.", "type": "object", "properties": { "compatibilityFlags": { "description": "Workers compatibility flags your Worker needs to start — global_fetch_strictly_public, nodejs_compat. Anything else is refused by name. Set this only when your bundle ships no JSON Wrangler config for us to read it from.", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "compatibilityDate": { "description": "The Workers compatibility date your bundle was COMPILED against, as `YYYY-MM-DD`. It is ignored unless it is newer than the platform's own pin — it can only move the date forward, never back.", "type": "string", "minLength": 1, "maxLength": 10 } }, "additionalProperties": false }, "forms": { "description": "The forms whose leads start an automation. A lead from a form named here raises its `event` beside `pages.lead.captured`; a form not named here raises only `pages.lead.captured`.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The form's name, as its lead carries it in the `form` field: lowercase letters, digits, `-` and `_`." }, "event": { "type": "string", "minLength": 1, "maxLength": 71, "description": "The automation event a lead from this form starts: `custom.` then a lowercase name of letters, digits and underscores, starting with a letter." } }, "required": [ "name", "event" ], "additionalProperties": false } } }, "additionalProperties": false, "description": "`pages.deploy.json` — the one file a bundle uses to say what it is and what it needs. Put it at the bundle root." } } }, "paths": { "/api/v1/tools/content.status": { "post": { "operationId": "call_content_status", "summary": "Call content.status", "description": "Read where this workspace's content stands — 'what's scheduled this week?', 'why did that post fail?' — every piece with its lifecycle status, its schedule, its elected platform versions, and the reason any of it failed. Call this before answering any question about what is drafted, ready, scheduled or live; never guess it. It reads only. Not for the week laid out by day — that is `schedule.read`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "content" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Only pieces in this lifecycle state.", "type": "string", "enum": [ "draft", "variants_in_progress", "ready", "approved", "scheduled", "publishing", "published", "verified", "failed" ] }, "format": { "description": "Only pieces of this format.", "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ] }, "limit": { "default": 25, "description": "How many pieces to return, newest-updated first.", "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "description": "Where to continue: pass the `next_cursor` from the previous page, with the same filters. Omit it for the first page.", "type": "string", "minLength": 1, "maxLength": 512 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "counts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "How many of the returned pieces sit in each status." }, "total": { "type": "number" }, "truncated": { "type": "boolean", "description": "True when more pieces matched than were returned. Deprecated: page with `cursor` until `next_cursor` is absent." }, "next_cursor": { "description": "Present when there is another page: pass it back as `cursor` to read it. Absent on the last page.", "type": "string" }, "pieces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "format": { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ] }, "status": { "type": "string", "enum": [ "draft", "variants_in_progress", "ready", "approved", "scheduled", "publishing", "published", "verified", "failed" ] }, "scheduled_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "status": { "type": "string" } }, "required": [ "platform", "status" ], "additionalProperties": false } } }, "required": [ "id", "title", "format", "status", "scheduled_for", "published_at", "failure_reason", "variants" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "counts", "pieces", "total", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/schedule.read": { "post": { "operationId": "call_schedule_read", "summary": "Call schedule.read", "description": "Read one week of this workspace's schedule grid — 'what's going out next week?', 'show me Thursday's slots' — the format rows the active cadence plans, every piece bucketed into its day column, and the zone those columns are in. It is the same grid /schedule draws, so the answer and the screen always agree, and it reads only. Not for each piece's lifecycle status and failure reasons — that is `content.status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "schedule" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "week": { "description": "Any date in the wanted week, as YYYY-MM-DD. Omit for the current week.", "type": "string" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "week_start": { "type": "string", "description": "The Monday of the returned week." }, "days": { "type": "array", "items": { "type": "string" }, "description": "The week's seven day columns." }, "display_time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The zone every day column is bucketed in." }, "has_cadence": { "type": "boolean", "description": "False when this workspace has no active cadence template." }, "meta_line": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ] }, "label": { "type": "string" }, "quota_line": { "type": "string" }, "planned_count": { "type": "number" } }, "required": [ "format", "label", "quota_line", "planned_count" ], "additionalProperties": false } }, "pieces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "format": { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ] }, "status": { "type": "string", "enum": [ "draft", "variants_in_progress", "ready", "approved", "scheduled", "publishing", "published", "verified", "failed" ] }, "day": { "type": "string" }, "scheduled_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platforms": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "format", "status", "day", "scheduled_for", "platforms" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "days", "display_time_zone", "has_cadence", "meta_line", "pieces", "rows", "week_start", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/library.search": { "post": { "operationId": "call_library_search", "summary": "Call library.search", "description": "Search this workspace's library — 'do we have a photo of the storefront?', 'find last month's launch video' — every finished image, clip, video and document, with the pinned ones first. Call this before answering any question about what this brand already has; never guess whether an asset exists. It reads only. Not for reading one item you already have the id of — that is `library.get`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "library" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "description": "Match items whose name contains this text. Omit to browse the shelf.", "type": "string" }, "roll": { "description": "Only this shelf. Omit to search all of them.", "type": "string", "enum": [ "images", "clips", "videos", "documents" ] }, "pinned_only": { "description": "Only items someone has pinned.", "type": "boolean" }, "limit": { "default": 25, "description": "How many items to return. Pinned items come first.", "type": "integer", "minimum": 1, "maximum": 50 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "total": { "type": "number" }, "truncated": { "type": "boolean", "description": "True when more matched than were returned, or the search window was reached. Narrow by roll rather than trusting a short answer." }, "search_window": { "type": "number", "description": "How many items the text match ran over — the newest of this workspace's finished work, pinned items first. Only meaningful with `query`." }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image_generation", "storage_object", "video_unit", "document" ], "description": "What sort of object this is — pass it back to library.get." }, "id": { "type": "string", "description": "The object's own id. With `kind`, this addresses it exactly." }, "roll": { "type": "string", "enum": [ "images", "clips", "videos", "documents" ], "description": "Which shelf of the library it sits on." }, "title": { "type": "string", "description": "What it is called: the name someone typed when pinning it, else the object's own label." }, "pinned": { "type": "boolean", "description": "Has someone pinned this to the shelf?" }, "pinned_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "finalized_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was promoted into the library." }, "source_board_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The board it was made on, when that board still exists." }, "source_board_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_image_generation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The image whose bytes preview it, when it has one." }, "preview_has_bytes": { "type": "boolean" } }, "required": [ "kind", "id", "roll", "title", "pinned", "pinned_name", "finalized_at", "source_board_id", "source_board_name", "preview_image_generation_id", "preview_has_bytes" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "items", "search_window", "total", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/library.get": { "post": { "operationId": "call_library_get", "summary": "Call library.get", "description": "Read one library item by the `kind` and `id` library.search returned — 'open that video', 'where was this image made?'. Use it to confirm an item still exists and to see where it was made before you reference it; it reads only. Not for finding items by what they are — that is `library.search`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "library" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image_generation", "storage_object", "video_unit", "document" ], "description": "The item's kind, exactly as library.search reported it." }, "id": { "type": "string", "minLength": 1, "description": "The item's id from library.search." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "kind": { "type": "string", "enum": [ "image_generation", "storage_object", "video_unit", "document" ], "description": "What sort of object this is — pass it back to library.get." }, "id": { "type": "string", "description": "The object's own id. With `kind`, this addresses it exactly." }, "roll": { "type": "string", "enum": [ "images", "clips", "videos", "documents" ], "description": "Which shelf of the library it sits on." }, "title": { "type": "string", "description": "What it is called: the name someone typed when pinning it, else the object's own label." }, "pinned": { "type": "boolean", "description": "Has someone pinned this to the shelf?" }, "pinned_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "finalized_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was promoted into the library." }, "source_board_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The board it was made on, when that board still exists." }, "source_board_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_image_generation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The image whose bytes preview it, when it has one." }, "preview_has_bytes": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "finalized_at", "id", "kind", "pinned", "pinned_name", "preview_has_bytes", "preview_image_generation_id", "roll", "source_board_id", "source_board_name", "title", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/knowledge.search": { "post": { "operationId": "call_knowledge_search", "summary": "Call knowledge.search", "description": "Search this workspace's own brand corpus — 'what do we say about pricing?', 'how do we describe our service?' — everything ingested about how this brand talks, what it sells and what it has published. Call this before answering any question about what the brand says; never guess it. Results are this brand's material only. Not for the live web — that is `web.api_search`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "knowledge" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What to look for in the brand corpus, in plain words." }, "limit": { "default": 5, "description": "How many chunks to return, closest match first.", "type": "integer", "minimum": 1, "maximum": 20 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "query": { "type": "string", "description": "The query as it was actually searched." }, "hits": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "What kind of thing the chunk came from — url, file, text, youtube, and so on." }, "excerpt": { "type": "string" }, "relevance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Higher is closer to the query." }, "affinity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which corpus slice it came from, when the row says." } }, "required": [ "source", "excerpt", "relevance", "affinity" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "hits", "query", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/connections.status": { "post": { "operationId": "call_connections_status", "summary": "Call connections.status", "description": "Read this workspace's live connections — 'is Instagram connected?', 'what needs reconnecting?' — what is connected, what needs attention, what is available to connect, and what is not built yet. Call this before answering any question about connection state; never guess it. Not for connecting an account: that is an operator decision made on screen, and no verb here does it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "connections" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "connected": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "What the connection is called, in the operator's own words." }, "state": { "type": "string", "description": "Where it stands — connected_live, token_expired, not_connected, and so on." }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which account or grant it rides, when it names one." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One short sentence, on states that need attention only." } }, "required": [ "name", "state", "account", "note" ], "additionalProperties": false } }, "needs_attention": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "What the connection is called, in the operator's own words." }, "state": { "type": "string", "description": "Where it stands — connected_live, token_expired, not_connected, and so on." }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which account or grant it rides, when it names one." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One short sentence, on states that need attention only." } }, "required": [ "name", "state", "account", "note" ], "additionalProperties": false } }, "available": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "What the connection is called, in the operator's own words." }, "state": { "type": "string", "description": "Where it stands — connected_live, token_expired, not_connected, and so on." }, "account": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which account or grant it rides, when it names one." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One short sentence, on states that need attention only." } }, "required": [ "name", "state", "account", "note" ], "additionalProperties": false }, "description": "Connectable today, not connected yet." }, "coming_soon": { "type": "array", "items": { "type": "string" }, "description": "Named so you can say 'not yet' rather than invent a way in." }, "counts": { "type": "object", "properties": { "connected": { "type": "integer", "minimum": 0 }, "attention": { "type": "integer", "minimum": 0 } }, "required": [ "connected", "attention" ], "additionalProperties": false }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "available", "coming_soon", "connected", "counts", "needs_attention", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/credits.balance": { "post": { "operationId": "call_credits_balance", "summary": "Call credits.balance", "description": "Read how many credits this account has left — 'how many credits do we have?', 'are we running low on credits?'. Say the figure back exactly as given — never work one out or recall one. Not for topping up: a person does that on Settings → Billing, and no verb here can.", "tags": [ "credits" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` whenever the call did not succeed, including when the tool itself returned a typed `ok: false` — this tool runs at account level, so there is no workspace boundary to distinguish. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "balance": { "type": "number", "description": "How many credits are left on the account that pays for this workspace." } }, "required": [ "ok", "balance" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/content.create_request": { "post": { "operationId": "call_content_create_request", "summary": "Call content.create_request", "description": "Ask this workspace to make a new piece of content on a given day — 'add a post on Thursday', 'we need something going out next Monday'. It is the same request the operator makes by pressing the plus in a cell of the schedule grid: it lands in that week's block, on the cadence's own planned slot when one is free, with the platforms that cadence elects. Not for reading what is already planned — that is `schedule.read`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "content" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ], "description": "What kind of piece to create a request for." }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The day it is planned for, as YYYY-MM-DD. The workspace's own cadence decides the time of day." }, "title": { "description": "A working title. Omit to leave it untitled.", "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "format", "day" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "piece_id": { "type": "string" }, "format": { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ] }, "scheduled_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it is planned to publish, ISO 8601 UTC." }, "week_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The publication week it grouped under, when the workspace has one open." }, "filled_planned_slot": { "type": "boolean", "description": "True when it filled a slot the workspace's cadence already planned." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "filled_planned_slot", "format", "piece_id", "scheduled_for", "week_block_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/library.update": { "post": { "operationId": "call_library_update", "summary": "Call library.update", "description": "Rename one item in this workspace's library — 'rename that video to Spring launch', 'call this image Hero shot'. Renaming is the only thing it changes: it never edits, regenerates, moves or removes the work itself, and there is no verb here that can. Not for finding the item — that is `library.search`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "library" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "string", "description": "Which library item to change — an id from library.search." }, "name": { "type": "string", "maxLength": 120, "description": "The new name. Send an empty string to clear it back to unnamed, which lets the item's own description show instead." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "item_id", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The stored name, or null when it is unnamed." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "id", "name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.generate": { "post": { "operationId": "call_images_generate", "summary": "Call images.generate", "description": "Generate new images onto a board in this workspace — 'make three pictures of our product on a beach', 'generate a hero image for the launch'. It spends credits, so it answers in two calls on every key: without confirmation_id it checks the board, says what would be made and returns a confirmation_id, and makes and charges nothing; the same call again with that confirmation_id, on a member's own API key, starts the run and answers its run_id. Not for changing an image that already exists — that is `images.iterate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board": { "type": "string", "description": "Which board the images land on — a board id in this workspace." }, "brief": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What to generate, in plain words." }, "count": { "default": 1, "description": "How many images to make. Each one costs credits.", "type": "integer", "minimum": 1, "maximum": 10 }, "shape": { "description": "The aspect ratio. Omit for the workspace default.", "type": "string", "enum": [ "1:1", "3:4", "4:3", "9:16", "16:9" ] }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board", "brief" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present only while confirmation is required. Send it back on the second call." } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "anyOf": [ { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present only while confirmation is required — what will be made, in one sentence, for a person to approve." } ] }, "status": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "enum": [ "dispatched", "accepted" ], "description": "dispatched — the run is under way. accepted — the run is under way but its details could not be read just now: count and aspect_ratio are null; follow it by run_id. (The first call answers confirmation_required: nothing ran and nothing was charged.)" } ] }, "count": { "anyOf": [ { "type": "integer", "description": "How many images this run covers." }, { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "How many images this run covers; null when accepted." } ] }, "aspect_ratio": { "anyOf": [ { "type": "string" }, { "anyOf": [ { "type": "string" }, { "type": "null" } ] } ] }, "board_id": { "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present only once dispatched — the run to follow." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "aspect_ratio", "board_id", "confirmation_id", "count", "request_summary", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.iterate": { "post": { "operationId": "call_images_iterate", "summary": "Call images.iterate", "description": "Edit an image already on a board in this workspace — 'make the background darker on that image', 'swap the shirt colour to blue'. It spends credits, so it answers in two calls on every key: without confirmation_id it checks the board, says what would be changed and returns a confirmation_id, and changes and charges nothing; the same call again with that confirmation_id, on a member's own API key, starts the edit and answers its run_id. Not for a brand-new image — that is `images.generate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board": { "type": "string", "description": "Which board the images land on — a board id in this workspace." }, "brief": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What to generate, in plain words." }, "count": { "default": 1, "description": "How many images to make. Each one costs credits.", "type": "integer", "minimum": 1, "maximum": 10 }, "shape": { "description": "The aspect ratio. Omit for the workspace default.", "type": "string", "enum": [ "1:1", "3:4", "4:3", "9:16", "16:9" ] }, "parent_generation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The existing image on this board to edit." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board", "brief", "parent_generation_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present only while confirmation is required. Send it back on the second call." } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "anyOf": [ { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present only while confirmation is required — what will be made, in one sentence, for a person to approve." } ] }, "status": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "enum": [ "dispatched", "accepted" ], "description": "dispatched — the run is under way. accepted — the run is under way but its details could not be read just now: count and aspect_ratio are null; follow it by run_id. (The first call answers confirmation_required: nothing ran and nothing was charged.)" } ] }, "count": { "anyOf": [ { "type": "integer", "description": "How many images this run covers." }, { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "How many images this run covers; null when accepted." } ] }, "aspect_ratio": { "anyOf": [ { "type": "string" }, { "anyOf": [ { "type": "string" }, { "type": "null" } ] } ] }, "board_id": { "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present only once dispatched — the run to follow." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "aspect_ratio", "board_id", "confirmation_id", "count", "request_summary", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/pages.ai.generate_text": { "post": { "operationId": "call_pages_ai_generate_text", "summary": "Call pages.ai.generate_text", "description": "Generate bounded managed text for the credential-bound Pages workload — 'write a headline for this section', 'draft the FAQ answers'. Not for searching the web — that is `web.api_search`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "pages" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What the generated text should accomplish." }, "input": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "citations": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "excerpt": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "additionalProperties": false } } }, "required": [ "text" ], "additionalProperties": false, "description": "The source text and optional citations the generated text must use." }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "requestedOutputTokens": { "description": "Required for an initial text request and bounded by the admitted policy.", "type": "integer", "exclusiveMinimum": 0 }, "tier": { "description": "Optional configured writing tier. Omit to use the grant default.", "type": "string", "minLength": 1, "maxLength": 128 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/web.search": { "post": { "operationId": "call_web_search", "summary": "Call web.search", "description": "Run a bounded managed web search for the credential-bound workload — 'search for local coffee roasters', 'find recent news on this topic'. Not for reading one page you already have the address of — that is `web.api_read`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "web" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The web search query." }, "mode": { "default": "answer", "description": "Use answer for synthesis, semantic for relevance, or serp for ranked web results.", "type": "string", "enum": [ "answer", "semantic", "serp" ] }, "maxResults": { "default": 5, "description": "The maximum number of search results to return.", "type": "integer", "minimum": 1, "maximum": 10 }, "freshnessDays": { "description": "Optional maximum age in days for search results when supported.", "type": "integer", "minimum": 1, "maximum": 365 }, "includeDomains": { "description": "Optional domains to include in the search.", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 } }, "excludeDomains": { "description": "Optional domains to exclude from the search.", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 } }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/web.read": { "post": { "operationId": "call_web_read", "summary": "Call web.read", "description": "Read one web page for the credential-bound workload, within its managed bounds — 'read this link', 'what does their pricing page say?'. Not for finding pages you do not have yet — that is `web.api_search`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "web" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "The public HTTP or HTTPS page to read." }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/web.image_search": { "post": { "operationId": "call_web_image_search", "summary": "Call web.image_search", "description": "Find image references for the credential-bound workload, within its managed bounds — 'find photos of mountain cabins', 'look for a picture of a latte'. It returns references only. Not for bringing one onto the site board — that is `images.api_acquire_remote`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "web" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The image search query." }, "maxResults": { "default": 5, "description": "The maximum number of image results to return.", "type": "integer", "minimum": 1, "maximum": 10 }, "imageType": { "description": "Optional image content type to prefer.", "type": "string", "enum": [ "face", "photo" ] }, "size": { "description": "Optional image size to prefer.", "type": "string", "enum": [ "medium", "large" ] }, "aspect": { "description": "Optional image aspect ratio to prefer.", "type": "string", "enum": [ "square", "tall", "wide" ] }, "usageRights": { "description": "Optional usage-rights filter for returned images.", "type": "string", "enum": [ "creative_commons_licenses", "commercial_or_other_licenses" ] }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.acquire_remote": { "post": { "operationId": "call_images_acquire_remote", "summary": "Call images.acquire_remote", "description": "Bring one managed image-search result onto the credential-bound site board — 'use that photo on the site', 'save the second result to the board'. Not for finding images — that is `web.api_image_search`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "searchRequestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The completed managed image-search request that produced the result." }, "position": { "type": "integer", "minimum": 1, "description": "The one-based position of the search result to acquire into the site board." }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/board.tree": { "post": { "operationId": "call_board_tree", "summary": "Call board.tree", "description": "Read this workspace's projects and boards as a tree — 'what projects do we have?', 'where does the client site live?'. It reads through the bearer-key API principal, changes nothing, and supplies the project ids `work.file` and `work.shortcut` take. Not for creating a project — that is `projects.create`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "board" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "Narrow it to one sort of thing — 'site' for the operator's sites, 'images' for image boards, 'automation' for automations. Leave it out to see everything. Folders always show if they hold a match.", "type": "string", "minLength": 1, "maxLength": 40 }, "root_board_id": { "description": "Start inside one folder, as a UUID from something you were shown. Leave it out for the whole workspace.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "roots": { "type": "array", "items": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "kind": { "type": "string" }, "parent_board_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "updated_at": { "type": "string" }, "referenced": { "type": "boolean" }, "children": { "type": "array", "items": {} } }, "required": [ "board_id", "name", "kind", "parent_board_id", "updated_at", "referenced", "children" ], "additionalProperties": false } }, "truncated": { "type": "boolean" }, "answer_note": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "roots", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/board.rename": { "post": { "operationId": "call_board_rename", "summary": "Call board.rename", "description": "Rename a board or project, a Dashboard desk (tab) included — 'call this project Spring Launch', 'change the name of the ads board to Q3 Ads', 'Home should be called Dashboard'. Gives any board or project in this workspace the name the member chose, Home and Splash Pad included. Take board_id from the board the member is on or `board.tree`. Only the name changes: nothing inside it moves or is deleted, and it can be renamed again. A name the member gives is kept; Goosy's automatic naming never replaces it. Not for moving it into another project — that is `work.file`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "board" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The new name, in the member's own words." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "answer_note": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without renaming anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "board_id", "name", "replayed", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/board.reorder": { "post": { "operationId": "call_board_reorder", "summary": "Call board.reorder", "description": "Move a project to a new place among the projects beside it — 'put Analytics before Today', 'make the client tab the last one', 'move Spring launch to the top'. It changes the order the Dashboard's tabs, or a project's sub-projects, read in; nothing moves into or out of anything. Say exactly one of: the sibling it goes before, the one it goes after, or first or last. A project at the top level of the workspace is ordered by activity and cannot be placed by hand. Not for putting it inside a different project — that is `work.file`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "board" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "before_board_id": { "description": "Put it just before this sibling, by its id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "after_board_id": { "description": "Put it just after this sibling, by its id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "place": { "description": "Put it first or last among its siblings.", "type": "string", "enum": [ "first", "last" ] }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string" }, "name": { "type": "string" }, "answer_note": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "board_id", "name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/board.trash": { "post": { "operationId": "call_board_trash", "summary": "Call board.trash", "description": "Send a project or board to the Trash — 'delete the Spring launch project', 'get rid of that tab', 'remove the Analytics desk' (a desk by its id from `widget.list`). Everything inside it goes with it, and all of it can be restored for 30 days, after which it is deleted for good. Home and Splash Pad cannot be trashed. Calling it raises the approval card when no member asked for it. Not for taking one widget off a desk — that is `item.trash`; not for bringing one back — that is `board.restore`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "board" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The project, board or Dashboard desk, by its id from `board.tree` or `widget.list`." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string" }, "name": { "type": "string" }, "answer_note": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/board.restore": { "post": { "operationId": "call_board_restore", "summary": "Call board.restore", "description": "Bring a project or board back out of the Trash, with everything that was inside it — 'undo deleting that tab', 'restore the Spring launch project'. It returns to where it was. It works for 30 days after the trash; a board already deleted for good cannot come back. Not for bringing back a trashed widget — that is `item.restore`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "board" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string" }, "name": { "type": "string" }, "answer_note": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "board_id", "name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/item.rename": { "post": { "operationId": "call_item_rename", "summary": "Call item.rename", "description": "Rename an image, an uploaded file, a data table, an email, a whole site or app, an automation, a video or short, or a widget on a desk or project — 'name the sunset picture Cover art', 'rename the uploaded price sheet to Pricing 2026', 'the signups table should be called Webinar leads', 'call the first welcome email Your table is ready', 'call this site Harbor Dental Care', 'change the name of the Monday report automation to Weekly Digest', 'retitle the spring promo video Spring Is Here', 'call the leads number Daily leads'. Gives the item the name the member chose, the one its tile, its list and every project it sits in show; an email's name is its subject line, so renaming an email changes the subject its readers see, and an email that is set to send is refused until the member sends it back to draft. Only the name changes: what the item holds, an email's body, a site's address, pages and live site, an automation's steps and whether it is on, a video's script, scenes and renders, and what a widget shows stay as they are; nothing is rebuilt, sent or published, and it can be renamed again. Send `item_id` when a verb or the page showed you the item's id — a site's site_id, an automation's definition_id from `automations.list`, never its board_id, a video's video_unit_id, a widget's id from `widget.list`; otherwise send `current_name`, the member's words for what it is called now (an image with no name yet goes by the words of its prompt, an email by its subject, a video or a widget by its title; a site the member has open needs neither), and call it straight away — when several items match, the answer lists them so you can ask which. Not for a project or board, a course or series included — that is `board.rename` — nor one page inside a site, which is `page.set_page_label`, nor a library item named by a `library.search` id, which is `library.update`, nor what a widget shows, which is `widget.update`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "item" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_kind": { "type": "string", "enum": [ "image", "file", "table", "email", "site", "automation", "video", "widget" ], "description": "What the item is: an image, an uploaded file, a data table, an email, a whole site or app, an automation, a video (a short is a video too), or a widget on a desk or project (a chart, a number, a note on a desk, a link, a button)." }, "item_id": { "description": "The item's id, as a UUID a verb or the page showed you; for an automation, its definition_id; for a widget, its id from `widget.list`. Leave it out when you only have the member's words for it.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "current_name": { "description": "The member's words for what the item is called now, when there is no item_id.", "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The new name, in the member's own words." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "item_kind", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "item_kind": { "type": "string", "enum": [ "image", "file", "table", "email", "site", "automation", "video", "widget" ] }, "item_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "answer_note": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without renaming anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "item_id", "item_kind", "name", "replayed", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/item.trash": { "post": { "operationId": "call_item_trash", "summary": "Call item.trash", "description": "Move an image, a document, an email, a post, a data table, a whole site or app, an automation, a video or short, or a widget on a desk or project (a chart, a number, a note, a link, a button) to the Trash — 'trash that sunset image', 'get rid of the draft welcome email', 'bin the post about the new menu', 'throw away the old signups table', 'we are done with the Acme landing site, bin it', 'delete the Monday report automation', 'delete the spring promo video', 'take the leads chart off my desk'. The item leaves every project and list it shows in and can be restored from the Trash for 30 days; nothing is charged. A trashed post never publishes: its scheduled versions are set aside and its place on the schedule is freed, and a post already out stays on the platform. An automation is switched off first and stays off. An email that is set to send is refused until the member sends it back to draft, and a post going out right now is refused until it has posted. A widget shown in several places can leave just one: send `from_place`, the desk or project it comes off by name, or its id as `from_project_id`, and it keeps showing in its other places. Calling it raises the approval card naming exactly the item it found, and the card is where the member checks it is the right one, so call it on the ask rather than asking which one first. Send `item_id` when a verb or the page showed you the item's id — a site's site_id, an automation's definition_id from `automations.list`, a video's video_unit_id, a widget's id from `widget.list`; otherwise send `name`, the member's words for its name, title or subject (a site the member has open needs neither). Not for a project — that is `board.trash` — nor for letting a widget come down on its own later, which is `widget.set_expiry`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "item" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_kind": { "type": "string", "enum": [ "image", "document", "email", "post", "table", "site", "automation", "video", "widget" ], "description": "What the item is: an image, a document, an email, a post, a data table, a whole site or app, an automation, a video (a short is a video too), or a widget on a desk or project (a chart, a number, a note on a desk, a link, a button)." }, "item_id": { "description": "The item's id, as a UUID a verb or the page showed you; for an automation, its definition_id; for a widget, its id from `widget.list`. Leave it out when you only have the member's words for it.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "description": "The member's words for the item's name, when there is no item_id.", "type": "string", "minLength": 1, "maxLength": 200 }, "from_project_id": { "description": "For a widget only: the project to take it off, by its id from `widget.list`. It leaves that one place and keeps showing in its others; it goes to the Trash only when that was its last place. Leave it out to send the widget to the Trash from everywhere.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "from_place": { "description": "For a widget only: the desk or project to take it off, by its name as they said it ('My desk', 'Acme retainer'), in place of from_project_id. It keeps showing in its other places.", "type": "string", "minLength": 1, "maxLength": 200 }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "item_kind" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "item_kind": { "type": "string", "enum": [ "image", "document", "email", "post", "table", "site", "automation", "video", "widget" ] }, "item_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "trashed": { "type": "boolean", "description": "True when it went to the Trash; false when a widget only left the one place from_project_id named." }, "answer_note": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/projects.create": { "post": { "operationId": "call_projects_create", "summary": "Call projects.create", "description": "Make a new project where the member is — 'start a project for the Harbor Dental rebrand', 'I need a new project called Fall menu', 'set up a sub-project here for the photo shoot'. A project is a canvas that holds the member's work and other projects. Made while the member is on a project, it goes inside that project; anywhere else it goes in Splash Pad, unless the member names the project it belongs in (parent_project_id from `board.tree`). It needs a name, so ask what to call it if they have not said. It starts empty: nothing is moved, published or spent. Not for moving something that already exists into a project (`work.file`), or for choosing where the member's new work starts from now on (`work.here`).\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "projects" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What to call the project, in the member's own words." }, "parent_project_id": { "description": "The project to make it inside, when the member named one. Left out, it is made inside the project the member is on, or in Splash Pad.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "project_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "parent_project_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "answer_note": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without changing anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "name", "parent_project_id", "project_id", "replayed", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/items.place": { "post": { "operationId": "call_items_place", "summary": "Call items.place", "description": "Bring an existing item — a photo, video, document, file, table, email, post, site, automation — onto the canvas the member is on now, as its home; a project the member names is `work.file` — 'put the leads table on this canvas', 'bring the logo file into this project', 'add the welcome email here'. Any item: a site, an automation, a video or short, a post, an image or photo, a document, an uploaded file, a data table, an email or a widget. This verb finds the item itself, so call it on the ask: put the member's words for the thing in item_name, a generic name too ('the new doc', 'that photo from Friday'), for any item but a widget. Among several matches it takes the one in the project the member is on, then the exact name; otherwise it moves nothing and answers with the matches by name and place, so you can ask which. The item then lives in the project the member is on (where their new work starts when they are on none); if it lived in another project it leaves that one, because an item lives in one place. Nothing is copied or deleted, and the member can undo it. Send item_id instead only when this conversation already showed you the item's id. Not for putting it in a project the member names (`work.file`), or for showing the item here while it stays where it lives (`work.shortcut`).\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "items" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_kind": { "type": "string", "enum": [ "site", "automation", "video", "post", "image", "document", "file", "table", "email", "widget" ], "description": "What it is: a site, an automation, a video (or short), a post, an image (a photo or picture), a document, an uploaded file, a data table, an email or a widget." }, "item_id": { "description": "Its id, only when a verb or the page already showed it to you (a project's from `board.tree`, a widget's from `widget.list`). Otherwise send item_name: never call a list just to find an id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "item_name": { "description": "The member's words for its name, title or subject ('the latte video', 'price list', 'the Monday report automation'), a generic name included. It works for every kind but a project and a widget; the tool finds the item itself, with no read first, and when several things match the answer lists them by name and place so you can ask which.", "type": "string", "minLength": 1, "maxLength": 200 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "item_kind" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "item_kind": { "type": "string", "enum": [ "site", "automation", "video", "post", "image", "document", "file", "table", "email", "widget" ] }, "item_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "from_project_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "trail": { "type": "string" }, "answer_note": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without changing anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "from_project_id", "item_id", "item_kind", "name", "project_id", "replayed", "trail", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/work.file": { "post": { "operationId": "call_work_file", "summary": "Call work.file", "description": "File or move any item — a document, photo, video, file, table, email, post, site, automation — or a whole project into a project the member names — 'move the onboarding video to the Clients project', 'put the Holiday gift boxes project under Wholesale cafes', 'the menu photos belong in Spring launch'. Any item (a site, an automation, a video or short, a post, an image or photo, a document, an uploaded file, a data table, an email, a widget) or a project, which takes everything inside it along. This verb finds the item itself, so call it on the ask: put the member's words for the thing in item_name, a generic name too ('the new doc', 'that photo from Friday'), for any item but a widget. Among several matches it takes the one in the project the member is on, then the exact name; otherwise it moves nothing and answers with the matches by name and place, so you can ask which. Read `board.tree` for to_project_id, the id of the project the member names; the tree lists projects, not the items inside them, so look for the item through this verb rather than in the tree. The project the member is on (the page's board_id) is where the item comes from, so it is never to_project_id here; putting a thing on that project is `items.place`. It leaves where it was and lives only in the new project; its shortcuts follow it, nothing is copied or deleted, and the member can undo it. A null to_project_id takes a project out to the top level of Projects; name a project being moved with item_kind project and its id from `board.tree`. Not for putting something on the project the member is on right now (`items.place`), or for showing it in a second project while it stays where it lives (`work.shortcut`).\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "work" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_kind": { "description": "What it is: a site, an automation, a video (or short), a post, an image (a photo or picture), a document, an uploaded file, a data table, an email, a widget, or a project.", "type": "string", "enum": [ "site", "automation", "video", "post", "image", "document", "file", "table", "email", "widget", "project" ] }, "item_id": { "description": "Its id, only when a verb or the page already showed it to you (a project's from `board.tree`, a widget's from `widget.list`). Otherwise send item_name: never call a list just to find an id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "item_name": { "description": "The member's words for its name, title or subject ('the latte video', 'price list', 'the Monday report automation'), a generic name included. It works for every kind but a project and a widget; the tool finds the item itself, with no read first, and when several things match the answer lists them by name and place so you can ask which.", "type": "string", "minLength": 1, "maxLength": 200 }, "to_project_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ], "description": "The project the member names as where it goes, by its id from `board.tree`. null only to take a project out to the top level of Projects." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "to_project_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "item_kind": { "type": "string", "enum": [ "site", "automation", "video", "post", "image", "document", "file", "table", "email", "widget", "project" ] }, "item_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "from_project_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "to_project_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "trail": { "type": "string" }, "answer_note": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without changing anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "from_project_id", "item_id", "item_kind", "name", "replayed", "to_project_id", "trail", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/work.shortcut": { "post": { "operationId": "call_work_shortcut", "summary": "Call work.shortcut", "description": "Make a shortcut to any item — a document, photo, video, table, automation — or a project in another project, so it shows there too while it stays where it lives — 'show the brand video in the Launch project as well', 'link the pricing table into Wholesale cafes too', 'I want the onboarding automation reachable from Clients'. A shortcut opens the original: a change to the original shows everywhere, and nothing is copied or moved. This verb finds the item itself, so call it on the ask: put the member's words for the thing in item_name, a generic name too ('the new doc', 'that photo from Friday'), for any item but a widget. Among several matches it takes the one in the project the member is on, then the exact name; otherwise it moves nothing and answers with the matches by name and place, so you can ask which. Read `board.tree` for to_project_id, the id of the project the member names; the tree lists projects, not the items inside them, so look for the item through this verb rather than in the tree. Any item or a project can have one, and the member can remove it or undo it. Name a project with item_kind project and its id from `board.tree`. Not for moving the thing itself into that project (`work.file`).\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "work" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_kind": { "description": "What it is: a site, an automation, a video (or short), a post, an image (a photo or picture), a document, an uploaded file, a data table, an email, a widget, or a project.", "type": "string", "enum": [ "site", "automation", "video", "post", "image", "document", "file", "table", "email", "widget", "project" ] }, "item_id": { "description": "Its id, only when a verb or the page already showed it to you (a project's from `board.tree`, a widget's from `widget.list`). Otherwise send item_name: never call a list just to find an id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "item_name": { "description": "The member's words for its name, title or subject ('the latte video', 'price list', 'the Monday report automation'), a generic name included. It works for every kind but a project and a widget; the tool finds the item itself, with no read first, and when several things match the answer lists them by name and place so you can ask which.", "type": "string", "minLength": 1, "maxLength": 200 }, "to_project_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The project the member names for the shortcut to appear in, by its id from `board.tree`." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "to_project_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "item_kind": { "type": "string", "enum": [ "site", "automation", "video", "post", "image", "document", "file", "table", "email", "widget", "project" ] }, "item_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "home_project_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "to_project_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "shortcut_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "trail": { "type": "string" }, "answer_note": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without changing anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "home_project_id", "item_id", "item_kind", "name", "replayed", "shortcut_id", "to_project_id", "trail", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/item.restore": { "post": { "operationId": "call_item_restore", "summary": "Call item.restore", "description": "Bring an image, a document, an email, a post, a data table, a video or short, or a widget back out of the Trash — 'bring back the lighthouse photo I trashed', 'restore the onboarding checklist doc', 'undo binning the renewal reminder email', 'I need the vendor contacts table back', 'take the open mic post out of the Trash', 'get the deleted harbor tour video back', 'put the bookings chart back'. The item returns to every project and list it left, under its name and with everything it held; nothing is charged, sent or published. A post comes back unscheduled: its place on the schedule was freed when it was trashed, so the member schedules it again. A widget comes back onto every desk and project it showed on. Call it straight away on the ask. Send `item_id` when a verb or the Trash page showed you the item's id (a widget's from `widget.list` with in_trash); otherwise send `name`, the member's words for its name, title or subject — when several trashed items match, the answer lists them so you can ask which. Not for a project — that is `board.restore` — nor a site or an automation, which comes back from the Trash page with its board.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "item" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_kind": { "type": "string", "enum": [ "image", "document", "email", "post", "table", "video", "widget" ], "description": "What the item is: an image, a document, an email, a post, a data table, a video (a short is a video too), or a widget." }, "item_id": { "description": "The item's id, as a UUID a verb or the page showed you; for an automation, its definition_id; for a widget, its id from `widget.list`. Leave it out when you only have the member's words for it.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "description": "The member's words for the trashed item's name, when there is no item_id.", "type": "string", "minLength": 1, "maxLength": 200 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "item_kind" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "item_kind": { "type": "string", "enum": [ "image", "document", "email", "post", "table", "video", "widget" ] }, "item_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "restored": { "type": "boolean", "const": true }, "answer_note": { "type": "string" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without restoring anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "answer_note", "item_id", "item_kind", "name", "replayed", "restored", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/data.create_table": { "post": { "operationId": "call_data_create_table", "summary": "Call data.create_table", "description": "Create a typed Data table in this workspace — 'make a table to track sponsors', 'set up a list of our venues'. It lands where the key's new work starts (the workspace's Splash Pad unless a Work here project is set); file it into a project with `work.file`. Not for adding rows — that is `data.api_append`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "data" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "What this table is called, in the operator's own words." }, "columns": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The column's identifier: lower snake case, starting with a letter, at most 64 characters (for example `first_name`). It is what row values are keyed by." }, "label": { "type": "string", "maxLength": 120, "description": "What a person reads at the head of the column." }, "type": { "type": "string", "enum": [ "text", "number", "boolean", "date", "email", "phone", "url", "json", "action", "file" ], "description": "The cell type. Values are coerced to it at every write and REFUSED when they do not fit, so pick the narrowest one that is honestly true." }, "required": { "description": "Leave it out unless a row is meaningless without this column.", "type": "boolean" }, "source": { "description": "WHO fills this column — a connector key or an automation, in free text. Never a vendor name you assumed; only one the operator or a tool gave you.", "type": "string", "maxLength": 80 }, "event": { "description": "For an `action` column only: the `custom.` event its row button sends.", "type": "string" } }, "required": [ "key", "label", "type" ], "description": "One typed column of a data table.", "additionalProperties": false }, "description": "The typed header. At most 100 columns. Every column key must be unique in the table." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "columns", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "table_id": { "type": "string" }, "name": { "type": "string" }, "board_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "board_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "column_count": { "type": "number" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "board_item_id", "column_count", "name", "table_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/data.describe": { "post": { "operationId": "call_data_describe", "summary": "Call data.describe", "description": "Describe this workspace's typed Data tables — 'what tables do we have?', 'what columns does the sponsors table have?' — optionally narrowed to one table or one board. It reads only. Not for reading the rows themselves — that is `data.api_query`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "data" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The table to describe." }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "Describe every data table on this board instead of one table by id." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "tables": { "type": "array", "items": { "type": "object", "properties": { "table_id": { "type": "string" }, "name": { "type": "string" }, "board_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "row_count": { "type": "number" }, "row_limit": { "type": "number" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "label", "type", "required", "source" ], "additionalProperties": false } }, "sources": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "published_columns": { "type": "array", "items": { "type": "string" } } }, "required": [ "table_id", "name", "board_id", "row_count", "row_limit", "columns", "sources", "published_columns" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "tables", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/data.query": { "post": { "operationId": "call_data_query", "summary": "Call data.query", "description": "Read rows from one Data table — 'which sponsors have no phone number?', 'show the ten newest venues' — with the same named-column filters, ordering and cursor paging as the product grid. It reads only. Not for the table's columns and limits — that is `data.api_describe`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "data" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The table being asked about." }, "has_value_in": { "description": "Only rows that HAVE a value in every one of these columns.", "type": "array", "items": { "type": "string" } }, "missing_value_in": { "description": "Only rows with NO value in any one of these columns — this is how you answer 'which of these have no phone?'.", "type": "array", "items": { "type": "string" } }, "equals": { "description": "Column key to exact value. Only for columns that exist on the table.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "order_by": { "description": "A column key to sort by. Leave it out for the natural order.", "type": "string" }, "descending": { "description": "Sort the other way.", "type": "boolean" }, "limit": { "description": "How many rows to bring back, at most 100. The total count is always returned whatever this is, so ask for few rows and report the count.", "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "description": "The `next_cursor` an earlier page answered with; leave it out for the first page.", "type": "string" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "table_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "table_id": { "type": "string" }, "count_line": { "type": "string" }, "total": { "type": "number" }, "returned": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "row_id": { "type": "string" }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "source": { "type": "string" } }, "required": [ "row_id", "values", "source" ], "additionalProperties": false } }, "next_cursor": { "description": "Present when more rows match: pass it as `cursor` for the next page.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "count_line", "returned", "rows", "table_id", "total", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/data.append": { "post": { "operationId": "call_data_append", "summary": "Call data.append", "description": "Add one validated row to a Data table — 'add Acme to the sponsors table', 'put a row in for the new venue'. Every value is checked against the table's columns, and reusing the same retry key never creates a second row. Not for changing a cell in an existing row — that is `data.api_update_cell`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "data" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The table gaining a row." }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The row, keyed by column key. Every key must be a column on the table — an unknown one is REFUSED, never dropped, so add the column first. Values are coerced to their column's type or refused." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "table_id", "values" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "table_id": { "type": "string" }, "row_id": { "type": "string" }, "row_count": { "type": "integer" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "row_count", "row_id", "table_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/data.update_cell": { "post": { "operationId": "call_data_update_cell", "summary": "Call data.update_cell", "description": "Change one cell of an existing row in a Data table — 'set Acme's status to signed', 'fix the phone number on that row'. The whole row is validated against the table's columns before it is written. Not for adding a new row — that is `data.api_append`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "data" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "row_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "column_key": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": {} }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } ] }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "table_id", "row_id", "column_key", "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "table_id": { "type": "string" }, "row_id": { "type": "string" }, "column_key": { "type": "string" }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "column_key", "row_id", "table_id", "values", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/data.set_published_columns": { "post": { "operationId": "call_data_set_published_columns", "summary": "Call data.set_published_columns", "description": "Set exactly which columns of a Data table a public Page may read — 'let the site show the venue name and city', 'stop the page reading the email column'. It replaces the whole list: nothing is published implicitly, and a column left out is hidden from every Page. Not for changing the table's data — that is `data.api_update_cell`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "data" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "published_columns": { "type": "array", "items": { "type": "string" } }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "table_id", "published_columns" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "table_id": { "type": "string" }, "published_columns": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/data.run_row_action": { "post": { "operationId": "call_data_run_row_action", "summary": "Call data.run_row_action", "description": "Press a row's button in a Data table, as a member clicking it would — 'process the Acme meeting', 'run the research button on that row'. A button is a column of type `action` (`data.api_describe` lists them); pressing it starts every automation built on its event with the row as input, and those may spend credits or send what they were built to send. It answers in two calls: without confirmation_id it proposes, names the table, button and row, and presses nothing; the same call again with that confirmation_id, on a member's own API key, presses it once. Not for adding a row — that is `data.api_append`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "data" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The table whose row button is pressed." }, "row_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The row the button is pressed on, as `data.query` returned it." }, "column_key": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The key of the table's `action` column — the button. `data.describe` lists it with `type: action` and the event it sends." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "table_id", "row_id", "column_key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "event_key": { "type": "string" }, "matched": { "type": "integer" }, "started": { "type": "integer" }, "already_started": { "type": "integer" }, "not_queued": { "type": "integer" }, "over_cap": { "type": "integer" }, "refused_row": { "type": "integer" }, "count_line": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.read": { "post": { "operationId": "call_page_read", "summary": "Call page.read", "description": "Read one page in this workspace — 'what's the state of the pricing page?', 'is the landing page live?'. It reads only. Not for a captured lead on the page — that is `page.api_read_lead`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "status": { "type": "string" }, "hostname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updated_at": { "type": "string" }, "latest_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_build": { "type": "boolean" }, "source_mode": { "type": "string" }, "pixels": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "enabled": { "type": "boolean" }, "configured": { "type": "boolean" } }, "required": [ "label", "enabled", "configured" ], "additionalProperties": false } }, "other_live_count": { "type": "integer", "minimum": 0 }, "board_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "has_build", "hostname", "latest_revision", "name", "other_live_count", "pixels", "published_at", "published_revision", "site_id", "source_mode", "status", "updated_at", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.build_status": { "post": { "operationId": "call_page_build_status", "summary": "Call page.build_status", "description": "Read where one build of a page stands — 'did the last build finish?', 'why did the build fail?' — after proving the build belongs to that page; the status comes back sanitized. Not for the page's list of builds — that is `page.api_revisions`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "build_run_id": { "type": "string", "minLength": 1 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "build_run_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "build_run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "retrying" ] }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "The rail's own failure taxonomy code." }, "message": { "type": "string", "description": "The rail's customer-facing refusal sentence — never a stack trace or an internal id." } }, "required": [ "code", "message" ], "description": "Why a `failed` build failed.", "additionalProperties": false }, { "type": "null" } ], "description": "Present only when `status` is `\"failed\"`; `null` otherwise." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "build_run_id", "failure", "revision", "site_id", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.publish": { "post": { "operationId": "call_page_publish", "summary": "Call page.publish", "description": "Propose, then confirm, putting one exact built version of a page on the public internet — 'publish the landing page', 'make the new version live'. Publishing is public, and nothing goes live until the confirmed call. Not for putting an earlier version back live — that is `page.api_rollback`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "published" ] }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "revision": { "type": "string" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "hostname": { "type": "string" }, "url": { "type": "string" }, "shared_dev_host": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "revision", "site_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.read_lead": { "post": { "operationId": "call_page_read_lead", "summary": "Call page.read_lead", "description": "Read one captured lead that belongs to a specific Page in this workspace — 'show me the lead from the webinar page', 'who filled in this form?'. It reads only. Not for the page itself — that is `page.api_read`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "lead_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "lead_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "lead_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "submitted_at": { "type": "string" }, "crm_status": { "type": "string", "enum": [ "pending", "synced", "skipped", "failed", "abandoned" ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "crm_status", "email", "fields", "lead_id", "name", "site_id", "submitted_at", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.revisions": { "post": { "operationId": "call_page_revisions", "summary": "Call page.revisions", "description": "List a page's builds, newest first, with the one currently published flagged — 'what versions of this page are there?', 'which build is live?'. It reads only. Not for one build's status — that is `page.api_build_status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "limit": { "description": "How many builds to return, newest first. Default 20, maximum 100.", "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "description": "Where to continue: pass the `next_cursor` from the previous page, with the same filters. Omit it for the first page.", "type": "string", "minLength": 1, "maxLength": 512 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "published_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "revision": { "type": "string" }, "origin": { "type": "string" }, "created_at": { "type": "string" }, "published": { "type": "boolean" }, "has_functions": { "type": "boolean" } }, "required": [ "revision", "origin", "created_at", "published", "has_functions" ], "additionalProperties": false } }, "next_cursor": { "description": "Present when there is another page: pass it back as `cursor` to read it. Absent on the last page.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "published_revision", "revisions", "site_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.rollback": { "post": { "operationId": "call_page_rollback", "summary": "Call page.rollback", "description": "Propose, then confirm, putting one exact earlier built version back on a page's live address — 'roll the live page back', 'put yesterday's version back up'. Visitors see it once confirmed. Not for publishing the newest build — that is `page.api_publish`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "revision": { "type": "string", "minLength": 1, "description": "The exact prior build to put back on the live address." }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "revision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "published" ] }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "revision": { "type": "string" }, "previous_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "hostname": { "type": "string" }, "url": { "type": "string" }, "shared_dev_host": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "revision", "site_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.assets": { "post": { "operationId": "call_page_assets", "summary": "Call page.assets", "description": "List the images and files attached to a page's own board — 'what images does this page have?', 'list the files on the site board'. No download address is issued and nothing changes. Not for the page's own state — that is `page.api_read`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "limit": { "description": "How many assets to return, newest first. Default 50, maximum 200.", "type": "integer", "minimum": 1, "maximum": 200 }, "cursor": { "description": "Where to continue: pass the `next_cursor` from the previous page, with the same filters. Omit it for the first page.", "type": "string", "minLength": 1, "maxLength": 512 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "board_item_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "storage_object_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "byte_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "uploaded_at": { "type": "string" } }, "required": [ "board_item_id", "storage_object_id", "display_name", "mime_type", "byte_size", "uploaded_at" ], "additionalProperties": false } }, "next_cursor": { "description": "Present when there is another page: pass it back as `cursor` to read it. Absent on the last page.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "assets", "board_id", "site_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.domains": { "post": { "operationId": "call_page_domains", "summary": "Call page.domains", "description": "Read every address a page answers on, each with its state and the DNS records still required — 'is my domain live yet?', 'what records do I still need?'. It reads only. Not for connecting a new domain — that is `page.api_domain_connect`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "kind": { "type": "string", "enum": [ "platform_subdomain", "custom" ] }, "state": { "type": "string", "enum": [ "waiting_dns", "validating", "active", "failed", "redirected_externally" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "note": { "type": "string" }, "state": { "type": "string" } }, "required": [ "key", "name", "note", "state" ], "additionalProperties": false } }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "routing", "certificate" ] } }, "required": [ "type", "name", "value", "purpose" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "domain_id", "hostname", "kind", "state", "steps", "records", "created_at", "updated_at" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "domains", "site_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.domain_connect": { "post": { "operationId": "call_page_domain_connect", "summary": "Call page.domain_connect", "description": "Connect a domain the customer already owns to one of their pages — 'connect mybrand.com to the landing page', 'use our own domain for this site'. It reserves the name, starts the certificate and returns the DNS records they must add; the domain is NOT live until those records resolve. Not for checking whether it is live yet — that is `page.api_domains`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string", "minLength": 1, "description": "The domain the customer already owns, e.g. `offers.example.com`." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "hostname" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "domain": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "kind": { "type": "string", "enum": [ "platform_subdomain", "custom" ] }, "state": { "type": "string", "enum": [ "waiting_dns", "validating", "active", "failed", "redirected_externally" ] } }, "required": [ "domain_id", "hostname", "kind", "state" ], "additionalProperties": false }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "routing", "certificate" ] } }, "required": [ "type", "name", "value", "purpose" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "domain", "records", "site_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.archive": { "post": { "operationId": "call_page_archive", "summary": "Call page.archive", "description": "Propose, then confirm, taking one page off the workspace's board, or putting it back with archived: false — 'archive the old promo page', 'bring back the page I archived'. It deletes nothing and is reversible in one call. Archiving a LIVE page is refused, because it would not take the page off the internet — relay that reason rather than retrying. Not for changing what visitors see — that is `page.api_publish`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "archived": { "type": "boolean" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "archived" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "archived", "restored" ] }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "site_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.set_access": { "post": { "operationId": "call_page_set_access", "summary": "Call page.set_access", "description": "Propose, then confirm, making one page of a site members-only — so only signed-in members of the workspace can open it — or public again: 'make the team page private', 'open /pricing to everyone again'. A live site rebuilds and publishes itself with the change; a draft site's change lands with its next build. It sets one page by its path, never a pattern such as '/admin/*' — relay that refusal, which says a pattern is edited in the site's source. Not for publishing a built version — that is `page.api_publish`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "access": { "type": "string", "enum": [ "members", "public" ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "path", "access" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "unchanged", "building", "publishing" ] }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "path": { "type": "string" }, "access": { "type": "string", "enum": [ "members", "public" ] }, "name": { "type": "string" }, "member_routes": { "type": "array", "items": { "type": "string" } }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "access", "path", "site_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.create_board": { "post": { "operationId": "call_automations_create_board", "summary": "Call automations.create_board", "description": "Create one empty automation board in this workspace — 'start a new automation', 'make a blank automation for lead follow-up'. It lands where the key's new work starts (Splash Pad unless a Work here project is set; file it elsewhere with `work.file`). Nothing is scheduled and nothing runs, and a retry with the same retry identity returns the same board rather than a second one. Not for writing the automation's steps — that is `automations.api_author`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "created": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "created", "name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.author": { "post": { "operationId": "call_automations_author", "summary": "Call automations.author", "description": "Propose, then confirm, one complete draft version of an existing automation board — 'add a step that emails new leads', 'rewrite this automation to wait three days first'. Confirming validates the connector bindings, builder availability, the graph and the trigger before anything is written, and the version is saved as a draft that does not run. Not for switching a version on — that is `automations.api_activate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What this automation is called, in the member's words." }, "description": { "description": "One or two plain sentences saying what it is for.", "type": "string", "maxLength": 600 }, "steps": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$", "description": "A stable key: lowercase letters, digits and underscores, starting with a letter (gather_answers); later steps read its answer as steps.." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The step's name in plain language." }, "description": { "description": "What this step does, in one sentence.", "type": "string", "maxLength": 400 }, "kind": { "default": "automated", "description": "What the step is. automated (the default, leave it off): runs an action by its implementation. ask: stops for a person or the contact, then carries on with the answer. wait: waits a set time, until a date, for something to happen, until a read says done, or for a callback. think: a model answers its instruction from the inputs it names, in the shape its JSON Schema declares. run: starts another automation of this workspace, and may wait for its answer. branch: sends the run down one of its edges by its rules. set: gives later steps the fields it names. loop: runs its body once for each item of a list, or until a test holds. code: JavaScript or Python, written when the step is set up with `automations.bind_step`. Every kind but automated and ask takes no implementation.", "type": "string", "enum": [ "automated", "approval", "code_step", "delay", "conversation", "wait_for_event", "compute", "think", "ask", "loop", "branch", "set", "wait", "run", "code" ] }, "implementation": { "description": "An automated step's action, by its catalogue key: contact.add_tag, contact.remove_tag, email.send, notify.member, opportunity.move_stage, contact.update_field, data.query, data.write, automation.call, or a connected tool's connector..; an ask step's is automation.ask. An unknown key is refused by name and nothing is saved, so never invent one.", "type": "string", "minLength": 1, "maxLength": 200 }, "params": { "description": "The step's settings, in its action's own shape: { \"tag\": \"hot\" } for contact.add_tag, { \"emailId\": \"\" } for email.send. Every action refuses a setting it does not take and names it, so ask the member rather than guessing one, and never pass settings without an implementation except on the kinds that take none. An ask step takes { \"target\": { \"kind\": \"member\" } or { \"kind\": \"role\", \"role\": \"admin\" } or { \"kind\": \"contact\" }, \"question\": \"…\", \"answerKind\": \"approve_decline\" or \"choice\" or \"text\", \"options\": [\"…\"], \"timeout\": \"P3D\" }: the timeout is required (ask the member for it), options only for choice, and a contact answers in text. Its answer is steps..outcome: approved, declined, answered or timed_out. A think step takes { \"instruction\": \"…\", \"inputs\": { \"\": \"{{ steps.. }}\" }, \"schema\": }: the schema is the answer's shape ({ \"type\": \"string\", \"enum\": [\"yes\", \"no\"] } for a decision; an object naming every field later steps read), and later steps read it at steps..answer. It reads the run only through its inputs, and may name a \"slot\": \"writing.standard\", \"writing.plus\", \"writing.max\" (the strongest writing last). To answer once for each item of a list, add \"items\": \"{{ steps.. }}\" (at most 20) and read each as {{ item }} in the inputs; the answers are steps..items[i].answer. When the work is many items and nobody waits on the answer (a nightly summary, sorting a list of replies), add \"timing\": \"batch\" and say so: the items go to the provider's batch rate, about half the usual price where the step's model has one, and the answers come back within hours rather than seconds. A wait step takes one of: { \"for\": \"P2D\" } (how long, an ISO 8601 duration, at most 90 days); { \"until\": \"2026-11-01T09:00\" } (a date-time in the workspace's zone, or one {{ … }} that gives an instant); { \"event\": { \"type\": \"tag_added\", \"tag\": \"…\" } or { \"type\": \"reply_received\" }, \"timeout\": \"P3D\" } (until that happens to the run's contact, at most 30 days); { \"poll\": { \"tool\": \"automation.call\" or \"connector..\", \"params\": { … }, \"until\": \"{{ json.status == 'done' }}\", \"every\": \"PT5M\" }, \"timeout\": \"PT1H\" }; or { \"callback\": { \"request\": { … }, \"expect\": }, \"timeout\": \"PT15M\" }. A wait that times out fails as wait_timeout, and the step's on_error decides what happens next. A run step takes { \"workflow\": \"\", \"mode\": \"wait\" or \"start\", \"input\": { … } }: wait holds this run until that one answers, read at steps..; start sets it going and carries on. A set step's settings are the fields it gives later steps ({ \"total\": \"{{ … }}\", \"label\": \"…\" }), read at steps... A branch step takes { \"rules\": [ { \"name\": \"big_order\", \"if\": \"{{ trigger.payload.total > 500 }}\" } ], \"mode\": \"first\" } and no implementation: each edge out of it names the rule it follows in output, or \"else\" for the edge taken when no rule holds; mode \"all\" takes every rule that holds. A code step takes { \"language\": \"javascript\" or \"python\", \"instruction\": \"\", \"inputs\": { \"\": \"{{ … }}\" }, \"output_schema\": }; binding it writes the code, which reads only its inputs and has no network. A browser step reads a website on this workspace's browsing list: `implementation: \"platform.browser\"` with `{\"task\":\"…\",\"startUrl\":\"https://…\",\"output\":,\"maxMinutes\":5}` (`output` when later steps read fields; up to 10 minutes). Its answer is at `stepResults..answer`. When `stepResults..outcome` is `needs_member` (a CAPTCHA, a sign-in code, a missing login, or a site off the list), follow it with an `ask` to the member quoting `stepResults..member_step`, then the same browser step again. Any setting, at any depth, reads the run's data with {{ … }} around one CEL expression. A value that is exactly one {{ … }} keeps its type (a number, a list, a map); with words around it, it is text. What an expression reads: trigger (what started the run: a webhook's body at trigger.payload., an app event's fields at trigger.event.payload.); steps. (an earlier step's answer: a table read's rows at steps..rows, each { row_id, values: { : … } }; a think's at steps..answer); json (the step just before); item and index (inside a loop); run.id and run.contactId; contact.consent.email and contact.consent.sms. Operators: + - * / %, == != < <= > >=, && || !, cond ? a : b, x in list. Functions, each called by its bare name: size(x). For text: upper(s), lower(s), trim(s), replace(s, from, to), substring(s, start, end), split(s, sep), join(list, sep), s.contains(t), s.startsWith(t), test(s, re2), extract(s, re2), format(\"%s of %s\", [a, b]). For numbers: round(x), round(x, 2), floor(x), ceil(x), abs(x), sum(list), avg(list), min(list), max(list), int(x), double(x), string(x). For lists: list.map(x, expr), list.filter(x, cond), list.exists(x, cond), first(list), last(list), sort(list), sortBy(list, \"field\"), unique(list), slice(list, from, to). For maps: has(m.field), get(m, \"a.b\", default), pick(m, keys), merge(a, b), keys(m), values(m). For dates: now(), dateAdd(d, \"P1D\"), dateDiff(a, b, \"day\"), dateFormat(d, \"MMM d, h:mm a\", \"America/Chicago\") (yyyy MM dd HH mm, and a zone; UTC when none), startOf(d, \"week\"). A value that may be missing: coalesce(trigger.payload.nickname, \"friend\") gives a default, and coalesce(trigger.payload.company, omit) leaves that key out. Examples: \"Booking {{ trigger.payload.booking_id }} for {{ trigger.payload.guests }} guests\"; { \"open\": \"{{ size(steps.read_tasks.rows) }}\" }; \"{{ join(steps.read_tasks.rows.map(r, r.values.title), ', ') }}\". An expression that cannot be read, names a step that is not before this one, or gives the wrong kind of value is refused at save with its path and its fix.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "delay": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "hours": { "type": "integer", "minimum": 0 }, "minutes": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "until": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "object", "properties": { "path": { "type": "string" }, "offset": { "type": "string" } }, "required": [ "path", "offset" ], "additionalProperties": false } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "waitForEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "tag_added", "reply_received" ] }, "tag": { "type": "string", "minLength": 1, "maxLength": 200 }, "timeoutMinutes": { "type": "integer", "minimum": 5, "maximum": 43200 } }, "required": [ "event", "timeoutMinutes" ], "additionalProperties": false }, "outputs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(?!__)" } }, "promptFirst": { "default": true, "type": "boolean" }, "retries": { "type": "integer", "minimum": 0 }, "retry": { "description": "Only when the member wants an action tried again after it fails (a service that was briefly down): { \"max\": 3, \"wait\": \"PT10S\" }, at most 5 more tries, at most 30 seconds apart. Only on an action step or a callback wait; a think retries on its own.", "type": "object", "properties": { "max": { "type": "integer", "minimum": 1, "maximum": 5 }, "wait": { "type": "string" } }, "required": [ "max" ], "additionalProperties": false }, "on_error": { "description": "What happens when this step fails. stop (the default, leave it off) ends the run there. continue carries on to the next step, which can read steps..ok (false) and steps..code. route follows this step's edge with output \"error\" instead of its usual next step: add that edge.", "type": "string", "enum": [ "stop", "continue", "route" ] }, "loop": { "description": "A loop step: \"items\" (one {{ … }} that gives the list; the body reads {{ item }} and {{ index }}) or \"repeat\" ({ \"max\": 5 } times, or { \"until\": \"{{ json.done }}\", \"max\": 10 } over each round's answer), and its \"body\": an action, its params, and \"on_error\" (\"continue\" skips a failed item).", "type": "object", "properties": { "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "repeat": { "type": "object", "properties": { "until": { "type": "string", "minLength": 1, "maxLength": 2000 }, "max": { "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "max" ], "additionalProperties": false }, "over": { "type": "string", "maxLength": 256, "pattern": "^(?:initData|state|stepResults\\.[a-z][a-z0-9_]*)(?:\\.[^\\s.{}|]+)*$" }, "until": {}, "while": {}, "concurrency": { "type": "integer", "minimum": 1 }, "onItemFailure": { "type": "string", "enum": [ "skip", "stop", "fail" ] }, "body": { "type": "object", "properties": { "implementation": { "type": "string", "minLength": 1, "maxLength": 200 }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "retries": { "type": "integer", "minimum": 0 }, "retry": { "type": "object", "properties": { "max": { "type": "integer", "minimum": 1, "maximum": 5 }, "wait": { "type": "string" } }, "required": [ "max" ], "additionalProperties": false }, "on_error": { "type": "string", "enum": [ "stop", "continue", "route" ] } }, "required": [ "implementation" ], "additionalProperties": false } }, "required": [ "body" ], "additionalProperties": false }, "sketch": { "type": "boolean", "const": true }, "compute": { "type": "object", "properties": { "task": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$" }, "payload": { "default": {}, "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 64 } }, "resumeOn": { "default": "completion", "type": "string", "enum": [ "completion" ] }, "reliability": { "type": "object", "properties": { "deadlineMs": { "type": "integer", "minimum": 1000, "maximum": 21600000 }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9{}][A-Za-z0-9_:.\\-{}]*$" } }, "required": [ "deadlineMs", "maxAttempts", "idempotencyKey" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } }, "required": [ "key", "label" ], "additionalProperties": false }, "description": "The steps, in the order they run. At most 24. An automated or ask step with no implementation is saved as a shape and refused when the automation is switched on." }, "edges": { "description": "Only when the run does not simply go through the steps in order: which step leads to which. Leave it out for a straight line; an empty list is refused.", "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "to": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "when": { "description": "Only on the two edges out of an A/B split, a step with implementation `flow.split` and params { \"percent\": 50 }: `{\"op\":\"eq\",\"left\":{\"path\":\"state.split_.arm\"},\"right\":{\"literal\":\"a\"}}` on the edge for the first share, `{\"op\":\"eq\",\"left\":{\"path\":\"state.split_.arm\"},\"right\":{\"literal\":\"b\"}}` on the other. Every other condition is a branch step's rule." }, "on": { "type": "string", "const": "failure" }, "whenLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "output": { "description": "Which outcome this edge follows. Out of a branch: the name of the rule it follows, or \"else\" for the edge taken when no rule holds. Out of an ask: approved, declined, answered or timed_out; once one edge out of an ask names one, every edge out of it does, and an outcome with no edge ends the run. \"error\": the edge a step with on_error route follows when it fails.", "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "from", "to" ], "additionalProperties": false } }, "trigger": { "description": "What fires it. Omit when the operator did not say — never invent a schedule.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "manual" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "schedule" }, "cron": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Five whitespace-separated cron fields, e.g. `0 9 * * 1`. Required for `schedule`." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "An IANA timezone name, e.g. `America/Chicago`. Required for `schedule` — ask rather than assume one." } }, "required": [ "kind", "cron", "timezone" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "app_event" }, "event_key": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Which event fires it. Required for `app_event`. `crm.tag_applied` — When a tag is added to a contact in the CRM — any tag, or only the one tag you choose. `crm.tag_removed` — When a tag is taken off a contact in the CRM. `crm.contact_created` — When a new contact is added to the CRM. `crm.contact_updated` — When a contact's own details are edited in the CRM — optionally only when their email, name or phone changes. `crm.contact_deleted` — When a contact is removed from the CRM. `crm.opportunity_opened` — When a deal is created on one of your pipelines. `crm.opportunity_closed` — When a deal is won, lost or abandoned. `crm.stage_changed` — When a deal moves from one pipeline stage to another. `appointment.booked` — When someone books a time on one of your calendars. `appointment.status_changed` — When a booking is confirmed, showed, marked a no-show, or cancelled. `invoice.paid` — When an invoice is paid in full. `payment.received` — When an order is paid — the amount and currency come with it. `email.opened` — When a contact opens an email you sent them. `email.clicked` — When a contact clicks a link in an email you sent them. `email.bounced` — When an email to a contact could not be delivered. `inbox.reply_received` — When a contact replies on any channel your inbox carries. `inbox.tag_applied` — When someone puts a tag on a conversation in the inbox. `pages.lead.captured` — When someone submits a form on one of your published pages. `contact.date_reached` — When a contact's birthday comes round — on the day, or a chosen number of days before or after, at the time you choose. `board_row.date_reached` — When a date in one of your board tables comes round — on the day, or a chosen number of days before or after, at the time you choose. `automation.sequence_enrolled` — When another automation enrols someone into this sequence — the emails and waits below start for that person." }, "changed_fields": { "description": "ONLY for `crm.contact_updated`: narrow it to the fields the operator named, e.g. `[\"phone\"]` for \"when their phone number changes\". Omit for any change to the contact. Passing it with ANY OTHER event key is REFUSED — no other event says which fields changed, so a filter on one would match nothing and the automation would silently never run. A contact field we do not store — an address, a company, a custom field — cannot be named either, so say so rather than choosing a neighbouring one.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "email", "name", "phone" ] } }, "date_field": { "description": "REQUIRED for `contact.date_reached`, and refused on every other key: WHICH stored date to watch. Only dates this product actually stores can be named — a renewal date or a CRM custom field cannot, so say so rather than choosing a neighbouring one.", "anyOf": [ { "type": "string", "enum": [ "date_of_birth" ] }, { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "column_id": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "table_id", "column_id" ], "additionalProperties": false } ] }, "offset_days": { "description": "REQUIRED for `contact.date_reached`, and refused on every other key: how many days BEFORE the date to fire. `0` is on the day, `3` is three days before. Negative is not accepted — an anniversary that has passed is not a date being reached.", "type": "integer", "minimum": 0 }, "direction": { "description": "For a date event: fire before (default) or after the date.", "type": "string", "enum": [ "before", "after" ] }, "at_local_time": { "description": "For a date event: the local time it fires, HH:MM (default 09:00).", "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "description": "An IANA timezone name, e.g. `America/Chicago`. Required for `schedule` — ask rather than assume one.", "type": "string", "minLength": 1, "maxLength": 64 }, "payload": { "description": "For a `custom.` event: its fields, each `{ name, type, required }` (type text, number, boolean, date, email or phone).", "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "type": { "type": "string", "enum": [ "text", "number", "boolean", "date", "email", "phone" ] }, "required": { "type": "boolean" } }, "required": [ "name", "type" ], "additionalProperties": false } } }, "required": [ "fields" ], "additionalProperties": false }, "pipeline_stage_ids": { "description": "ONLY for a deal event (`crm.opportunity_opened`, `crm.opportunity_closed`, `crm.stage_changed`): narrow it to the pipeline stages the operator named, e.g. the id of \"Proposal sent\" for \"when a deal reaches proposal\". Omit for any stage on any pipeline. These are the `id` values `pipeline.list` returns for the STAGES — never a GoHighLevel pipeline or stage ref, which would match nothing. Passing it with ANY OTHER event key is REFUSED — no other event says which stage it happened on, so a scope on one would match nothing and the automation would silently never run.", "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "tag": { "description": "For `crm.tag_applied`: the one tag name it waits for; omit for any tag.", "type": "string", "minLength": 1, "maxLength": 200 }, "form": { "description": "For `pages.lead.captured`: the one page form it waits for, as page.read's `forms` names it; omit for any form. A form whose `event` is set starts through that `custom.*` event instead.", "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" } }, "required": [ "kind", "event_key" ], "additionalProperties": false } ] }, "sketch_trigger": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "manual", "schedule", "webhook", "app_event" ], "description": "What will start it, before it is set up." } }, "required": [ "kind" ], "additionalProperties": false }, "review_gated": { "type": "boolean" }, "callable": { "type": "object", "properties": { "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "output": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false }, "run_queue": { "type": "string" }, "error_workflow": { "description": "Only when the member names one: the id of another automation in this workspace that runs whenever a run of this one fails. Its input names what failed, under failed: the run, the automation, the step, and why: its code and message. Leave it out on a change to keep the one already set.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id", "name", "steps" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "saved" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expected_latest_version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "display_name": { "type": "string" }, "created": { "type": "boolean" }, "status": { "type": "string", "const": "draft" }, "bound_steps": { "type": "array", "items": { "type": "string" } }, "unbound_steps": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.activate": { "post": { "operationId": "call_automations_activate", "summary": "Call automations.activate", "description": "Propose, then confirm, switching on one exact reviewed version of an automation — 'turn this automation on', 'activate the version we just reviewed'. Once confirmed, that version is the one that runs. Not for writing or changing the steps — that is `automations.api_author`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "activated" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "document_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "display_name": { "type": "string" }, "schedule_arming": { "type": "string", "enum": [ "not_a_schedule", "flag_off", "armed", "kept_paused" ] }, "is_active": { "type": "boolean" }, "changed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "display_name", "document_hash", "is_active", "schedule_arming", "state", "version", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/pages.capabilities.catalogue": { "post": { "operationId": "call_pages_capabilities_catalogue", "summary": "Call pages.capabilities.catalogue", "description": "Read the live managed capability catalogue and one workload's effective policy — 'what can this site's workload do?', 'which capabilities are granted here?'. It reads only. Not for changing a policy, grant or approval — that is `pages.api_capabilities_configure`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "pages" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "site" }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "kind", "site_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "workflow" }, "workflow_definition_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflow_definition_version_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "kind", "workflow_definition_id", "workflow_definition_version_id" ], "additionalProperties": false } ] }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "writing_tiers": { "type": "array", "items": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "leverage": { "type": "string", "enum": [ "read", "write", "high-leverage" ] }, "requires_confirmation": { "type": "boolean" }, "supports_standing_approval": { "type": "boolean" }, "writing_tiers": { "type": "array", "items": { "type": "string" } }, "managed_key_input_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "type": "array", "items": {} }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } ] } } }, "required": [ "key", "leverage", "requires_confirmation", "supports_standing_approval", "writing_tiers", "managed_key_input_schema" ], "additionalProperties": false } }, "effective": { "anyOf": [ { "type": "object", "properties": { "grant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "account_policy_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "project_policy_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "operation_keys": { "type": "array", "items": { "type": "string" } }, "allowed_tiers": { "type": "array", "items": { "type": "string" } }, "default_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "max_input_bytes": { "type": "integer", "exclusiveMinimum": 0 }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0 }, "max_search_queries": { "type": "integer", "minimum": 0 }, "max_search_results": { "type": "integer", "minimum": 0 }, "max_tool_calls": { "type": "integer", "minimum": 0 }, "max_concurrent_requests": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "max_input_bytes", "max_output_tokens", "max_search_queries", "max_search_results", "max_tool_calls", "max_concurrent_requests" ], "additionalProperties": false }, "rate_cap": { "anyOf": [ { "type": "object", "properties": { "max_requests": { "type": "integer", "exclusiveMinimum": 0 }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 2678400 }, "window_starts_at": { "type": "string" }, "window_resets_at": { "type": "string" } }, "required": [ "max_requests", "window_seconds", "window_starts_at", "window_resets_at" ], "additionalProperties": false }, { "type": "null" } ] }, "standing_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "disclosure_summary": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "standing_automation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": [ "id", "disclosure_summary", "expires_at", "standing_automation_id" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "grant_id", "account_policy_id", "project_policy_id", "operation_keys", "allowed_tiers", "default_tier", "limits", "rate_cap", "standing_approval" ], "additionalProperties": false }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "effective", "operations", "writing_tiers", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/pages.capabilities.configure": { "post": { "operationId": "call_pages_capabilities_configure", "summary": "Call pages.capabilities.configure", "description": "Propose, then confirm, one exact managed policy, grant, standing approval, workflow enrollment or revocation — 'let this site run the lead workflow', 'revoke the image search grant'. Nothing changes until the confirmed call. Not for reading what is granted today — that is `pages.api_capabilities_catalogue`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "pages" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "policy" }, "policy": { "oneOf": [ { "type": "object", "properties": { "scope_kind": { "type": "string", "const": "account" }, "workspace_id": { "type": "null" }, "project_board_id": { "type": "null" }, "policy_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "operation_keys": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "pages.ai.generate_text", "web.search", "web.read", "web.image_search", "images.acquire_remote", "images.generate", "images.iterate", "workflow.invoke", "workflow.status", "connections.call" ] } }, "allowed_tiers": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "default_tier": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "max_input_bytes": { "type": "integer", "exclusiveMinimum": 0 }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0 }, "max_search_queries": { "type": "integer", "minimum": 0 }, "max_search_results": { "type": "integer", "minimum": 0 }, "max_tool_calls": { "type": "integer", "minimum": 0 }, "max_concurrent_requests": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "max_input_bytes", "max_output_tokens", "max_search_queries", "max_search_results", "max_tool_calls", "max_concurrent_requests" ], "additionalProperties": false }, "enabled": { "type": "boolean" }, "activate": { "type": "boolean" } }, "required": [ "scope_kind", "workspace_id", "project_board_id", "policy_id", "operation_keys", "allowed_tiers", "default_tier", "limits", "enabled", "activate" ], "additionalProperties": false }, { "type": "object", "properties": { "scope_kind": { "type": "string", "const": "project" }, "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "project_board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "policy_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "operation_keys": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "pages.ai.generate_text", "web.search", "web.read", "web.image_search", "images.acquire_remote", "images.generate", "images.iterate", "workflow.invoke", "workflow.status", "connections.call" ] } }, "allowed_tiers": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "default_tier": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "max_input_bytes": { "type": "integer", "exclusiveMinimum": 0 }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0 }, "max_search_queries": { "type": "integer", "minimum": 0 }, "max_search_results": { "type": "integer", "minimum": 0 }, "max_tool_calls": { "type": "integer", "minimum": 0 }, "max_concurrent_requests": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "max_input_bytes", "max_output_tokens", "max_search_queries", "max_search_results", "max_tool_calls", "max_concurrent_requests" ], "additionalProperties": false }, "enabled": { "type": "boolean" }, "activate": { "type": "boolean" } }, "required": [ "scope_kind", "workspace_id", "project_board_id", "policy_id", "operation_keys", "allowed_tiers", "default_tier", "limits", "enabled", "activate" ], "additionalProperties": false } ] } }, "required": [ "kind", "policy" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "grant" }, "grant": { "type": "object", "properties": { "account_policy_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "project_policy_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "previous_grant_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "site" }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "target_board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "kind", "site_id", "target_board_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "workflow" }, "workflow_definition_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflow_definition_version_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "kind", "workflow_definition_id", "workflow_definition_version_id" ], "additionalProperties": false } ] }, "operation_keys": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "pages.ai.generate_text", "web.search", "web.read", "web.image_search", "images.acquire_remote", "images.generate", "images.iterate", "workflow.invoke", "workflow.status", "connections.call" ] } }, "allowed_tiers": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "default_tier": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "max_input_bytes": { "type": "integer", "exclusiveMinimum": 0 }, "max_output_tokens": { "type": "integer", "exclusiveMinimum": 0 }, "max_search_queries": { "type": "integer", "minimum": 0 }, "max_search_results": { "type": "integer", "minimum": 0 }, "max_tool_calls": { "type": "integer", "minimum": 0 }, "max_concurrent_requests": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "max_input_bytes", "max_output_tokens", "max_search_queries", "max_search_results", "max_tool_calls", "max_concurrent_requests" ], "additionalProperties": false }, "rate_cap": { "anyOf": [ { "type": "object", "properties": { "max_requests": { "type": "integer", "exclusiveMinimum": 0 }, "window_seconds": { "type": "integer", "minimum": 1, "maximum": 2678400 } }, "required": [ "max_requests", "window_seconds" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "account_policy_id", "project_policy_id", "previous_grant_id", "target", "operation_keys", "allowed_tiers", "default_tier", "limits" ], "additionalProperties": false } }, "required": [ "kind", "grant" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "standing_approval" }, "standing_approval": { "type": "object", "properties": { "grant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "disclosure_summary": { "type": "string", "minLength": 1 }, "expires_at": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "standing_automation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": [ "grant_id", "disclosure_summary", "expires_at", "standing_automation_id" ], "additionalProperties": false } }, "required": [ "kind", "standing_approval" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "grant_revoke" }, "grant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "kind", "grant_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "standing_approval_revoke" }, "standing_approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": [ "kind", "standing_approval_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "workflow_enrollment" }, "site_grant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflow_grant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "standing_automation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "site_standing_approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflow_standing_approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "previous_enrollment_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": [ "kind", "site_grant_id", "workflow_grant_id", "standing_automation_id", "site_standing_approval_id", "workflow_standing_approval_id", "previous_enrollment_id" ], "additionalProperties": false } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "configuration" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "configured", "enrollment_pending" ] }, "kind": { "type": "string", "enum": [ "policy", "grant", "standing_approval", "grant_revoke", "standing_approval_revoke", "workflow_enrollment" ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "disclosure_summary": { "type": "string" }, "policy_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "version_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "activated": { "type": "boolean" }, "grant_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "grant_saved": { "type": "boolean" }, "runtime_credential": { "type": "string", "enum": [ "ready", "not_required", "enrollment_pending" ] }, "enrollment_error_code": { "type": "string" }, "standing_approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "standing_approval": { "type": "string", "enum": [ "ready", "not_required", "pending" ] }, "standing_approval_error_code": { "type": "string" }, "enrollment_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflow_definition_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflow_definition_version_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "service_actor_user_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "service_actor_role": { "type": "string" }, "changed": { "type": "boolean" }, "standing_approvals_revoked": { "type": "integer", "minimum": 0 }, "managed_keys_revoked": { "type": "integer", "minimum": 0 }, "request_replayed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "kind", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/workflow.invoke": { "post": { "operationId": "call_workflow_invoke", "summary": "Call workflow.invoke", "description": "Run one explicitly enrolled managed automation through to its result — 'run the lead workflow now', 'send this form through the enrolment automation'. It waits for the run's terminal result. Not for checking on a run already started — that is `workflow.api_status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "workflow" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The active managed workflow enrollment to invoke at its pinned version." }, "input": { "default": {}, "description": "The workflow input object; omit it when no input is needed.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "type": "array", "items": {} }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } ] } }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/workflow.status": { "post": { "operationId": "call_workflow_status", "summary": "Call workflow.status", "description": "Read the saved status of one managed automation run — 'did that workflow finish?', 'what happened to the last run?'. It reads only. Not for starting a run — that is `workflow.api_invoke`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "workflow" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "invocationRequestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The original managed workflow invocation request whose durable status should be read." }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/connections.call": { "post": { "operationId": "call_connections_call", "summary": "Call connections.call", "description": "Make one request with a connection this site bound by name, from the site's own code and its own key — 'look up the customer in Stripe', 'add the contact to our CRM'. It sends one HTTPS request to that connection's host, signed in with its credential, which never reaches the site; GET and HEAD read, every other method changes something on the provider's side. Only a site's own managed key can call it. Not for the brand's chat — that is the member's `connections.call` in Goosy.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "connections" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name this site bound the connection under." }, "method": { "type": "string", "minLength": 1, "description": "GET, HEAD, POST, PUT, PATCH or DELETE." }, "path": { "type": "string", "minLength": 1, "description": "The path on the connection's host, beginning with one /." }, "query": { "description": "Query string parameters, name to value.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "headers": { "description": "Extra request headers; never a credential — the connection signs the request in.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "body": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "type": "array", "items": {} }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } ], "description": "The JSON body. A GET or HEAD sends none." }, "confirmation_id": { "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 256 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "completed", "reconciliation_required", "terminal_replay" ] }, "confirmation_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/desk.build_card": { "post": { "operationId": "call_desk_build_card", "summary": "Call desk.build_card", "description": "Write a small custom card for this workspace — 'build me a calculator for this', 'make a countdown to the launch' — a little self-contained page, coded from the brief you give it, rendered in a sandbox and readable at its own address. Use it when what is wanted is not one of the ordinary elements: a bespoke view, a calculator, a countdown, a table shaped a particular way. Carry the operator's own sentence into brief; it is the whole instruction the card is written from. If the card needs live data, pass every Data table it may read in data_table_ids — a table you do not pass is a table the card can never see. This runs a PAID authoring session, so it answers in two calls on every key: without confirmation_id it describes what would be built, charges nothing and returns a confirmation_id; the same call again with that confirmation_id, on a member's own API key, builds it. Not for putting the card on a desk or project — that is `work.file`, with the card_id it answers as a widget's item_id.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "desk" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What to call the card — its label on the desk." }, "brief": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What the card should show, in the member's own words." }, "data_table_ids": { "description": "Every Data table this card may read, and the only ones. Leave it out for a card that reads nothing.", "maxItems": 8, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "title", "brief" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "built", "description": "built — the card exists. (The first call answers confirmation_required: nothing was written and nothing was charged.)" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "title": { "type": "string", "description": "What the card is called." }, "card_id": { "description": "Present once built — the card's durable identity.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "revision": { "description": "Present once built — the build this card is now on.", "type": "string" }, "entry": { "description": "Bundle-relative path of the document the frame loads.", "type": "string" }, "file_count": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 }, "reads": { "description": "What this build declared it may read, and the only ones.", "type": "array", "items": { "type": "string" } }, "door_url": { "description": "Present once built — a short-lived address that renders this card. Null when one could not be signed for this environment; the card is still built. Treat it as a secret: it is a bearer capability and it expires.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "title", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.read_piece": { "post": { "operationId": "call_posts_read_piece", "summary": "Call posts.read_piece", "description": "Read where one post piece stands — 'is this post ready to send', 'what's still missing on this piece', 'when does it go out'. It returns the piece's copy, its destinations and their versions, its publish time, the steps it still needs and whether its approval was sent. It reads only and changes nothing. Not for the workspace's whole pipeline at once — that is `content.status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piece_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The piece's id, as content.create_request, content.status or schedule.read return it." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "piece_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "piece_id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "type": "string" }, "status": { "type": "string" }, "display_time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workspace's zone; every time here is UTC and renders in it." }, "source_kind": { "type": "string" }, "source_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_master_content": { "type": "boolean" }, "master_content": { "type": "string", "description": "The piece's own body copy." }, "scheduled_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The piece's own publish time, ISO 8601 UTC." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "has_copy": { "type": "boolean" }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publish_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aspect_ratio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" } }, "required": [ "platform", "has_copy", "caption", "publish_at", "aspect_ratio", "status" ], "additionalProperties": false } }, "outstanding_steps": { "type": "array", "items": { "type": "string" }, "description": "The steps this piece does not yet satisfy, in order — the same check the workspace's own board runs." }, "retracted": { "type": "boolean", "description": "The answer that wrote this piece was withdrawn; it is never ready to send." }, "ready_to_send": { "type": "boolean" }, "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Its approval request's state, or null when none was sent." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "approval_status", "display_time_zone", "format", "has_master_content", "master_content", "outstanding_steps", "piece_id", "ready_to_send", "retracted", "scheduled_for", "source_kind", "source_ref", "status", "title", "variants", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.set_schedule": { "post": { "operationId": "call_posts_set_schedule", "summary": "Call posts.set_schedule", "description": "Set or clear the time one post piece goes out — 'schedule this post for Tuesday at 9am', 'move the launch post to Friday', 'take the time off this piece'. The time is when the piece reaches its audience on every destination without a time of its own, and nobody is asked again at that moment. A time someone changed in between is refused rather than overwritten. Not for reading the piece's current time — that is `posts.api_read_piece`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piece_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The piece's id, as content.create_request, content.status or schedule.read return it." }, "scheduled_for": { "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the piece goes out, ISO 8601 with a Z or an offset; null clears the time. Pass it on both calls." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "piece_id", "scheduled_for" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "enum": [ "confirmation_required", "scheduled" ] } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "piece_id": { "type": "string" }, "scheduled_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The publish time this call sets (or set), ISO 8601 UTC." }, "previous_scheduled_for": { "description": "The piece's publish time when the confirmation was issued.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.plan_context": { "post": { "operationId": "call_posts_plan_context", "summary": "Call posts.plan_context", "description": "Read what a posting plan has to work with — 'what slots are open this week', 'which finished videos could we post from', 'where can a carousel go'. It returns the workspace's open cadence slots over the next days (and whether each is already filled), the finished videos in its library with the date a slot binds each to, the destinations a piece of the chosen format may go to, and the zone every time renders in. It reads only and changes nothing. Not for one piece's own state — that is `posts.api_read_piece`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "piece_format": { "description": "Which format's destination catalogue to return. Omit for `posts` — carousels and single posts, the common case. Only pass another when the brief is explicitly about stories, shorts/clips or long form.", "anyOf": [ { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ] }, { "type": "null" } ] }, "days_ahead": { "description": "How many days of open cadence slots to read, from now. Omit for 7 (\"this week\"). Raise it only when the brief names a longer span.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 60 }, { "type": "null" } ] }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "display_time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workspace's zone; every time here is UTC and renders in it." }, "open_slots": { "type": "array", "items": { "type": "object", "properties": { "slot_id": { "type": "string" }, "destination": { "type": "string" }, "publish_at": { "type": "string" }, "status": { "type": "string" }, "filled": { "type": "boolean", "description": "Something is already bound to this slot." } }, "required": [ "slot_id", "destination", "publish_at", "status", "filled" ], "additionalProperties": false } }, "finals": { "type": "array", "items": { "type": "object", "properties": { "source_ref": { "type": "string", "description": "The finished video's id." }, "title": { "type": "string" }, "status": { "type": "string" }, "bound_publish_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When a cadence slot has it going out, or null." } }, "required": [ "source_ref", "title", "status", "bound_publish_at" ], "additionalProperties": false } }, "electable_platforms": { "type": "array", "items": { "type": "string" }, "description": "The destinations a piece of this format may be put on." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "display_time_zone", "electable_platforms", "finals", "open_slots", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.create_pieces": { "post": { "operationId": "call_posts_create_pieces", "summary": "Call posts.create_pieces", "description": "Create every post a brief calls for, in one call — 'make this week's posts from Tuesday's episode', 'create three posts for the launch'. Each piece is created with whatever the request already settles — what it is built from, where it goes, its own copy, its time — and gets its board, so a complete request needs no further calls beyond each destination's version. Read posts.plan_context first so slot ids, library ids and destination names are real. It creates drafts only: nothing is published or sent for approval. Not for reading where one piece stands afterwards — that is `posts.api_read_piece`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pieces": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "What the operator would call this piece. Short and human — it labels the tile on their grid." }, "piece_format": { "description": "Omit for `posts`.", "anyOf": [ { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ] }, { "type": "null" } ] }, "schedule_slot_id": { "description": "The open cadence slot from posts.plan_context this piece fills. The slot supplies the destinations AND the time, so passing it means you do not pass `platforms` or `scheduled_for` at all. Omit it for a piece the cadence has no slot for.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platforms": { "description": "Where this piece publishes. Omit when `schedule_slot_id` is set — the slot's own defaults are the operator's rhythm and restating them is what drifts. Pass ONLY values posts.plan_context listed as electable; anything else is refused.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "master_content": { "description": "The piece's own copy — the canonical version every destination's variant is shaped from. Write it here when the brief gives you enough to; otherwise omit and fill it later with posts.fill_step.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_kind": { "description": "What this piece is built from. Use `video_unit` with the id from posts.plan_context's finals list when the brief names an episode. `scratch` (the default) means written in the flow and takes NO source_ref.", "anyOf": [ { "type": "string", "enum": [ "video_unit", "image", "document", "scratch" ] }, { "type": "null" } ] }, "source_ref": { "description": "The id of the final named by `source_kind`. Required for every kind but `scratch`, and forbidden for `scratch`.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_for": { "description": "When this piece goes out: the operator's LOCAL date and time as `YYYY-MM-DDTHH:MM`, with no offset and no `Z` — the date from the `calendar` posts.plan_context returned, the time as they said it. The server converts it in `displayTimeZone`, so never convert it or add an offset yourself. Omit when `schedule_slot_id` is set. Pass it whenever the operator named a day or time, and never leave a named time out.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false }, "description": "Every piece the brief asks for, in ONE call. A week of posts is one call, not one call per post." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "pieces" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "created": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "description": "The piece's position in the request, from 0." }, "piece_id": { "type": "string" }, "run_id": { "type": "string", "description": "The piece's workflow run." } }, "required": [ "index", "piece_id", "run_id" ], "additionalProperties": false } }, "refused": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "index", "code", "message" ], "additionalProperties": false } }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without running anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "created", "refused", "replayed", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.fill_step": { "post": { "operationId": "call_posts_fill_step", "summary": "Call posts.fill_step", "description": "Write what a post is built from, its name and its own copy — 'here's what this post should say', 'this post is built from Tuesday's episode', 'rename this post'. Its copy is what every destination's version is shaped from, so write it before each destination's version. It saves the draft only; nothing is published or sent. Not for one destination's own version — that is `posts.api_save_variants`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piece_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The piece's id, as posts.create_pieces, content.create_request, content.status or schedule.read return it." }, "title": { "description": "Rename the piece.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_kind": { "description": "Step 1 — what this piece is built from. Moves as a PAIR with source_ref: `scratch` takes none, every other kind requires one.", "anyOf": [ { "type": "string", "enum": [ "video_unit", "image", "document", "scratch" ] }, { "type": "null" } ] }, "source_ref": { "description": "The id of the final named by source_kind.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "master_content": { "description": "The piece's own copy — the canonical version every destination's version is shaped from.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "piece_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "piece_id": { "type": "string" }, "applied": { "type": "array", "items": { "type": "string" }, "description": "What was saved on the piece: title, source, master_content." }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without running anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "applied", "piece_id", "replayed", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/knowledge_source.list": { "post": { "operationId": "call_knowledge_source_list", "summary": "Call knowledge_source.list", "description": "See this workspace's knowledge sources — 'what sources do we have', 'is our blog already added', 'which pages did you suggest from our site'. List this workspace's knowledge sources — name, kind, the link or handle each points at, when it was last ingested, whether it is switched on and its status (ready, processing, paused, or suggested: a page Goosy proposed from the website that was never read) — plus the kinds knowledge_source.add accepts. Paused and suggested sources are listed only with include_disabled. Call this first when the operator talks about a source without naming an id. Not for searching what the sources say — that is `knowledge.search`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "knowledge_source" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "include_disabled": { "description": "True to include the sources that are switched off: paused ones and suggestions (pages Goosy proposed from the website that were never read). Leave unset for the ones in use.", "type": "boolean" }, "limit": { "description": "How many sources to return, at most 100.", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string" }, "display_name": { "type": "string" }, "reference": { "type": "string" }, "ingestion_cadence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_ingested_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ready", "processing", "paused", "suggested" ] }, "created_at": { "type": "string" } }, "required": [ "source_id", "kind", "display_name", "reference", "ingestion_cadence", "last_ingested_at", "enabled", "status", "created_at" ], "additionalProperties": false } }, "total_count": { "type": "integer", "minimum": 0 }, "enabled_count": { "type": "integer", "minimum": 0 }, "accepted_kinds": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "accepted_kinds", "enabled_count", "sources", "total_count", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/knowledge_source.add": { "post": { "operationId": "call_knowledge_source_add", "summary": "Call knowledge_source.add", "description": "Bring a new knowledge source into this workspace's brand knowledge base — 'add our blog as a source', 'ingest this competitor's site', 'keep this decision for everyone', 'remember this for the team', 'put what we agreed in the knowledge base'. Add a knowledge source to this workspace's brand knowledge base — a link, feed, YouTube channel, competitor handle, subreddit, an already-uploaded file, or a note: something the member asks you to save, remember or share with the team from this conversation, which every member's knowledge.search then finds. A member's chats are private to them, so a note is how a decision reaches the team; write it only when the member asks for it, never on your own. Reading a source or a note costs the workspace credits. Calling it raises the approval card showing what would be added, which is the operator's confirmation, so it can still be refused after you call it. Never say a source was added unless the result says so. Report the outcome from the result's status field, never from ingested: status 'ingested' means the source was read into the knowledge base just now; status 'catalogued' means it is saved but NOT read yet, so never claim the knowledge base already answers from it; status 'already_live' means it was ALREADY saved and read, so say it is already working and nothing needed doing — do not describe it as unread. Not for a fact about the brand itself that the member tells you (an offer, a location, a dated plan with no ask to save it for the team), which is `brand_kit.suggest`; not for reading one page right now without saving it — that is `web.read`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "knowledge_source" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "file_upload", "url", "rss_feed", "competitor_handle", "subreddit", "youtube_channel", "note" ], "description": "What this source is. Use 'note' for something the member asked you to save from this conversation, 'url' for a web page, 'youtube_channel' for a YouTube channel or video, 'rss_feed' for a feed, 'competitor_handle' or 'subreddit' for a monitored handle, 'file_upload' for a file already uploaded on the Knowledge screen." }, "display_name": { "type": "string", "minLength": 2, "description": "What the operator should see this source called, at least 2 characters. For a note, a short title naming the decision." }, "reference": { "description": "The link, handle or filename this source points at, at least 2 characters. Never invent one — take it from the operator. Leave it out for a note.", "type": "string", "minLength": 2 }, "text": { "description": "For a note only: what to save, written from the conversation as plain sentences a colleague can read without it — the decision, its reasons and today's date, in the member's own facts. Never add a fact the conversation does not hold.", "type": "string", "minLength": 2 }, "ingestion_cadence": { "description": "How often to re-read the source. Leave it out unless the member says how often: a web page then re-reads weekly, so its answers stay current.", "type": "string", "enum": [ "one_shot", "weekly", "on_demand" ] }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "kind", "display_name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "source_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": [ "ingested", "catalogued", "already_live" ] }, "ingested": { "type": "boolean" }, "chunk_count": { "type": "integer", "minimum": 0 }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/knowledge_source.dismiss": { "post": { "operationId": "call_knowledge_source_dismiss", "summary": "Call knowledge_source.dismiss", "description": "Dismiss a source Goosy suggested from the website so it stops being offered — 'get rid of those suggested pages', 'dismiss the suggestions from our site', 'we don't need that suggested link'. A suggestion is a page the website crawl proposed that nobody switched on and nothing read: its status is 'suggested' in knowledge_source.list. Dismissing hides it from the source list and the crawl never offers it again; it removes nothing from the knowledge base, costs nothing, and adding the page as a source later brings it back. Call it once per suggestion. Never say a suggestion was dismissed unless the result says so. Not for a source that is already read or switched on — taking that out of the knowledge base is `knowledge_source.remove`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "knowledge_source" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The suggestion, as a UUID: a source whose status is 'suggested' in knowledge_source.list (call it with include_disabled true). Never invent one." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "source_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "source_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "display_name": { "type": "string" }, "dismissed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "dismissed", "display_name", "source_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/knowledge_source.remove": { "post": { "operationId": "call_knowledge_source_remove", "summary": "Call knowledge_source.remove", "description": "Remove a knowledge source for good — 'delete that source', 'remove the old pricing page from our knowledge', 'take that competitor's site out of the knowledge base entirely'. It deletes the source and expires every passage it contributed, so no agent in this workspace retrieves from it again; this cannot be undone, and adding it back reads it afresh as a new source. Calling it raises the approval card showing the source's name and what it points at, which is the operator's confirmation, so call it on the ask; it can still be refused after you call it. Never say a source was removed unless the result says so. Pass the id of the source the operator named, from knowledge_source.list. Not for switching a source off while keeping it — that is `knowledge_source.disable`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "knowledge_source" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The source, as a UUID. Take it from knowledge_source.list or from the conversation's context — never invent one." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "source_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "source_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "display_name": { "type": "string" }, "removed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.elect_platforms": { "post": { "operationId": "call_posts_elect_platforms", "summary": "Call posts.elect_platforms", "description": "Add destinations to a post — 'also post this to LinkedIn', 'put this one on Instagram too'. Each added destination gets an empty version of its own, so write and save that version afterwards or the piece is not ready to send. A destination already on the piece, or one the piece's format does not take, is refused and named. It adds only: dropping a destination is done in the product. Not for writing a destination's copy — that is `posts.api_save_variants`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piece_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The piece's id, as posts.create_pieces, content.create_request, content.status or schedule.read return it." }, "elect": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Destinations to ADD, as posts.plan_context lists them electable for this piece's format." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "elect", "piece_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "piece_id": { "type": "string" }, "elected": { "type": "array", "items": { "type": "string" } }, "refused": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "platform", "code", "message" ], "additionalProperties": false } }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without running anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "elected", "piece_id", "refused", "replayed", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.save_variants": { "post": { "operationId": "call_posts_save_variants", "summary": "Call posts.save_variants", "description": "Save the version written for each destination of a post — 'save these captions for Instagram and LinkedIn', 'here's the LinkedIn version of this post'. It stores the words you send; it writes none itself. A destination must already be on the piece, each version must carry its words, and a destination that already published refuses, because its copy is the record of what went out. It saves the draft only; nothing is published. Not for the piece's own copy — that is `posts.api_fill_step`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piece_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The piece's id, as posts.create_pieces, content.create_request, content.status or schedule.read return it." }, "variants": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "The destination this version is for. Must already be elected." }, "caption": { "description": "This destination's version of the copy — what actually posts there.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "description": "The longer body, for destinations that have one (a YouTube description, a Google Business post). Omit where the destination only has a caption.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publish_at": { "description": "This destination's OWN time, ISO 8601 UTC — a per-platform offset from the piece's anchor. Omit unless the brief asked for one; the piece's own time covers every destination that has none.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aspect_ratio": { "description": "Override the managed default aspect for this destination. Omit unless the operator asked — the default is the managed configuration and is nearly always right.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hashtags": { "description": "The tags going out with THIS destination's version. Write them WITHOUT the leading # — the surface adds it, so a stored one doubles it. One word each, no spaces.", "anyOf": [ { "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^#?[^\\s#@]+$" } }, { "type": "null" } ] }, "alt_text": { "description": "What the creative SHOWS, for a reader who cannot see it — the subject, what they are doing, the setting. Describe the image, never repeat the caption.", "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "first_comment": { "description": "The comment posted immediately behind the piece, where the destination has the convention. Omit on destinations that do not.", "anyOf": [ { "type": "string", "maxLength": 2200 }, { "type": "null" } ] }, "location_label": { "description": "The place this post is tagged at, as a human label (\"Northwind Trading Co. · Portland, OR\"). Never invent one the operator has not given you.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "tagged_handles": { "description": "The accounts tagged in this destination's version, WITHOUT the leading @. Only accounts the operator named — a tagged account is a claim about someone else.", "anyOf": [ { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^@?[^\\s@]+$" } }, { "type": "null" } ] }, "story": { "description": "Only on a stories piece: every frame of this destination's story, in order, plus when it expires, the highlight it is saved to and who may reply. Including this REPLACES the whole rail.", "anyOf": [ { "type": "object", "properties": { "frames": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "text_sticker": { "description": "The white pill laid over this frame's picture. A short line, not a caption — omit it where the picture speaks for itself.", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "link_sticker_url": { "description": "Where this frame's link sticker sends a viewer. Only a destination the operator named.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "link_sticker_label": { "description": "The words ON the link pill (\"See the menu\"). Ignored without link_sticker_url — a label with no destination is a pill that goes nowhere.", "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "music_label": { "description": "The track as the platform NAMES it (\"Golden Hour · JVKE\"). Only a track the operator picked — never one you chose for them.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "alt_text": { "description": "What THIS frame's picture shows, for a reader who cannot see it. Per frame — three frames are three different pictures.", "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "poll": { "description": "The poll sticker on this frame. A question with two to four options; anything less is a question, not a poll.", "anyOf": [ { "type": "object", "properties": { "question": { "type": "string", "maxLength": 200 }, "options": { "minItems": 2, "maxItems": 4, "type": "array", "items": { "type": "string", "maxLength": 60 } } }, "required": [ "question", "options" ], "additionalProperties": false }, { "type": "null" } ] }, "mention_handles": { "description": "Accounts @-mentioned ON this frame, WITHOUT the leading @ — the surface adds it. Only accounts the operator named.", "anyOf": [ { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^@?[^\\s@]+$" } }, { "type": "null" } ] }, "duration_seconds": { "description": "How long this frame sits on screen. Omit for the platforms' own 5-second still.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 60 }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "EVERY frame of this story, in order — the first entry is the frame a viewer sees first. This REPLACES the whole rail: any frame you do not list is removed." }, "expires_at": { "description": "When the story stops being visible, ISO 8601 UTC. Normally 24 hours after it posts; omit unless the operator said otherwise.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highlight_name": { "description": "The highlight the story is saved into after it expires. Only one the operator named.", "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "replies_mode": { "description": "WHO MAY REPLY to the story. Omit to leave the account's own default — never guess it.", "anyOf": [ { "type": "string", "enum": [ "everyone", "followers", "off" ] }, { "type": "null" } ] } }, "required": [ "frames" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "platform" ], "additionalProperties": false }, "description": "Every destination's version, in ONE call. Each one must carry the words — a destination with only its name on it is refused, because there is nothing to put on the piece." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "piece_id", "variants" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "piece_id": { "type": "string" }, "saved": { "type": "array", "items": { "type": "string" } }, "refused": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "platform", "code", "message" ], "additionalProperties": false } }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without running anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "piece_id", "refused", "replayed", "saved", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.add_take": { "post": { "operationId": "call_posts_add_take", "summary": "Call posts.add_take", "description": "Put a film already recorded onto a story that was waiting for one — 'use this clip for that story', 'attach my recording to this story'. The story stops waiting and its words are written over the film by a drafting run, which is model work charged to the workspace. A story that already has its take is left as it is. Not for trimming the film or changing its look: that is done in Videos, and no verb here does it. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "set_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The week the story is in." }, "piece_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The story waiting on a take." }, "video_unit_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The film they recorded or uploaded." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "piece_id", "set_id", "video_unit_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "bound" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "piece_id": { "type": "string" }, "drafting": { "type": "boolean", "description": "True when the story's words are now being written over the film; false when it already had its take." }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without running anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.keep_idea": { "post": { "operationId": "call_posts_keep_idea", "summary": "Call posts.keep_idea", "description": "Keep one of the week's post ideas for drafting, or set it aside — 'keep this idea', 'skip that one'. Only kept ideas are drafted when the week is drafted, so say how many are kept afterwards. Name the idea by its own key, never by its position in the list. A week that changed while this ran is refused rather than overwritten. Not for creating a post directly — that is `posts.api_create_pieces`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "set_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The week the idea is in." }, "idea_key": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which moment of the week — the idea's own key, like `m2`." }, "kept": { "type": "boolean", "description": "True to keep it for drafting, false to set it aside." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "idea_key", "kept", "set_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "set_id": { "type": "string" }, "idea_key": { "type": "string" }, "kept": { "type": "boolean" }, "kept_count": { "type": "integer", "minimum": 0, "description": "How many of the week's ideas are kept for drafting now." }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without running anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "idea_key", "kept", "kept_count", "replayed", "set_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/posts.submit_for_approval": { "post": { "operationId": "call_posts_submit_for_approval", "summary": "Call posts.submit_for_approval", "description": "Send a finished post for approval — 'send this post for approval', 'submit this for review'. Read it with posts.read_piece first: a piece with steps still outstanding, no destinations, or withdrawn content is refused, and the refusal names why. This submits only; the approval itself is always a person's, in Reviews or on the piece, and nothing goes out without that approval. Not for setting when it goes out — that is `posts.set_schedule`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "posts" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piece_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The piece's id, as posts.create_pieces, content.create_request, content.status or schedule.read return it." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "piece_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "submitted" }, "piece_id": { "type": "string" }, "run_id": { "type": "string", "description": "The piece's workflow run." }, "approval_surface": { "type": "string", "enum": [ "queue", "inline" ], "description": "Where the approval now waits: the Reviews queue when a sign-off is configured, otherwise on the piece itself." }, "requires_signoff": { "type": "boolean" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without running anything again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "approval_surface", "piece_id", "replayed", "requires_signoff", "run_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.list_footage": { "post": { "operationId": "call_videos_list_footage", "summary": "Call videos.list_footage", "description": "'what footage have we already uploaded', 'do we have any clips of this already' — list the footage already uploaded to this workspace: each file's id, name, length, when it landed, and whether a video already uses it. It changes nothing. Not for what a new video can be filed into — that is `videos.creation_context`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "footage": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration_s": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "uploaded_at": { "type": "string" }, "status": { "type": "string" }, "already_used": { "type": "boolean" }, "used_by_video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "used_by_video_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "filename", "duration_s", "uploaded_at", "status" ], "additionalProperties": false } }, "footage_count": { "type": "integer", "minimum": 0 }, "more_footage": { "type": "boolean" }, "unused_count": { "type": "integer", "minimum": 0 }, "partial_read": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "footage", "footage_count", "more_footage", "partial_read", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.creation_context": { "post": { "operationId": "call_videos_creation_context", "summary": "Call videos.creation_context", "description": "'what can I start a new video from', 'which slots are open for a new video' — read what a new video can be started on and filed into: the workspace's enabled production profiles and its open cadence slots in the next few weeks, each with its id. It changes nothing. Not for footage already uploaded — that is `videos.list_footage`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "production_profiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "profile_key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "profile_key", "label", "description" ], "additionalProperties": false } }, "open_slots": { "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "destination": { "type": "string" }, "publish_at": { "type": "string" }, "required_asset_type": { "type": "string" } }, "required": [ "id", "destination", "publish_at", "required_asset_type" ], "additionalProperties": false } }, "more_open_slots": { "type": "boolean" }, "slot_window_days": { "type": "integer" }, "partial_reads": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "more_open_slots", "open_slots", "partial_reads", "production_profiles", "slot_window_days", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.read_edit": { "post": { "operationId": "call_videos_read_edit", "summary": "Call videos.read_edit", "description": "'what did you change in this edit', 'show me the edit log' — read back what the edit did to one video: every change as a plain sentence with its id, how long it runs now, the titles, the pictures, and the one line said about watching it back. If it answers edited: false, nobody has edited that video yet. It changes nothing. Not for making an edit — that is `videos.plan_edit`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The video's id, as given in this conversation." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "video_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "video_id": { "type": "string" }, "edited": { "type": "boolean" }, "log": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The log line's id — what `videos.undo_edit` takes." }, "sentence": { "type": "string", "description": "The plain past-tense sentence a person reads under the player." }, "kind": { "type": "string", "enum": [ "hook_tightened", "pause_dropped", "captions_on", "insert_placed", "music_bed_laid", "scene_shortened", "transition_changed", "frame_moved", "put_on_screen", "hook_moved", "ending_looped", "graded", "fillers_cut", "retakes_cut", "studio_sound_on", "words_cut", "take_not_heard" ] }, "scene_id": { "anyOf": [ { "type": "string", "minLength": 1, "description": "The scene's id, as given in the storyboard." }, { "type": "null" } ], "description": "The scene's id, as given in the storyboard." }, "undoable": { "type": "boolean" } }, "required": [ "id", "sentence", "kind", "scene_id", "undoable" ], "additionalProperties": false } }, "titles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "picked": { "type": "boolean" } }, "required": [ "id", "text", "picked" ], "additionalProperties": false } }, "thumbnails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "note": { "type": "string" }, "picked": { "type": "boolean" }, "drawn": { "type": "boolean" } }, "required": [ "id", "note", "picked", "drawn" ], "additionalProperties": false } }, "seconds": { "type": "integer" }, "clock": { "type": "string" }, "judge_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "waiting_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "step": { "type": "string", "enum": [ "idea", "writing", "storyboarded", "needs_filming", "edited", "ready", "scheduled", "live" ] }, "open_at": { "type": "string", "description": "Where the person watches it." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "clock", "edited", "judge_line", "log", "open_at", "seconds", "step", "thumbnails", "titles", "video_id", "waiting_on", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.write_script": { "post": { "operationId": "call_videos_write_script", "summary": "Call videos.write_script", "description": "'write the script for this video', 'rewrite the script to be more casual' — write one video's script from its plan, or rewrite it under one direction you pass. The answer carries the chapters and any facts the script still needs. This runs a PAID writing turn: on a member's own key it writes in one call; on a key with no member behind it the first call describes what would be written, charges nothing and returns a confirmation id, and the second, carrying that id back, is what writes it. Not for drawing the scenes — that is `videos.draw_storyboard`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The video's id, as given in this conversation." }, "direction": { "description": "The direction for a fresh draft from the plan, in the person's own words. Leave it out for the first pass.", "type": "string", "minLength": 1, "maxLength": 2000 }, "confirmation_id": { "description": "Only when a first call answered confirmation_required: send that id back, unchanged, to run the recorded request. On your own member key the first call already runs, and there is no id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "video_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "video_id": { "type": "string" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "name": { "type": "string" }, "text": { "type": "string" }, "seconds": { "type": "integer" }, "made_by": { "type": "string", "enum": [ "you", "goosy" ] } }, "required": [ "number", "name", "text", "seconds", "made_by" ], "additionalProperties": false } }, "words": { "type": "integer", "description": "How long the script runs, in words." }, "length_words": { "type": "string" }, "step": { "type": "string", "enum": [ "idea", "writing", "storyboarded", "needs_filming", "edited", "ready", "scheduled", "live" ] }, "open_at": { "type": "string", "description": "Where the person reads it." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "ask": { "type": "string", "description": "The question, as the person reads it." }, "why": { "type": "string", "description": "Why the script needs it." }, "example": { "type": "string", "description": "One example answer." } }, "required": [ "key", "ask", "why", "example" ], "additionalProperties": false }, "description": "Facts Goosy needs and does not have. Ask the person these AS YOUR NEXT TURN, in your own words, in one message. Never answer one yourself and never guess: a made-up name, number or place ships in the finished video, and the video will not go down while a blank stands." }, "questions_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Say this to the person, in your own words, INSTEAD of asking anything — the questions did not save. Never ask a question from `questions` in the same turn you say this." }, "state": { "type": "string", "enum": [ "confirmation_required", "written", "in_flight" ], "description": "written — the script is written and below; in_flight — it is still running: nothing failed, do not send it again, follow job_id with jobs.read; confirmation_required — a key with no member behind it asked first: nothing ran and nothing was charged." }, "job_id": { "description": "The job's handle. Read its status with `jobs.read` (REST: POST /api/v1/tools/jobs.read) until it says succeeded or failed.", "type": "string" }, "confirmation_id": { "description": "Present only while confirmation is required.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "description": "How long that confirmation stays usable.", "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "description": "Present only while confirmation is required — what will run, in one sentence, for a person to approve.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.draw_storyboard": { "post": { "operationId": "call_videos_draw_storyboard", "summary": "Call videos.draw_storyboard", "description": "'storyboard this video', 'draw out the scenes for this script' — draw one video's storyboard from its script: every scene and its complete sheet. It does not draw the pictures. This runs a PAID writing turn: on a member's own key it draws in one call; on a key with no member behind it the first call describes what would be drawn, charges nothing and returns a confirmation id, and the second, carrying that id back, is what draws it. Not for writing the script — that is `videos.write_script`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The video's id, as given in this conversation." }, "wants": { "description": "Anything the person said they want to see — a shot, a place, a thing on the desk.", "type": "string", "minLength": 1, "maxLength": 2000 }, "confirmation_id": { "description": "Only when a first call answered confirmation_required: send that id back, unchanged, to run the recorded request. On your own member key the first call already runs, and there is no id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "video_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "video_id": { "type": "string" }, "scenes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "name": { "type": "string" }, "seconds": { "type": "integer" }, "at": { "type": "string" }, "source": { "type": "string", "enum": [ "you", "goosy", "screen" ] }, "source_word": { "type": "string" }, "sheet": { "type": "object", "properties": { "said": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "on_screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "moves": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sound": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timing": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "why": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "said", "on_screen", "moves", "sound", "captions", "voice", "timing", "layout", "why" ], "additionalProperties": false }, "insert": { "anyOf": [ { "type": "object", "properties": { "line": { "type": "string" }, "attribution": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line", "attribution" ], "additionalProperties": false }, { "type": "null" } ] }, "drawn": { "type": "boolean" } }, "required": [ "id", "number", "name", "seconds", "at", "source", "source_word", "sheet", "insert", "drawn" ], "additionalProperties": false } }, "length": { "type": "string" }, "step": { "type": "string", "enum": [ "idea", "writing", "storyboarded", "needs_filming", "edited", "ready", "scheduled", "live" ] }, "needs_filming": { "type": "boolean" }, "look": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "look_note": { "type": "string" }, "open_at": { "type": "string" }, "state": { "type": "string", "enum": [ "confirmation_required", "drawn", "in_flight" ], "description": "drawn — the storyboard is drawn and below; in_flight — it is still running: nothing failed, do not send it again, follow job_id with jobs.read; confirmation_required — a key with no member behind it asked first: nothing ran and nothing was charged." }, "job_id": { "description": "The job's handle. Read its status with `jobs.read` (REST: POST /api/v1/tools/jobs.read) until it says succeeded or failed.", "type": "string" }, "confirmation_id": { "description": "Present only while confirmation is required.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "description": "How long that confirmation stays usable.", "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "description": "Present only while confirmation is required — what will run, in one sentence, for a person to approve.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.plan_edit": { "post": { "operationId": "call_videos_plan_edit", "summary": "Call videos.plan_edit", "description": "'edit this video', 'make it tighter', 'cut scene three shorter' — edit one video, optionally under a direction or for one scene, and return the log of what changed — or, if the edit is still running when this answers, state in_flight and a job_id to follow with `jobs.read` (do not send it again). A retry carrying the same idempotency_key is the same edit. This runs a PAID editing turn: on a member's own key it edits in one call; on a key with no member behind it the first call describes the edit, charges nothing and returns a confirmation id, and the second, carrying that id back, is what edits it. Not for reading an edit already made — that is `videos.read_edit`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The video's id, as given in this conversation." }, "direction": { "description": "What to change, in the person's own words. Leave it out for Goosy's first edit.", "type": "string", "minLength": 1, "maxLength": 2000 }, "scene_id": { "description": "ONE scene, when the person asked about one scene rather than the whole video.", "type": "string", "minLength": 1 }, "confirmation_id": { "description": "Only when a first call answered confirmation_required: send that id back, unchanged, to run the recorded request. On your own member key the first call already runs, and there is no id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "video_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "video_id": { "type": "string" }, "log": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The log line's id — what `videos.undo_edit` takes." }, "sentence": { "type": "string", "description": "The plain past-tense sentence a person reads under the player." }, "kind": { "type": "string", "enum": [ "hook_tightened", "pause_dropped", "captions_on", "insert_placed", "music_bed_laid", "scene_shortened", "transition_changed", "frame_moved", "put_on_screen", "hook_moved", "ending_looped", "graded", "fillers_cut", "retakes_cut", "studio_sound_on", "words_cut", "take_not_heard" ] }, "scene_id": { "anyOf": [ { "type": "string", "minLength": 1, "description": "The scene's id, as given in the storyboard." }, { "type": "null" } ], "description": "The scene's id, as given in the storyboard." }, "undoable": { "type": "boolean" } }, "required": [ "id", "sentence", "kind", "scene_id", "undoable" ], "additionalProperties": false } }, "titles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "picked": { "type": "boolean" } }, "required": [ "id", "text", "picked" ], "additionalProperties": false } }, "seconds": { "type": "integer" }, "clock": { "type": "string" }, "honest_time": { "type": "string" }, "step": { "type": "string", "enum": [ "idea", "writing", "storyboarded", "needs_filming", "edited", "ready", "scheduled", "live" ] }, "open_at": { "type": "string", "description": "Where the person watches it." }, "state": { "type": "string", "enum": [ "confirmation_required", "edited", "in_flight" ], "description": "edited — the edit is made and its log is below; in_flight — it is still running: nothing failed, do not send it again, follow job_id with jobs.read; confirmation_required — a key with no member behind it asked first: nothing ran and nothing was charged." }, "job_id": { "description": "The job's handle. Read its status with `jobs.read` (REST: POST /api/v1/tools/jobs.read) until it says succeeded or failed.", "type": "string" }, "confirmation_id": { "description": "Present only while confirmation is required.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "description": "How long that confirmation stays usable.", "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "description": "Present only while confirmation is required — what will run, in one sentence, for a person to approve.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.generate_clip": { "post": { "operationId": "call_videos_generate_clip", "summary": "Call videos.generate_clip", "description": "'generate a clip for this scene', 'make this scene since we don't have real footage' — start a made clip for one storyboard scene when nothing real will do, and return its job handle. The clip is NOT ready when this answers; follow its job_id with `jobs.read`. A retry carrying the same idempotency_key returns the same clip, never a second one. This is PAID generation and needs the key holder to be a workspace admin: on a member's own key it starts in one call; on a key with no member behind it the first call describes the clip, charges nothing and returns a confirmation id, and the second, carrying that id back, is what starts it. Not for drawing the whole storyboard — that is `videos.draw_storyboard`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The video's id, as given in this conversation." }, "scene_id": { "type": "string", "minLength": 1, "description": "The scene's id, as given in the storyboard." }, "shows": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the clip should show, in the scene's own words." }, "seconds": { "default": 5, "description": "How long the clip runs inside the scene.", "type": "integer", "minimum": 1, "maximum": 15 }, "confirmation_id": { "description": "Only when a first call answered confirmation_required: send that id back, unchanged, to run the recorded request. On your own member key the first call already runs, and there is no id.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "scene_id", "shows", "video_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "video_id": { "type": "string" }, "scene_id": { "type": "string" }, "seconds": { "type": "integer" }, "marker": { "type": "string" }, "open_at": { "type": "string" }, "state": { "type": "string", "enum": [ "confirmation_required", "started" ], "description": "started — the clip is being made; job_id is its handle and it is not ready yet; confirmation_required — a key with no member behind it asked first: nothing ran and nothing was charged." }, "job_id": { "description": "The job's handle. Read its status with `jobs.read` (REST: POST /api/v1/tools/jobs.read) until it says succeeded or failed.", "type": "string" }, "confirmation_id": { "description": "Present only while confirmation is required.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "description": "How long that confirmation stays usable.", "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "description": "Present only while confirmation is required — what will run, in one sentence, for a person to approve.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/jobs.read": { "post": { "operationId": "call_jobs_read", "summary": "Call jobs.read", "description": "'is my clip done yet', 'did that edit finish' — read one long-running job's status by the job_id a call answered (videos.generate_clip, or an edit or draft that answered in_flight): queued, running, succeeded or failed, when it started and finished, and once it has succeeded what to read next. It changes nothing and starts nothing. Not for starting work — call the verb that makes it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "jobs" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "minLength": 1, "description": "The job_id a long-running call answered (for example videos.generate_clip)." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "job_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ], "description": "queued — accepted, not started; running — under way; succeeded — done, read `result`; failed — it stopped, see error_code." }, "created_at": { "type": "string", "description": "When the job was asked for (ISO 8601)." }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it started running, or null before it has." }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it finished, or null while it has not." }, "result": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "clip", "video", "brand_fact" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "null" } ], "description": "Once succeeded: what to read next — the clip made, the video the run wrote, or the brand kit fact the confirm confirmed (read it with brand_kit.read). Null until then." }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Once failed: a stable code for why. Null otherwise." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "completed_at", "created_at", "error_code", "job_id", "result", "started_at", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/jobs.set_webhook": { "post": { "operationId": "call_jobs_set_webhook", "summary": "Call jobs.set_webhook", "description": "'send my completed jobs to this URL', 'notify our server when a clip is done' — register the workspace's job-completion webhook, or replace it: the https URL to announce completed jobs to, and a signing secret the operator chose and keeps. Once set, every long-running job that finishes (a clip from videos.generate_clip, an edit or draft that answered in_flight) is announced once, as a POST signed with that secret whose body is the job's jobs.read answer. The secret is never shown back. It spends nothing and starts no job. Not for reading a job's status — that is jobs.read.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "jobs" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "The https URL to announce completed jobs to. It must name a public host on the default port, with no user name, password or fragment." }, "signing_secret": { "type": "string", "pattern": "^[\\x21-\\x7e]{32,256}$", "description": "A secret you choose and keep, 32 to 256 printable characters with no spaces. Every delivery is signed with it: x-goosy-signature: t=,v1=.\">. It is never shown back." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "url", "signing_secret" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "webhook_id": { "type": "string", "description": "The webhook's id." }, "url": { "type": "string", "description": "The URL completed jobs are announced to." }, "state": { "type": "string", "enum": [ "registered", "replaced" ], "description": "registered — this call created the workspace's webhook; replaced — it already existed, and its URL and secret are now these." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "url", "webhook_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/jobs.remove_webhook": { "post": { "operationId": "call_jobs_remove_webhook", "summary": "Call jobs.remove_webhook", "description": "Remove this workspace's job-completion webhook — 'remove our job webhook', 'stop sending finished jobs to our server', 'that webhook URL is dead, take it off'. A workspace has at most one: the address its finished jobs (a made clip, an edit or draft that ran long) are announced to over the API. Removing it stops every announcement from then on and releases the signing secret it was set up with; this cannot be undone, and the only way back is to register a webhook again. It takes no arguments. Calling it raises the approval card, which names the host announcements stop going to, so call it on the ask. If the workspace has no webhook, the card says so and nothing changes. Not for setting up or replacing the webhook's URL or secret — that is `jobs.set_webhook`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "jobs" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "removed", "description": "removed — the webhook is gone and its signing secret released; no completed job is announced to it again." } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "webhook_id": { "type": "string", "description": "The removed webhook's id." }, "url_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The host completed jobs were announced to." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.describe": { "post": { "operationId": "call_images_describe", "summary": "Call images.describe", "description": "'what images are on this board', 'tell me more about this image' — without generation_id, list one board's images, newest first: each image's id, stored caption and status; with generation_id, read that one image's stored description in full. The board is named by id and must be this workspace's. A listing is one page: totalCount is the board's real size, hasMore means older images sit on later pages, and page is a direct index, so the oldest images are on page ceil(totalCount / pageSize). It changes nothing. Not for the workspace's saved photos, logo and product shots — that is `images.brand_elements`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "generation_id": { "description": "The id of ONE image to describe in detail. OMIT to list this board's images (ids + prompts + captions) — call it that way FIRST whenever you need an image id for images.iterate / images.add_to_board.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page": { "description": "Listing page, a DIRECT INDEX (newest first, 8 per page) — page 1 is the newest and the OLDEST images are on page ceil(totalCount / pageSize), so jump straight to the page you want rather than walking one page at a time. The listing result says totalCount and hasMore. Ignored when generation_id is set.", "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "board": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The board to act on, by id — one of this workspace's boards (board.tree lists them)." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "boardId": { "type": "string" }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "images": { "type": "array", "items": { "type": "object", "properties": { "generationId": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "generationId", "role", "status", "description", "createdAt" ], "additionalProperties": false } }, "instruction": { "type": "string", "minLength": 1 }, "generationId": { "type": "string" }, "status": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "describedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.brand_elements": { "post": { "operationId": "call_images_brand_elements", "summary": "Call images.brand_elements", "description": "'what photos of me do we have saved', 'which logos can an image use' — list this workspace's saved brand elements, newest first: photos of the owner ('person'), logos, product shots and other references, each with its id, role and name. Only elements whose upload has finished are listed. It changes nothing. Not for saved looks — that is `images.saved_styles`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "Restrict the listing to one role: 'person' (the operator's own photos — what a request for their likeness resolves to), 'logo', 'product', or 'reference'. Omit to list every role.", "anyOf": [ { "type": "string", "enum": [ "logo", "person", "product", "reference" ] }, { "type": "null" } ] }, "page": { "description": "Listing page (newest first, 12 per page). The result says hasMore — request page+1 to continue.", "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "elements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "logo", "person", "product", "reference" ] }, "name": { "type": "string" }, "packLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "role", "name", "packLabel" ], "additionalProperties": false } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1 }, "hasMore": { "type": "boolean" }, "instruction": { "type": "string", "minLength": 1 }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "elements", "hasMore", "instruction", "page", "pageSize", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.saved_styles": { "post": { "operationId": "call_images_saved_styles", "summary": "Call images.saved_styles", "description": "'what styles do we have saved', 'show me our saved looks' — list this workspace's saved image styles, newest first: each look's id, name, note, and whether its source image is finished and usable. It changes nothing. Not for photos of people, logos or products — that is `images.brand_elements`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "styles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usable": { "type": "boolean" } }, "required": [ "id", "name", "note", "usable" ], "additionalProperties": false } }, "instruction": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "instruction", "styles", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.save_style": { "post": { "operationId": "call_images_save_style", "summary": "Call images.save_style", "description": "'save this look so we can use it again', 'turn this image into a saved style' — save one image's look as a named, reusable workspace style. The name is required; saving the same image twice changes nothing and the answer says it was already a style. Not for keeping the image itself in the Library — that is `images.save_to_library`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "generation_id": { "type": "string", "description": "The id of the image whose LOOK should be saved." }, "name": { "type": "string", "minLength": 1, "description": "What to call the style — REQUIRED, because this is how the operator picks it later. Use their words if they named it; otherwise propose a short descriptive name and say what you chose." }, "note": { "description": "Optional 'when to use this' note for the operator's own reference.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "board": { "description": "Optional: the board this image is being saved from, by id — recorded as where it came from. Omit when there is none.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "generation_id", "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "savedStyleId": { "type": "string" }, "name": { "type": "string" }, "alreadySaved": { "type": "boolean" }, "instruction": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "alreadySaved", "instruction", "name", "savedStyleId", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.save_to_library": { "post": { "operationId": "call_images_save_to_library", "summary": "Call images.save_to_library", "description": "'keep this image in our library', 'save that one for later' — keep one image, named by its id, in the workspace Library so it can be found and reused from any board. Saving twice changes nothing; the answer says whether it was already kept. Not for saving the image's look as a reusable style — that is `images.save_style`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "generation_id": { "type": "string", "minLength": 1, "description": "The id of the image to keep in the Library (images.describe lists a board's images with their ids)." }, "name": { "description": "Optional name for the saved image.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "board": { "description": "Optional: the board this image is being saved from, by id — recorded as where it came from. Omit when there is none.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "generation_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "savedGenerationIds": { "type": "array", "items": { "type": "string" } }, "alreadySavedGenerationIds": { "type": "array", "items": { "type": "string" } }, "skippedGenerationIds": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "alreadySavedGenerationIds", "savedGenerationIds", "skippedGenerationIds", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.add_to_board": { "post": { "operationId": "call_images_add_to_board", "summary": "Call images.add_to_board", "description": "'add that image to this board', 'bring this picture over as a reference' — place one image already in this workspace on a board, named by id, as an output tile or as a reference for later runs. Adding it twice changes nothing. Not for keeping an image in the Library — that is `images.save_to_library`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "generation_id": { "type": "string", "description": "The id of the image to add to this board." }, "role": { "description": "How the image sits on the board: 'output' (default) or 'reference' (an input for later runs).", "anyOf": [ { "type": "string", "enum": [ "output", "reference" ] }, { "type": "null" } ] }, "board": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The board to act on, by id — one of this workspace's boards (board.tree lists them)." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "generation_id", "board" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "attachedGenerationIds": { "type": "array", "items": { "type": "string" } }, "skippedGenerationIds": { "type": "array", "items": { "type": "string" } }, "role": { "type": "string", "enum": [ "output", "reference" ] }, "boardId": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "attachedGenerationIds", "boardId", "role", "skippedGenerationIds", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.list": { "post": { "operationId": "call_automations_list", "summary": "Call automations.list", "description": "'what automations do we have?', 'is that automation still on?' — list this workspace's automations, the same rows its Automations board shows: each one's definition id, name, status (Running, Needs a look, Paused or Not scheduled), the project it lives in, its schedule in words, when it last ran and when it fires next, plus a count per status. It answers one page — as many automations as fit, in the board's order — and `counts` on every page covers every automation, not only the rows shown; when `next_cursor` comes back, call again with it as `cursor` for the rest, and `limit` asks for fewer. It changes nothing. Not for whether one automation's inbound webhook is set up — that is `automations.webhook_token_status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "At most this many automations on the page. Omit it to get as many as fit in one answer.", "type": "integer", "minimum": 1 }, "cursor": { "description": "Where to continue: pass the `next_cursor` from the previous page, with the same filters. Omit it for the first page.", "type": "string", "minLength": 1, "maxLength": 512 }, "name": { "description": "Only the automations whose name contains this, ignoring case. Omit it to list them all.", "type": "string", "minLength": 1, "maxLength": 120 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "automations": { "type": "array", "items": { "type": "object", "properties": { "definition_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "board_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "lives_in": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schedule": { "type": "string" }, "last_run_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next_fire_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "definition_id", "board_id", "name", "status", "lives_in", "schedule", "last_run_at", "next_fire_at" ], "additionalProperties": false } }, "counts": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "paused": { "type": "integer", "minimum": 0 }, "needs_a_look": { "type": "integer", "minimum": 0 }, "not_scheduled": { "type": "integer", "minimum": 0 } }, "required": [ "total", "running", "paused", "needs_a_look", "not_scheduled" ], "additionalProperties": false }, "next_cursor": { "description": "Present when there is another page: pass it back as `cursor` to read it. Absent on the last page.", "type": "string" }, "next": { "description": "What to call next to read, change or fix one of these automations.", "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "automations", "counts", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.webhook_token_status": { "post": { "operationId": "call_automations_webhook_token_status", "summary": "Call automations.webhook_token_status", "description": "'why isn't my webhook firing?', 'is the Zapier trigger set up?' — for one webhook-triggered automation in this workspace, named by its definition id (automations.list gives it), say whether its inbound token is set up, when it was issued or last rotated, and whether the automation is published, so the endpoint would accept a call. It never returns the token, and it changes nothing. Not for listing the automations — that is `automations.list`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definition_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The automation's definition id — the id in its webhook URL. Read it from automations.list or the board, never invent one." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "definition_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "definition_id": { "type": "string" }, "display_name": { "type": "string" }, "purpose": { "type": "string" }, "configured": { "type": "boolean" }, "minted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rotated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "configured", "definition_id", "display_name", "minted_at", "published", "purpose", "rotated_at", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/brand_kit.read": { "post": { "operationId": "call_brand_kit_read", "summary": "Call brand_kit.read", "description": "'what's our one-liner?', 'which offer is running right now?', 'find the photo of Alex at the counter' — read this workspace's brand kit: who the brand is, what it offers, who it is for, how it sounds and looks, where it is, its video settings, and its pictures by label, kind and tag (never the files). Each fact says whether a member confirmed it or it is still a suggestion; a suggestion carries the fact_id and updated_at a member confirms on the brand page. A large kit comes back in part, with `omitted` naming the groups to read next by `group`. It changes nothing. Not for adding or correcting a fact — that is `brand_kit.suggest`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "brand_kit" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "description": "Only this section of the kit. Omit for the whole kit; a long section comes back in part, and `omitted` names what to read next.", "type": "string", "enum": [ "identity", "offer", "audience", "verbal", "visual", "reach", "video" ] }, "kind": { "description": "Only this kind of fact — every row of one list, by the `kind` a section of `sections` names. Use it to read the whole of a list `sections` says was shortened (`shown` below its count).", "type": "string", "minLength": 1 }, "cursor": { "description": "The next page of the list read with `kind`: pass the `next_cursor` the last read returned, with the same `kind`. Omit it for the first page.", "type": "string", "minLength": 1 }, "library_query": { "description": "A word to find pictures by — a label, a kind or a tag ('book cover', 'person', 'product').", "type": "string", "maxLength": 120 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "name": { "type": "string" }, "logo": { "anyOf": [ { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "files": { "type": "array", "items": { "type": "string", "enum": [ "original", "transparent", "light", "dark" ] } }, "files_missing": { "type": "array", "items": { "type": "string", "enum": [ "transparent", "light", "dark" ] } }, "served_from": { "type": "string" }, "state": { "type": "string", "const": "suggested" }, "fact_id": { "type": "string" }, "updated_at": { "type": "string" }, "pending": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "files": { "type": "array", "items": { "type": "string", "enum": [ "original", "transparent", "light", "dark" ] } }, "files_missing": { "type": "array", "items": { "type": "string", "enum": [ "transparent", "light", "dark" ] } }, "served_from": { "type": "string" }, "state": { "type": "string", "const": "suggested" }, "fact_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "label", "source", "files", "fact_id", "updated_at" ], "additionalProperties": false } }, "required": [ "label", "source", "files", "fact_id", "updated_at" ], "additionalProperties": false }, { "type": "null" } ] }, "adherence": { "type": "string", "enum": [ "tight", "balanced", "loose" ] }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string" }, "group": { "type": "string", "enum": [ "identity", "offer", "audience", "verbal", "visual", "reach", "video" ] }, "state": { "type": "string", "enum": [ "empty", "suggested", "confirmed", "mixed" ] }, "confirmed": { "type": "integer" }, "suggested": { "type": "integer" }, "suggested_from": { "type": "array", "items": { "type": "string" } }, "kinds": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "name": { "type": "string" }, "confirmed": { "type": "integer" }, "suggested": { "type": "integer" }, "shown": { "type": "integer" } }, "required": [ "kind", "name", "confirmed", "suggested" ], "additionalProperties": false } }, "pictures": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer" } }, "files": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer" } }, "empty": { "type": "array", "items": { "type": "string" } } }, "required": [ "section", "group", "state", "confirmed", "suggested" ], "additionalProperties": false } }, "facts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "text": { "type": "string" }, "state": { "type": "string", "enum": [ "suggested", "confirmed" ] }, "item_key": { "type": "string" }, "fact_id": { "type": "string" }, "updated_at": { "type": "string" }, "source": { "type": "string" } }, "required": [ "kind", "label", "text", "state", "fact_id", "updated_at" ], "additionalProperties": false } }, "library": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "confirmed": { "type": "boolean" }, "fact_id": { "type": "string" }, "updated_at": { "type": "string" }, "source": { "type": "string" } }, "required": [ "asset_id", "label", "kind", "tags", "confirmed", "fact_id", "updated_at" ], "additionalProperties": false } }, "fill": { "type": "object", "properties": { "present": { "type": "integer" }, "total": { "type": "integer" }, "to_look_over": { "type": "integer" } }, "required": [ "present", "total", "to_look_over" ], "additionalProperties": false }, "page": { "type": "object", "properties": { "kind": { "type": "string" }, "from": { "type": "integer" }, "shown": { "type": "integer" }, "total": { "type": "integer" }, "last": { "type": "boolean" } }, "required": [ "kind", "from", "shown", "total", "last" ], "additionalProperties": false }, "next_cursor": { "type": "string" }, "omitted": { "type": "object", "properties": { "facts": { "type": "integer" }, "pictures": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "string" } }, "kinds": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "unread": { "type": "integer" } }, "required": [ "kind", "unread" ], "additionalProperties": false } } }, "required": [ "facts", "pictures", "groups" ], "additionalProperties": false }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "adherence", "facts", "fill", "library", "name", "sections", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/brand_kit.suggest": { "post": { "operationId": "call_brand_kit_suggest", "summary": "Call brand_kit.suggest", "description": "'we're running a Harvest Week sale, 1 to 7 October', 'add our new shop on Alder Street' — add one fact to this workspace's brand kit as a SUGGESTION: a location, an offer, a person, a picture and its name, a contact detail, a product. `kind` is the kit's own name for the fact (read the kit first when unsure); a kind the kit holds many of takes an `item_key`. It never confirms anything and never overwrites a confirmed fact: a change waits beside it until a member confirms it on the brand page. The same suggestion twice changes nothing. A dated note (kind `timing`) is refused with `brand_kit.note_chat_only`: a member says it in chat, and the API has no speaker to own it. Not for how closely drafts follow the brand — that is `brand_kit.set_adherence`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "brand_kit" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The fact's kind, as the kit's catalogue names it, such as `location`, `offer`, `person` or `asset` — an open set the catalogue holds, not a fixed list." }, "item_key": { "description": "For a kind the kit holds many of: a short slug for this one.", "type": "string", "minLength": 1, "maxLength": 120 }, "scope": { "description": "For a video setting that differs per job: the job (`youtube`, `shorts`).", "type": "string", "minLength": 1, "maxLength": 60 }, "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The fact's value, in its kind's shape." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "kind", "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "fact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "suggested", "confirmed" ] }, "line": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "fact_id", "line", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/brand_kit.set_adherence": { "post": { "operationId": "call_brand_kit_set_adherence", "summary": "Call brand_kit.set_adherence", "description": "'keep the brand loose for this post', 'stick to our brand exactly from now on' — set how closely drafts follow this workspace's brand kit: tight (exactly), balanced (mostly) or loose (as a reference), for one piece named by its title, or as the brand's default for every draft that follows. It answers in two calls: without confirmation_id it proposes and says what would change; the same call again with that confirmation_id, on a member's own API key, applies exactly that. The brand's facts and banned words hold at every level. Not for changing what the kit says — that is `brand_kit.suggest`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "brand_kit" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "tight", "balanced", "loose" ], "description": "tight = stick to the brand exactly; balanced = mostly; loose = use it as a reference only (the facts still hold)." }, "target": { "type": "string", "enum": [ "turn", "piece", "kit" ], "description": "turn = what the member just said about THIS piece in chat; piece = the piece's own setting; kit = the brand's default for everything." }, "piece_title": { "description": "For turn and piece, when no piece is open in this conversation: the piece's title, in the member's words.", "type": "string", "minLength": 1, "maxLength": 200 }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "level", "target" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "applied" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "level": { "type": "string", "enum": [ "tight", "balanced", "loose" ] }, "target": { "type": "string", "enum": [ "turn", "piece", "kit" ] }, "piece_title": { "type": "string" }, "current_level": { "type": "string", "enum": [ "tight", "balanced", "loose" ] }, "line": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "level", "state", "target", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/brand_playbook.run": { "post": { "operationId": "call_brand_playbook_run", "summary": "Call brand_playbook.run", "description": "'make us a logo', 'make the icon set from our logo', 'make some poses of Alex' — run one of this workspace's brand playbooks: poses of one of the brand's people, a logo pack (a logo with its favicon and icon set), or the icon set from the logo the brand has. It answers in two calls: without confirmation_id it returns the price per stage and a confirmation_id and spends nothing; the same call again with that confirmation_id, on a member's own API key, starts the run, spends the quoted credits and answers its job_run_id. The logo pack pauses after drawing its directions: a call without confirmation_id then answers `awaiting_pick`, and choosing one (`pick`) takes the same two calls and spends nothing. Not for a single picture or an edit to one — that is `images.generate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "brand_playbook" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "pose_pack", "logo_pack", "icon_set" ] }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "pick": { "type": "object", "properties": { "job_run_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "direction": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "job_run_id", "direction" ], "additionalProperties": false }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.forget_video_learning": { "post": { "operationId": "call_videos_forget_video_learning", "summary": "Call videos.forget_video_learning", "description": "'forget that we like short cold opens', 'that's not right any more' — forget one line Goosy has learned about the key holder's videos, quoted word for word with its category exactly as the brand kit's video page shows it; a paraphrase matches nothing. It answers in two calls: without confirmation_id it finds the line and says what would be forgotten, changing nothing; the same call again with that confirmation_id, on a member's own API key, forgets exactly that line. Not for a look they no longer want on a video — that is `videos.change_look`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The learned line's category, exactly as the page shows it beside the line." }, "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The learned line ITSELF, quoted word for word from what the page shows. It is matched exactly — a paraphrase matches nothing and removes nothing. If you are not certain of the wording, ask which line they mean instead of guessing." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "category", "text" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "forgotten" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "category": { "type": "string" }, "text": { "type": "string" }, "sentence": { "type": "string", "description": "The line as the brand kit shows it." }, "learned_on": { "type": "string", "description": "The day it was learned, YYYY-MM-DD." }, "removed": { "type": "boolean" }, "href": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.undo_edit": { "post": { "operationId": "call_videos_undo_edit", "summary": "Call videos.undo_edit", "description": "'undo that last change', 'put the pause back' — take back ONE thing the edit did to a video, by the log line's id `videos.read_edit` gives it. The line stays in the log, struck, and the video's length is worked out again; nothing is laid down again, so a master already made keeps the change until the video is edited again. It answers in two calls: without confirmation_id it names the line it would take back and changes nothing; the same call again with that confirmation_id, on a member's own API key, takes back exactly that line. Not for editing the video again — that is `videos.plan_edit`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The video's id, as given in this conversation." }, "log_entry_id": { "type": "string", "minLength": 1, "description": "The log line to undo, by the id the edit log gave it." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "video_id", "log_entry_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "undone" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "video_id": { "type": "string" }, "log_entry_id": { "type": "string" }, "line": { "type": "string", "description": "The edit line that would be taken back." }, "undone": { "type": "string" }, "log": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The log line's id — what `videos.undo_edit` takes." }, "sentence": { "type": "string", "description": "The plain past-tense sentence a person reads under the player." }, "kind": { "type": "string", "enum": [ "hook_tightened", "pause_dropped", "captions_on", "insert_placed", "music_bed_laid", "scene_shortened", "transition_changed", "frame_moved", "put_on_screen", "hook_moved", "ending_looped", "graded", "fillers_cut", "retakes_cut", "studio_sound_on", "words_cut", "take_not_heard" ] }, "scene_id": { "anyOf": [ { "type": "string", "minLength": 1, "description": "The scene's id, as given in the storyboard." }, { "type": "null" } ], "description": "The scene's id, as given in the storyboard." }, "undoable": { "type": "boolean" } }, "required": [ "id", "sentence", "kind", "scene_id", "undoable" ], "additionalProperties": false } }, "seconds": { "type": "integer" }, "clock": { "type": "string" }, "relaying": { "type": "boolean" }, "open_at": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "video_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/videos.stock_pull": { "post": { "operationId": "call_videos_stock_pull", "summary": "Call videos.stock_pull", "description": "'find a real shot for this scene', 'use a real clip of a desk here' — find a real-world shot for one storyboard scene and drop it in as an insert of a few seconds; it never replaces the scene, and the answer names who took it with a link. It answers in two calls: without confirmation_id it says what would be looked for and for how long, and searches nothing; the same call again with that confirmation_id, on a member's own API key, searches, keeps the shot in this workspace's clips and places it. Not for a made clip when nothing real will do — that is `videos.generate_clip`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "videos" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The video's id, as given in this conversation." }, "scene_id": { "type": "string", "minLength": 1, "description": "The scene's id, as given in the storyboard." }, "looking_for": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What the shot should be of, in a few words." }, "seconds": { "default": 5, "description": "How long the shot runs inside the scene — a few seconds.", "type": "integer", "minimum": 1, "maximum": 15 }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "video_id", "scene_id", "looking_for" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "placed" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "video_id": { "type": "string" }, "scene_id": { "type": "string" }, "looking_for": { "type": "string", "description": "What the search would look for." }, "seconds": { "anyOf": [ { "type": "integer", "description": "How long the insert would run." }, { "type": "integer" } ] }, "attribution": { "type": "string", "description": "The photographer's name." }, "link": { "type": "string", "description": "The link to the shot on Pexels." }, "marker": { "type": "string" }, "open_at": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "scene_id", "seconds", "state", "video_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.batch": { "post": { "operationId": "call_images_batch", "summary": "Call images.batch", "description": "'give me ten options for the launch hero', 'make a batch of product shots on this board' — make a batch of new images from one brief onto a board in this workspace, named by id. It spends: it answers in two calls on every key. Without confirmation_id it checks the board, returns the quote (how many images, at what shape, and the draw on the workspace's image allowance) with a confirmation_id, and makes and charges nothing; the same call again with that confirmation_id, on a member's own API key, starts the run and answers its run_id. Each delivered image is charged when it is made. Not for a single image — that is `images.generate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The board to act on, by id — one of this workspace's boards (board.tree lists them)." }, "brief": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What to generate, in plain words." }, "count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many images the batch makes, 1-10. Each delivered image draws on the workspace's image allowance." }, "shape": { "description": "The aspect ratio. Omit for square (1:1).", "type": "string", "enum": [ "1:1", "3:4", "4:3", "9:16", "16:9" ] }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board", "brief", "count" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "enum": [ "dispatched", "accepted" ], "description": "dispatched — the run is under way. accepted — the run is under way but its details could not be read just now: count and aspect_ratio are null; follow it by run_id." } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "quote": { "type": "object", "properties": { "count": { "type": "integer", "exclusiveMinimum": 0 }, "aspect_ratio": { "type": "string" }, "board_id": { "type": "string" }, "budget": { "type": "string", "description": "The workspace allowance this batch draws on." }, "budget_units": { "type": "integer", "exclusiveMinimum": 0, "description": "How much of that allowance the batch draws." } }, "required": [ "count", "aspect_ratio", "board_id", "budget", "budget_units" ], "description": "What confirming would run: how many images, at what shape, on which board, and the draw on the workspace's image allowance. Each delivered image is charged when it is made.", "additionalProperties": false }, "run_id": { "type": "string", "description": "The run now under way — follow it by this." }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "aspect_ratio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "board_id": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/images.start_board": { "post": { "operationId": "call_images_start_board", "summary": "Call images.start_board", "description": "'start a new image board for the launch thumbnails', 'open a board for our October post images' — open a NEW image board in this workspace under the given name, with the opening request waiting in its composer, UNSENT. One call: it answers the new board's id and name and `open_path` — the link that lands a member on the board with the request ready. Nothing is generated and nothing is spent: pictures are made only when a member presses send. Not for making images on a board that already exists — that is `images.generate` or `images.batch`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "images" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What to call the board, in the operator's own words — what the pictures are FOR (\"Launch thumbnails\", \"October post images\"), never a generic placeholder." }, "opening_request": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The request to leave waiting in the board's composer: what to make, how many, and at what shape, written as the operator would say it. Build it from what they actually told you — never invent a brief they did not describe." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "name", "opening_request" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string" }, "board_name": { "type": "string" }, "request_waiting": { "type": "boolean", "const": true, "description": "Always true: the opening request waits, unsent, in the board's composer — nothing is generated until a member sends it." }, "open_path": { "type": "string", "description": "The board's path in the app, carrying the opening request: whoever opens it lands on the board with the request waiting, unsent, in its composer." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "board_name", "open_path", "request_waiting", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.deactivate": { "post": { "operationId": "call_automations_deactivate", "summary": "Call automations.deactivate", "description": "'turn this automation off', 'stop that automation running' — switch one automation in this workspace off, named by its board_id: it stops running until it is switched back on, and its saved versions are kept, so switching it on again restores exactly what it ran. It answers in two calls: without confirmation_id it proposes, says what would change and changes nothing; the same call again with that confirmation_id, on a member's own API key, switches it off. Not for pausing only its schedule — that is `automations.pause_schedule`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The board of the automation. Omit on an automation board — the conversation already knows which one it is on.", "type": "string" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "deactivated" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string" }, "display_name": { "type": "string" }, "is_active": { "type": "boolean" }, "active_version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "changed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "display_name", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.pause_schedule": { "post": { "operationId": "call_automations_pause_schedule", "summary": "Call automations.pause_schedule", "description": "'pause this automation's schedule', 'stop it running on schedule for now' — stop one automation in this workspace, named by its board_id, from running on its schedule, without switching the automation off. It answers in two calls: without confirmation_id it proposes, shows the schedule as it stands and changes nothing; the same call again with that confirmation_id, on a member's own API key, pauses it. Not for switching the whole automation off — that is `automations.deactivate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The board of the automation. Omit on an automation board — the conversation already knows which one it is on.", "type": "string" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "paused" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string" }, "display_name": { "type": "string" }, "cron": { "type": "string" }, "timezone": { "type": "string" }, "current_status": { "type": "string", "enum": [ "active", "paused" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "changed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.resume_schedule": { "post": { "operationId": "call_automations_resume_schedule", "summary": "Call automations.resume_schedule", "description": "'resume this automation's schedule', 'start it running on schedule again' — let one paused automation in this workspace, named by its board_id, run on its schedule again, on the times it was saved with. It answers in two calls: without confirmation_id it proposes, shows the schedule as it stands and changes nothing; the same call again with that confirmation_id, on a member's own API key, resumes it. Not for switching an automation on — that is `automations.activate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The board of the automation. Omit on an automation board — the conversation already knows which one it is on.", "type": "string" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "resumed" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string" }, "display_name": { "type": "string" }, "cron": { "type": "string" }, "timezone": { "type": "string" }, "current_status": { "type": "string", "enum": [ "active", "paused" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "changed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.restore_version": { "post": { "operationId": "call_automations_restore_version", "summary": "Call automations.restore_version", "description": "'put version 2 back', 'restore the version from last week' — make an earlier published version of one automation in this workspace, named by its board_id, the one that runs again: its document is published forward as a NEW version, so the history stays in order. It answers in two calls: without confirmation_id it proposes, names the version it would replace and changes nothing; the same call again with that confirmation_id, on a member's own API key, restores it. Not for switching an automation on — that is `automations.activate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "description": "The version number to put back — the number shown in the automation's Versions list." }, "board_id": { "description": "The board of the automation. Omit on an automation board — the conversation already knows which one it is on.", "type": "string" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "restored" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string" }, "display_name": { "type": "string" }, "restore_from_version": { "type": "integer", "exclusiveMinimum": 0 }, "active_version": { "anyOf": [ { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ] }, { "type": "integer", "exclusiveMinimum": 0 } ] }, "restored_from_version": { "type": "integer", "exclusiveMinimum": 0 }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "active_version", "board_id", "display_name", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.test_run": { "post": { "operationId": "call_automations_test_run", "summary": "Call automations.test_run", "description": "'test this automation', 'dry-run it before we switch it on' — dry-run one automation in this workspace, named by its board_id, against the workspace's synthetic test contact: its draft (or, with no draft, the version that runs) walks every step, sends go only to the workspace's designated test address, waits are skipped and CRM writes are withheld. A person or deal the member names is the test to run: the synthetic test contact stands in for them, and the answer's subject says so. The run starts with the trigger data a real start carries for that contact; sample carries only trigger details the member gave (a form's fields, say), as test values. A run uses model and step time. It answers in two calls: without confirmation_id it proposes, names the version and the test address and runs nothing; the same call again with that confirmation_id, on a member's own API key, runs it. Not for switching it on for real contacts — that is `automations.activate`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The id of the automation to test, as `automations.list` answers it — never its name. Omit it to test the automation this conversation is on; for another automation the operator names, read its board_id from `automations.list` and pass that.", "type": "string" }, "sample": { "description": "Sample trigger data, shaped as a real trigger of this automation would carry it — for a form capture, `{ event: { payload: { fields: { form: \"application\" } } } }`. Pass it only with trigger details the operator gave (a form they named, say), as test values; a plain test passes none. Any person in it is replaced by the synthetic test contact, which stands in for them. A JSON object, at most 16 KB.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "tested" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string" }, "tested": { "type": "string", "enum": [ "draft", "active" ] }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "inbox": { "type": "string" }, "run_id": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "inbox", "state", "tested", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.repair_step": { "post": { "operationId": "call_automations_repair_step", "summary": "Call automations.repair_step", "description": "'why did the email step fail?', 'fix the step that broke on the last run' — repair ONE step of an automation in this workspace, named by its board_id, that failed on its last run. Without a fix it reads how that step failed and how it is configured today, and changes nothing; omit step_key to repair the step that failed on the last run, which the answer names. With a fix it answers in two calls: without confirmation_id it proposes the change and shows that one step before and after, changing nothing; the same call again with that confirmation_id, on a member's own API key, saves it as a new draft that does not run until it is switched on. A fix that would touch any other step, the order or what starts the automation is refused. Not for rewriting the whole automation — that is `automations.author`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The board of the automation to repair. Omit on an automation board — the conversation already knows which one it is on.", "type": "string", "minLength": 1, "maxLength": 64 }, "step_key": { "description": "The machine key of the step that FAILED. Leave it out to repair the step that failed on the last run; the answer names that step. Call without `fix` first to read what it was given, what it produced and how it failed.", "type": "string", "minLength": 1, "maxLength": 64 }, "fix": { "description": "The change to THAT ONE step. Omit on the first call. A field you leave out is left exactly as it is. You may not change the step's key, its kind, what it hands on, any other step, the order, or what starts the automation — a fix that would is REFUSED.", "type": "object", "properties": { "label": { "description": "A new name for the step.", "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "description": "A new plain-language description of the step.", "type": "string", "maxLength": 400 }, "implementation": { "description": "The registered action this step should run instead, e.g. `ghl.send_email`.", "type": "string", "minLength": 1, "maxLength": 200 }, "params": { "description": "The step's settings, in full. What you send REPLACES the step's current settings, so include the ones that were already right. An `email.send` step's saved email is set by its `emailId`, never by the email's words.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "delay": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "hours": { "type": "integer", "minimum": 0 }, "minutes": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "until": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "object", "properties": { "path": { "type": "string" }, "offset": { "type": "string" } }, "required": [ "path", "offset" ], "additionalProperties": false } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "waitForEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "tag_added", "reply_received" ] }, "tag": { "type": "string", "minLength": 1, "maxLength": 200 }, "timeoutMinutes": { "type": "integer", "minimum": 5, "maximum": 43200 } }, "required": [ "event", "timeoutMinutes" ], "additionalProperties": false } }, "additionalProperties": false }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "diagnosis" }, { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "repaired" } ] }, "board_id": { "type": "string" }, "step_key": { "type": "string" }, "step_label": { "type": "string" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "step": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$", "description": "A stable key: lowercase letters, digits and underscores, starting with a letter (gather_answers); later steps read its answer as steps.." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The step's name in plain language." }, "kind": { "default": "automated", "description": "What the step is. automated (the default, leave it off): runs an action by its implementation. ask: stops for a person or the contact, then carries on with the answer. wait: waits a set time, until a date, for something to happen, until a read says done, or for a callback. think: a model answers its instruction from the inputs it names, in the shape its JSON Schema declares. run: starts another automation of this workspace, and may wait for its answer. branch: sends the run down one of its edges by its rules. set: gives later steps the fields it names. loop: runs its body once for each item of a list, or until a test holds. code: JavaScript or Python, written when the step is set up with `automations.bind_step`. Every kind but automated and ask takes no implementation.", "type": "string", "enum": [ "automated", "approval", "code_step", "delay", "conversation", "wait_for_event", "compute", "think", "ask", "loop", "branch", "set", "wait", "run", "code" ] }, "description": { "description": "What this step does, in one sentence.", "type": "string", "maxLength": 400 }, "implementation": { "description": "An automated step's action, by its catalogue key: contact.add_tag, contact.remove_tag, email.send, notify.member, opportunity.move_stage, contact.update_field, data.query, data.write, automation.call, or a connected tool's connector..; an ask step's is automation.ask. An unknown key is refused by name and nothing is saved, so never invent one.", "type": "string", "minLength": 1, "maxLength": 200 }, "params": { "description": "The step's settings, in its action's own shape: { \"tag\": \"hot\" } for contact.add_tag, { \"emailId\": \"\" } for email.send. Every action refuses a setting it does not take and names it, so ask the member rather than guessing one, and never pass settings without an implementation except on the kinds that take none. An ask step takes { \"target\": { \"kind\": \"member\" } or { \"kind\": \"role\", \"role\": \"admin\" } or { \"kind\": \"contact\" }, \"question\": \"…\", \"answerKind\": \"approve_decline\" or \"choice\" or \"text\", \"options\": [\"…\"], \"timeout\": \"P3D\" }: the timeout is required (ask the member for it), options only for choice, and a contact answers in text. Its answer is steps..outcome: approved, declined, answered or timed_out. A think step takes { \"instruction\": \"…\", \"inputs\": { \"\": \"{{ steps.. }}\" }, \"schema\": }: the schema is the answer's shape ({ \"type\": \"string\", \"enum\": [\"yes\", \"no\"] } for a decision; an object naming every field later steps read), and later steps read it at steps..answer. It reads the run only through its inputs, and may name a \"slot\": \"writing.standard\", \"writing.plus\", \"writing.max\" (the strongest writing last). To answer once for each item of a list, add \"items\": \"{{ steps.. }}\" (at most 20) and read each as {{ item }} in the inputs; the answers are steps..items[i].answer. When the work is many items and nobody waits on the answer (a nightly summary, sorting a list of replies), add \"timing\": \"batch\" and say so: the items go to the provider's batch rate, about half the usual price where the step's model has one, and the answers come back within hours rather than seconds. A wait step takes one of: { \"for\": \"P2D\" } (how long, an ISO 8601 duration, at most 90 days); { \"until\": \"2026-11-01T09:00\" } (a date-time in the workspace's zone, or one {{ … }} that gives an instant); { \"event\": { \"type\": \"tag_added\", \"tag\": \"…\" } or { \"type\": \"reply_received\" }, \"timeout\": \"P3D\" } (until that happens to the run's contact, at most 30 days); { \"poll\": { \"tool\": \"automation.call\" or \"connector..\", \"params\": { … }, \"until\": \"{{ json.status == 'done' }}\", \"every\": \"PT5M\" }, \"timeout\": \"PT1H\" }; or { \"callback\": { \"request\": { … }, \"expect\": }, \"timeout\": \"PT15M\" }. A wait that times out fails as wait_timeout, and the step's on_error decides what happens next. A run step takes { \"workflow\": \"\", \"mode\": \"wait\" or \"start\", \"input\": { … } }: wait holds this run until that one answers, read at steps..; start sets it going and carries on. A set step's settings are the fields it gives later steps ({ \"total\": \"{{ … }}\", \"label\": \"…\" }), read at steps... A branch step takes { \"rules\": [ { \"name\": \"big_order\", \"if\": \"{{ trigger.payload.total > 500 }}\" } ], \"mode\": \"first\" } and no implementation: each edge out of it names the rule it follows in output, or \"else\" for the edge taken when no rule holds; mode \"all\" takes every rule that holds. A code step takes { \"language\": \"javascript\" or \"python\", \"instruction\": \"\", \"inputs\": { \"\": \"{{ … }}\" }, \"output_schema\": }; binding it writes the code, which reads only its inputs and has no network. A browser step reads a website on this workspace's browsing list: `implementation: \"platform.browser\"` with `{\"task\":\"…\",\"startUrl\":\"https://…\",\"output\":,\"maxMinutes\":5}` (`output` when later steps read fields; up to 10 minutes). Its answer is at `stepResults..answer`. When `stepResults..outcome` is `needs_member` (a CAPTCHA, a sign-in code, a missing login, or a site off the list), follow it with an `ask` to the member quoting `stepResults..member_step`, then the same browser step again. Any setting, at any depth, reads the run's data with {{ … }} around one CEL expression. A value that is exactly one {{ … }} keeps its type (a number, a list, a map); with words around it, it is text. What an expression reads: trigger (what started the run: a webhook's body at trigger.payload., an app event's fields at trigger.event.payload.); steps. (an earlier step's answer: a table read's rows at steps..rows, each { row_id, values: { : … } }; a think's at steps..answer); json (the step just before); item and index (inside a loop); run.id and run.contactId; contact.consent.email and contact.consent.sms. Operators: + - * / %, == != < <= > >=, && || !, cond ? a : b, x in list. Functions, each called by its bare name: size(x). For text: upper(s), lower(s), trim(s), replace(s, from, to), substring(s, start, end), split(s, sep), join(list, sep), s.contains(t), s.startsWith(t), test(s, re2), extract(s, re2), format(\"%s of %s\", [a, b]). For numbers: round(x), round(x, 2), floor(x), ceil(x), abs(x), sum(list), avg(list), min(list), max(list), int(x), double(x), string(x). For lists: list.map(x, expr), list.filter(x, cond), list.exists(x, cond), first(list), last(list), sort(list), sortBy(list, \"field\"), unique(list), slice(list, from, to). For maps: has(m.field), get(m, \"a.b\", default), pick(m, keys), merge(a, b), keys(m), values(m). For dates: now(), dateAdd(d, \"P1D\"), dateDiff(a, b, \"day\"), dateFormat(d, \"MMM d, h:mm a\", \"America/Chicago\") (yyyy MM dd HH mm, and a zone; UTC when none), startOf(d, \"week\"). A value that may be missing: coalesce(trigger.payload.nickname, \"friend\") gives a default, and coalesce(trigger.payload.company, omit) leaves that key out. Examples: \"Booking {{ trigger.payload.booking_id }} for {{ trigger.payload.guests }} guests\"; { \"open\": \"{{ size(steps.read_tasks.rows) }}\" }; \"{{ join(steps.read_tasks.rows.map(r, r.values.title), ', ') }}\". An expression that cannot be read, names a step that is not before this one, or gives the wrong kind of value is refused at save with its path and its fix.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "delay": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "hours": { "type": "integer", "minimum": 0 }, "minutes": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "until": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "object", "properties": { "path": { "type": "string" }, "offset": { "type": "string" } }, "required": [ "path", "offset" ], "additionalProperties": false } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "waitForEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "tag_added", "reply_received" ] }, "tag": { "type": "string", "minLength": 1, "maxLength": 200 }, "timeoutMinutes": { "type": "integer", "minimum": 5, "maximum": 43200 } }, "required": [ "event", "timeoutMinutes" ], "additionalProperties": false } }, "required": [ "key", "label" ], "additionalProperties": false }, "run_id": { "type": "string" }, "test_run": { "type": "boolean" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "applies_to_version": { "type": "integer", "exclusiveMinimum": 0 }, "expected_latest_version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "step_before": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$", "description": "A stable key: lowercase letters, digits and underscores, starting with a letter (gather_answers); later steps read its answer as steps.." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The step's name in plain language." }, "kind": { "default": "automated", "description": "What the step is. automated (the default, leave it off): runs an action by its implementation. ask: stops for a person or the contact, then carries on with the answer. wait: waits a set time, until a date, for something to happen, until a read says done, or for a callback. think: a model answers its instruction from the inputs it names, in the shape its JSON Schema declares. run: starts another automation of this workspace, and may wait for its answer. branch: sends the run down one of its edges by its rules. set: gives later steps the fields it names. loop: runs its body once for each item of a list, or until a test holds. code: JavaScript or Python, written when the step is set up with `automations.bind_step`. Every kind but automated and ask takes no implementation.", "type": "string", "enum": [ "automated", "approval", "code_step", "delay", "conversation", "wait_for_event", "compute", "think", "ask", "loop", "branch", "set", "wait", "run", "code" ] }, "description": { "description": "What this step does, in one sentence.", "type": "string", "maxLength": 400 }, "implementation": { "description": "An automated step's action, by its catalogue key: contact.add_tag, contact.remove_tag, email.send, notify.member, opportunity.move_stage, contact.update_field, data.query, data.write, automation.call, or a connected tool's connector..; an ask step's is automation.ask. An unknown key is refused by name and nothing is saved, so never invent one.", "type": "string", "minLength": 1, "maxLength": 200 }, "params": { "description": "The step's settings, in its action's own shape: { \"tag\": \"hot\" } for contact.add_tag, { \"emailId\": \"\" } for email.send. Every action refuses a setting it does not take and names it, so ask the member rather than guessing one, and never pass settings without an implementation except on the kinds that take none. An ask step takes { \"target\": { \"kind\": \"member\" } or { \"kind\": \"role\", \"role\": \"admin\" } or { \"kind\": \"contact\" }, \"question\": \"…\", \"answerKind\": \"approve_decline\" or \"choice\" or \"text\", \"options\": [\"…\"], \"timeout\": \"P3D\" }: the timeout is required (ask the member for it), options only for choice, and a contact answers in text. Its answer is steps..outcome: approved, declined, answered or timed_out. A think step takes { \"instruction\": \"…\", \"inputs\": { \"\": \"{{ steps.. }}\" }, \"schema\": }: the schema is the answer's shape ({ \"type\": \"string\", \"enum\": [\"yes\", \"no\"] } for a decision; an object naming every field later steps read), and later steps read it at steps..answer. It reads the run only through its inputs, and may name a \"slot\": \"writing.standard\", \"writing.plus\", \"writing.max\" (the strongest writing last). To answer once for each item of a list, add \"items\": \"{{ steps.. }}\" (at most 20) and read each as {{ item }} in the inputs; the answers are steps..items[i].answer. When the work is many items and nobody waits on the answer (a nightly summary, sorting a list of replies), add \"timing\": \"batch\" and say so: the items go to the provider's batch rate, about half the usual price where the step's model has one, and the answers come back within hours rather than seconds. A wait step takes one of: { \"for\": \"P2D\" } (how long, an ISO 8601 duration, at most 90 days); { \"until\": \"2026-11-01T09:00\" } (a date-time in the workspace's zone, or one {{ … }} that gives an instant); { \"event\": { \"type\": \"tag_added\", \"tag\": \"…\" } or { \"type\": \"reply_received\" }, \"timeout\": \"P3D\" } (until that happens to the run's contact, at most 30 days); { \"poll\": { \"tool\": \"automation.call\" or \"connector..\", \"params\": { … }, \"until\": \"{{ json.status == 'done' }}\", \"every\": \"PT5M\" }, \"timeout\": \"PT1H\" }; or { \"callback\": { \"request\": { … }, \"expect\": }, \"timeout\": \"PT15M\" }. A wait that times out fails as wait_timeout, and the step's on_error decides what happens next. A run step takes { \"workflow\": \"\", \"mode\": \"wait\" or \"start\", \"input\": { … } }: wait holds this run until that one answers, read at steps..; start sets it going and carries on. A set step's settings are the fields it gives later steps ({ \"total\": \"{{ … }}\", \"label\": \"…\" }), read at steps... A branch step takes { \"rules\": [ { \"name\": \"big_order\", \"if\": \"{{ trigger.payload.total > 500 }}\" } ], \"mode\": \"first\" } and no implementation: each edge out of it names the rule it follows in output, or \"else\" for the edge taken when no rule holds; mode \"all\" takes every rule that holds. A code step takes { \"language\": \"javascript\" or \"python\", \"instruction\": \"\", \"inputs\": { \"\": \"{{ … }}\" }, \"output_schema\": }; binding it writes the code, which reads only its inputs and has no network. A browser step reads a website on this workspace's browsing list: `implementation: \"platform.browser\"` with `{\"task\":\"…\",\"startUrl\":\"https://…\",\"output\":,\"maxMinutes\":5}` (`output` when later steps read fields; up to 10 minutes). Its answer is at `stepResults..answer`. When `stepResults..outcome` is `needs_member` (a CAPTCHA, a sign-in code, a missing login, or a site off the list), follow it with an `ask` to the member quoting `stepResults..member_step`, then the same browser step again. Any setting, at any depth, reads the run's data with {{ … }} around one CEL expression. A value that is exactly one {{ … }} keeps its type (a number, a list, a map); with words around it, it is text. What an expression reads: trigger (what started the run: a webhook's body at trigger.payload., an app event's fields at trigger.event.payload.); steps. (an earlier step's answer: a table read's rows at steps..rows, each { row_id, values: { : … } }; a think's at steps..answer); json (the step just before); item and index (inside a loop); run.id and run.contactId; contact.consent.email and contact.consent.sms. Operators: + - * / %, == != < <= > >=, && || !, cond ? a : b, x in list. Functions, each called by its bare name: size(x). For text: upper(s), lower(s), trim(s), replace(s, from, to), substring(s, start, end), split(s, sep), join(list, sep), s.contains(t), s.startsWith(t), test(s, re2), extract(s, re2), format(\"%s of %s\", [a, b]). For numbers: round(x), round(x, 2), floor(x), ceil(x), abs(x), sum(list), avg(list), min(list), max(list), int(x), double(x), string(x). For lists: list.map(x, expr), list.filter(x, cond), list.exists(x, cond), first(list), last(list), sort(list), sortBy(list, \"field\"), unique(list), slice(list, from, to). For maps: has(m.field), get(m, \"a.b\", default), pick(m, keys), merge(a, b), keys(m), values(m). For dates: now(), dateAdd(d, \"P1D\"), dateDiff(a, b, \"day\"), dateFormat(d, \"MMM d, h:mm a\", \"America/Chicago\") (yyyy MM dd HH mm, and a zone; UTC when none), startOf(d, \"week\"). A value that may be missing: coalesce(trigger.payload.nickname, \"friend\") gives a default, and coalesce(trigger.payload.company, omit) leaves that key out. Examples: \"Booking {{ trigger.payload.booking_id }} for {{ trigger.payload.guests }} guests\"; { \"open\": \"{{ size(steps.read_tasks.rows) }}\" }; \"{{ join(steps.read_tasks.rows.map(r, r.values.title), ', ') }}\". An expression that cannot be read, names a step that is not before this one, or gives the wrong kind of value is refused at save with its path and its fix.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "delay": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "hours": { "type": "integer", "minimum": 0 }, "minutes": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "until": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "object", "properties": { "path": { "type": "string" }, "offset": { "type": "string" } }, "required": [ "path", "offset" ], "additionalProperties": false } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "waitForEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "tag_added", "reply_received" ] }, "tag": { "type": "string", "minLength": 1, "maxLength": 200 }, "timeoutMinutes": { "type": "integer", "minimum": 5, "maximum": 43200 } }, "required": [ "event", "timeoutMinutes" ], "additionalProperties": false } }, "required": [ "key", "label" ], "additionalProperties": false }, "step_after": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$", "description": "A stable key: lowercase letters, digits and underscores, starting with a letter (gather_answers); later steps read its answer as steps.." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The step's name in plain language." }, "kind": { "default": "automated", "description": "What the step is. automated (the default, leave it off): runs an action by its implementation. ask: stops for a person or the contact, then carries on with the answer. wait: waits a set time, until a date, for something to happen, until a read says done, or for a callback. think: a model answers its instruction from the inputs it names, in the shape its JSON Schema declares. run: starts another automation of this workspace, and may wait for its answer. branch: sends the run down one of its edges by its rules. set: gives later steps the fields it names. loop: runs its body once for each item of a list, or until a test holds. code: JavaScript or Python, written when the step is set up with `automations.bind_step`. Every kind but automated and ask takes no implementation.", "type": "string", "enum": [ "automated", "approval", "code_step", "delay", "conversation", "wait_for_event", "compute", "think", "ask", "loop", "branch", "set", "wait", "run", "code" ] }, "description": { "description": "What this step does, in one sentence.", "type": "string", "maxLength": 400 }, "implementation": { "description": "An automated step's action, by its catalogue key: contact.add_tag, contact.remove_tag, email.send, notify.member, opportunity.move_stage, contact.update_field, data.query, data.write, automation.call, or a connected tool's connector..; an ask step's is automation.ask. An unknown key is refused by name and nothing is saved, so never invent one.", "type": "string", "minLength": 1, "maxLength": 200 }, "params": { "description": "The step's settings, in its action's own shape: { \"tag\": \"hot\" } for contact.add_tag, { \"emailId\": \"\" } for email.send. Every action refuses a setting it does not take and names it, so ask the member rather than guessing one, and never pass settings without an implementation except on the kinds that take none. An ask step takes { \"target\": { \"kind\": \"member\" } or { \"kind\": \"role\", \"role\": \"admin\" } or { \"kind\": \"contact\" }, \"question\": \"…\", \"answerKind\": \"approve_decline\" or \"choice\" or \"text\", \"options\": [\"…\"], \"timeout\": \"P3D\" }: the timeout is required (ask the member for it), options only for choice, and a contact answers in text. Its answer is steps..outcome: approved, declined, answered or timed_out. A think step takes { \"instruction\": \"…\", \"inputs\": { \"\": \"{{ steps.. }}\" }, \"schema\": }: the schema is the answer's shape ({ \"type\": \"string\", \"enum\": [\"yes\", \"no\"] } for a decision; an object naming every field later steps read), and later steps read it at steps..answer. It reads the run only through its inputs, and may name a \"slot\": \"writing.standard\", \"writing.plus\", \"writing.max\" (the strongest writing last). To answer once for each item of a list, add \"items\": \"{{ steps.. }}\" (at most 20) and read each as {{ item }} in the inputs; the answers are steps..items[i].answer. When the work is many items and nobody waits on the answer (a nightly summary, sorting a list of replies), add \"timing\": \"batch\" and say so: the items go to the provider's batch rate, about half the usual price where the step's model has one, and the answers come back within hours rather than seconds. A wait step takes one of: { \"for\": \"P2D\" } (how long, an ISO 8601 duration, at most 90 days); { \"until\": \"2026-11-01T09:00\" } (a date-time in the workspace's zone, or one {{ … }} that gives an instant); { \"event\": { \"type\": \"tag_added\", \"tag\": \"…\" } or { \"type\": \"reply_received\" }, \"timeout\": \"P3D\" } (until that happens to the run's contact, at most 30 days); { \"poll\": { \"tool\": \"automation.call\" or \"connector..\", \"params\": { … }, \"until\": \"{{ json.status == 'done' }}\", \"every\": \"PT5M\" }, \"timeout\": \"PT1H\" }; or { \"callback\": { \"request\": { … }, \"expect\": }, \"timeout\": \"PT15M\" }. A wait that times out fails as wait_timeout, and the step's on_error decides what happens next. A run step takes { \"workflow\": \"\", \"mode\": \"wait\" or \"start\", \"input\": { … } }: wait holds this run until that one answers, read at steps..; start sets it going and carries on. A set step's settings are the fields it gives later steps ({ \"total\": \"{{ … }}\", \"label\": \"…\" }), read at steps... A branch step takes { \"rules\": [ { \"name\": \"big_order\", \"if\": \"{{ trigger.payload.total > 500 }}\" } ], \"mode\": \"first\" } and no implementation: each edge out of it names the rule it follows in output, or \"else\" for the edge taken when no rule holds; mode \"all\" takes every rule that holds. A code step takes { \"language\": \"javascript\" or \"python\", \"instruction\": \"\", \"inputs\": { \"\": \"{{ … }}\" }, \"output_schema\": }; binding it writes the code, which reads only its inputs and has no network. A browser step reads a website on this workspace's browsing list: `implementation: \"platform.browser\"` with `{\"task\":\"…\",\"startUrl\":\"https://…\",\"output\":,\"maxMinutes\":5}` (`output` when later steps read fields; up to 10 minutes). Its answer is at `stepResults..answer`. When `stepResults..outcome` is `needs_member` (a CAPTCHA, a sign-in code, a missing login, or a site off the list), follow it with an `ask` to the member quoting `stepResults..member_step`, then the same browser step again. Any setting, at any depth, reads the run's data with {{ … }} around one CEL expression. A value that is exactly one {{ … }} keeps its type (a number, a list, a map); with words around it, it is text. What an expression reads: trigger (what started the run: a webhook's body at trigger.payload., an app event's fields at trigger.event.payload.); steps. (an earlier step's answer: a table read's rows at steps..rows, each { row_id, values: { : … } }; a think's at steps..answer); json (the step just before); item and index (inside a loop); run.id and run.contactId; contact.consent.email and contact.consent.sms. Operators: + - * / %, == != < <= > >=, && || !, cond ? a : b, x in list. Functions, each called by its bare name: size(x). For text: upper(s), lower(s), trim(s), replace(s, from, to), substring(s, start, end), split(s, sep), join(list, sep), s.contains(t), s.startsWith(t), test(s, re2), extract(s, re2), format(\"%s of %s\", [a, b]). For numbers: round(x), round(x, 2), floor(x), ceil(x), abs(x), sum(list), avg(list), min(list), max(list), int(x), double(x), string(x). For lists: list.map(x, expr), list.filter(x, cond), list.exists(x, cond), first(list), last(list), sort(list), sortBy(list, \"field\"), unique(list), slice(list, from, to). For maps: has(m.field), get(m, \"a.b\", default), pick(m, keys), merge(a, b), keys(m), values(m). For dates: now(), dateAdd(d, \"P1D\"), dateDiff(a, b, \"day\"), dateFormat(d, \"MMM d, h:mm a\", \"America/Chicago\") (yyyy MM dd HH mm, and a zone; UTC when none), startOf(d, \"week\"). A value that may be missing: coalesce(trigger.payload.nickname, \"friend\") gives a default, and coalesce(trigger.payload.company, omit) leaves that key out. Examples: \"Booking {{ trigger.payload.booking_id }} for {{ trigger.payload.guests }} guests\"; { \"open\": \"{{ size(steps.read_tasks.rows) }}\" }; \"{{ join(steps.read_tasks.rows.map(r, r.values.title), ', ') }}\". An expression that cannot be read, names a step that is not before this one, or gives the wrong kind of value is refused at save with its path and its fix.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "delay": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "hours": { "type": "integer", "minimum": 0 }, "minutes": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "until": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "object", "properties": { "path": { "type": "string" }, "offset": { "type": "string" } }, "required": [ "path", "offset" ], "additionalProperties": false } ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "waitForEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "tag_added", "reply_received" ] }, "tag": { "type": "string", "minLength": 1, "maxLength": 200 }, "timeoutMinutes": { "type": "integer", "minimum": 5, "maximum": 43200 } }, "required": [ "event", "timeoutMinutes" ], "additionalProperties": false } }, "required": [ "key", "label" ], "additionalProperties": false }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "state", "step_key", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.propose_webhook_token": { "post": { "operationId": "call_automations_propose_webhook_token", "summary": "Call automations.propose_webhook_token", "description": "'rotate that webhook token', 'give me a new token for the Zapier trigger' — replace the inbound webhook token of one webhook-triggered automation in this workspace, named by its definition_id (automations.list gives it). It answers in two calls: without confirmation_id it proposes, says whether a token exists and whether the automation is live, and changes nothing; the same call again with that confirmation_id, on a member's own API key, rotates it and returns the new token ONCE, in that answer — store it then, nothing can show it again, and every sender on the old token is refused from that moment. Needs an account admin's key. With intent `mint` it issues an automation's FIRST token the same way. Not for shutting a webhook off — that is `automations.revoke_webhook_token`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definition_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The automation's definition id — the id in its webhook URL. Read it from automations.list or the board, never invent one." }, "intent": { "type": "string", "enum": [ "mint", "rotate" ], "description": "`mint` for an automation that has no token yet; `rotate` to replace a live one (every existing sender stops working the moment it is rotated)." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "definition_id", "intent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "enum": [ "minted", "rotated" ] } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "intent": { "type": "string", "enum": [ "mint", "rotate" ] }, "status": { "type": "object", "properties": { "definition_id": { "type": "string" }, "display_name": { "type": "string" }, "purpose": { "type": "string" }, "configured": { "type": "boolean" }, "minted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rotated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published": { "type": "boolean" } }, "required": [ "definition_id", "display_name", "purpose", "configured", "minted_at", "rotated_at", "published" ], "description": "Whether this automation's inbound webhook token is provisioned, and when it was last issued. Never contains the token itself — nothing can return that after the moment it is minted.", "additionalProperties": false }, "webhook_token": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.revoke_webhook_token": { "post": { "operationId": "call_automations_revoke_webhook_token", "summary": "Call automations.revoke_webhook_token", "description": "'kill that webhook', 'that token leaked, revoke it' — retire the inbound webhook token of one webhook-triggered automation in this workspace, named by its definition_id (automations.list gives it): every caller using it is refused from then on and the automation stops firing until a new token is issued. It answers in two calls — a proposal that names which automation goes dark and whether it is live, then a confirm on a member's own API key. Not for replacing the token — that is `automations.propose_webhook_token`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definition_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The automation's definition id — the id in its webhook URL. Read it from automations.list or the board, never invent one." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "definition_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "revoked" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "status": { "type": "object", "properties": { "definition_id": { "type": "string" }, "display_name": { "type": "string" }, "purpose": { "type": "string" }, "configured": { "type": "boolean" }, "minted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rotated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published": { "type": "boolean" } }, "required": [ "definition_id", "display_name", "purpose", "configured", "minted_at", "rotated_at", "published" ], "description": "Whether this automation's inbound webhook token is provisioned, and when it was last issued. Never contains the token itself — nothing can return that after the moment it is minted.", "additionalProperties": false }, "definition_id": { "type": "string" }, "display_name": { "type": "string" }, "purpose": { "type": "string" }, "configured": { "type": "boolean" }, "minted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rotated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.run": { "post": { "operationId": "call_automations_run", "summary": "Call automations.run", "description": "'run the welcome automation now', 'kick off the onboarding automation for this lead' — start a live run of one switched-on automation in this workspace, named by its board_id (automations.list gives each one): the same run its board's Run now starts, on the version that is live, so its sends and actions are real. It answers at once with the run id and pending; the run continues in the background and the automation's board shows how it went. Pass input to give the run its opening values, and a request_id of your own so a retried call answers the first run instead of starting a second. A draft or a switched-off automation is refused and nothing runs. Each run uses model and step time and is billed as a run. Not for trying a draft safely against the workspace's test contact — that is `automations.test_run`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The automation's board id, as `automations.list` returns it in board_id." }, "input": { "description": "Optional values the run starts with, as one JSON object of at most 16 KB; its steps read them from the run's state. The run's own identity (tenant, workspace, user, run id) is set by the platform and cannot be supplied here.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "request_id": { "description": "Optional UUID you choose for this start. Sending the same request_id again answers the first call's run and starts nothing new, so a retried call never runs the automation twice. Omit it and every call starts its own run.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "run_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The run that was started; the automation's board shows it in its run history." }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "const": "pending", "description": "Always pending: the run was handed to the runner and has not run yet." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "run_id", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.get": { "post": { "operationId": "call_automations_get", "summary": "Call automations.get", "description": "'show me the steps of the welcome automation', 'what does the onboarding automation do right now?' — read one automation in this workspace, named by its board_id (automations.list gives each one), with the steps, edges and trigger of the version it runs: the switched-on version, or its newest draft when none is switched on. The steps come back exactly as stored, in the shape `automations.author` takes, and latest_version says whether a newer draft exists. It changes nothing. An automation of another workspace, or a board with no automation, answers not found. Not for listing every automation and its status — that is `automations.list`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The automation's board id, as `automations.list` returns it in board_id." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "board_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "definition_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The automation's definition id, as `automations.list` returns it." }, "name": { "type": "string", "description": "The automation's name." }, "version": { "anyOf": [ { "type": "object", "properties": { "number": { "type": "integer", "exclusiveMinimum": 0, "description": "The version number, as the automation's versions list shows it." }, "is_live": { "type": "boolean", "description": "True when this is the switched-on version; false when the automation has none switched on and this is its newest draft." }, "status": { "type": "string", "description": "The version's stored status." }, "steps": { "description": "The version's steps, exactly as stored: the same document `automations.author` takes in steps." }, "edges": { "description": "The version's edges as stored, or null when the steps run in their listed order." }, "trigger": { "description": "What starts the automation, as stored, or null when no trigger is set." }, "review_gated": { "type": "boolean", "description": "True when each run waits for a person's review before it acts." }, "created_at": { "type": "string", "description": "When this version was saved (ISO 8601)." } }, "required": [ "number", "is_live", "status", "steps", "edges", "trigger", "review_gated", "created_at" ], "description": "One stored version of the automation.", "additionalProperties": false }, { "type": "null" } ], "description": "The switched-on version, else the newest draft; null when the automation has no version saved yet." }, "latest_version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "The newest version number, draft or live; when it is above version.number a newer draft exists. Null when no version is saved." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "definition_id", "latest_version", "name", "version", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.undo_draft": { "post": { "operationId": "call_automations_undo_draft", "summary": "Call automations.undo_draft", "description": "'undo the last change to the welcome automation', 'take back that edit' — undo the last change to one automation's draft in this workspace, named by its key: the draft's previous state is written back as a new change, so `automations.redo_draft` can bring the undone change back, and the version that runs is unchanged. Pass `revision` (a save's answer) to undo exactly that change: a draft that moved since is refused and nothing changes. A retry with the same idempotency_key returns the first answer and undoes nothing more. Not for throwing the whole draft away — that is `automations.discard_draft`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The board of the automation. Omit on an automation board — the conversation already knows which one it is on.", "type": "string" }, "revision": { "description": "Only to undo one particular change: the `revision` that change's save answered. A draft that moved since is refused, and nothing changes; leave it out to step from the draft as it stands.", "type": "integer", "minimum": 0 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string" }, "display_name": { "type": "string" }, "status": { "type": "string", "const": "draft" }, "revision": { "type": "integer", "minimum": 0 }, "can_undo": { "type": "boolean" }, "can_redo": { "type": "boolean" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without stepping the draft again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "can_redo", "can_undo", "display_name", "replayed", "revision", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.redo_draft": { "post": { "operationId": "call_automations_redo_draft", "summary": "Call automations.redo_draft", "description": "'redo that change', 'put the edit I undid back' — redo the change last undone on one automation's draft in this workspace, named by its key: it is written back into the draft as a new change, and the version that runs is unchanged. A fresh edit after an undo clears what can be redone. A retry with the same idempotency_key returns the first answer and redoes nothing more. Not for undoing a change — that is `automations.undo_draft`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The board of the automation. Omit on an automation board — the conversation already knows which one it is on.", "type": "string" }, "revision": { "description": "Only to undo one particular change: the `revision` that change's save answered. A draft that moved since is refused, and nothing changes; leave it out to step from the draft as it stands.", "type": "integer", "minimum": 0 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "board_id": { "type": "string" }, "display_name": { "type": "string" }, "status": { "type": "string", "const": "draft" }, "revision": { "type": "integer", "minimum": 0 }, "can_undo": { "type": "boolean" }, "can_redo": { "type": "boolean" }, "replayed": { "type": "boolean", "description": "True when this is the first result of an earlier call with the same idempotency_key, returned without stepping the draft again." }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "board_id", "can_redo", "can_undo", "display_name", "replayed", "revision", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/automations.discard_draft": { "post": { "operationId": "call_automations_discard_draft", "summary": "Call automations.discard_draft", "description": "'discard the draft of the welcome automation', 'scrap these changes and keep what is running' — throw away one automation's unpublished draft in this workspace, named by its key: every change in it goes at once, and the automation shows its live version again; the live version and its runs are not touched. An automation that was never published has no live version to go back to, and is refused. It answers in two calls: without confirmation_id it proposes, says what would be thrown away and changes nothing; the same call again with that confirmation_id, on a member's own API key, discards it, refused if the draft changed since. Not for undoing one change — that is `automations.undo_draft`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "automations" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "The board of the automation. Omit on an automation board — the conversation already knows which one it is on.", "type": "string" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "discarded" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "board_id": { "type": "string" }, "display_name": { "type": "string" }, "discarded_version": { "type": "integer", "exclusiveMinimum": 0 }, "live_version": { "type": "integer", "exclusiveMinimum": 0 }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/brand_kit.confirm": { "post": { "operationId": "call_brand_kit_confirm", "summary": "Call brand_kit.confirm", "description": "'yes, that address is right — confirm it', 'confirm the Harvest Week offer' — confirm ONE suggested fact in this workspace's brand kit exactly as a member was shown it: the fact's id and the updated_at `brand_kit.read` returned; it takes no value. It answers in two calls: without confirmation_id it proposes and shows the fact as it would be confirmed; the same call again with that confirmation_id, on a member's own API key, starts the confirm and answers its job_run_id — the confirm runs on its own, in seconds. A suggestion that changed since it was read is refused. Not for changing a fact — that is `brand_kit.suggest` with the corrected value, then a confirm of that new version.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "brand_kit" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fact_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The suggested fact to confirm — its id from brand_kit.read." }, "expected_updated_at": { "type": "string", "minLength": 1, "description": "The fact's updated_at from brand_kit.read — the version the member was shown." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "fact_id", "expected_updated_at" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "submitted" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "fact_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "description": "The kit's own name for the fact (location, offer, …)." }, "item_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "description": "The fact exactly as it would be confirmed — the value shown." }, "expected_updated_at": { "type": "string" }, "job_run_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The confirm's job reference, for support. Its status is read by `job_id`, never by this id." }, "job_id": { "type": "string", "description": "The confirm's handle. Read its status with `jobs.read` until it says succeeded or failed: queued or running — still pending, keep waiting; succeeded — confirmed; failed — refused, and error_code says why (brand_fact.changed_since_review: the fact changed after it was read)." }, "read_outcome_with": { "type": "object", "properties": { "tool": { "type": "string", "const": "brand_kit.read" }, "kind": { "type": "string" } }, "required": [ "tool", "kind" ], "description": "Where the confirmed fact reads once `jobs.read` on job_id says succeeded: `brand_kit.read` with this kind. It cannot tell a pending confirm from a refused one — the fact reads suggested in both — so the status is `jobs.read`'s.", "additionalProperties": false }, "line": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "fact_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/brand_kit.retire": { "post": { "operationId": "call_brand_kit_retire", "summary": "Call brand_kit.retire", "description": "'take the old Alder Street shop out of the kit', 'that offer is over, remove it', 'no, that is not our logo' — retire ONE fact of this workspace's brand kit, named by the fact_id `brand_kit.read` returned. A confirmed fact leaves the kit; a suggestion is declined, and the same suggestion is not brought back. It answers in two calls: without confirmation_id it shows the fact as it would be retired and returns a confirmation_id; the same call again with that confirmation_id retires exactly that fact. It works only on a member's own API key. A retired fact cannot be restored; it is added again as a new fact. Not for correcting a fact — that is `brand_kit.suggest` with the corrected value.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "brand_kit" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fact_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The fact's id, exactly as brand_kit.read returned it." }, "expected_updated_at": { "description": "The updated_at brand_kit.read returned with the fact. A fact that changed since is refused. Omit to retire it as it reads now.", "type": "string", "minLength": 1, "maxLength": 64 }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "fact_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "anyOf": [ { "type": "string", "const": "confirmation_required" }, { "type": "string", "const": "retired" } ] }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "fact_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "anyOf": [ { "type": "string", "description": "The kit's own name for the fact." }, { "type": "string" } ] }, "item_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fact_state": { "type": "string", "enum": [ "confirmed", "suggested" ], "description": "confirmed: retiring removes it from the kit. suggested: retiring declines it, and the same suggestion is not brought back." }, "value": { "description": "The fact exactly as it would be retired." }, "updated_at": { "type": "string" }, "declined": { "type": "boolean", "description": "true when the retired fact was a suggestion, now declined." }, "read_outcome_with": { "type": "object", "properties": { "tool": { "type": "string", "const": "brand_kit.read" }, "kind": { "type": "string" } }, "required": [ "tool", "kind" ], "description": "`brand_kit.read` with this kind no longer lists the fact.", "additionalProperties": false }, "line": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "fact_id", "item_key", "kind", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/brand_kit.upload_asset": { "post": { "operationId": "call_brand_kit_upload_asset", "summary": "Call brand_kit.upload_asset", "description": "'upload our new logo', 'add this photo of Alex to the brand', 'put our menu PDF in the brand library' — bring one file of the member's own into this workspace's brand library, as the brand page's upload does: a logo, a picture of one of the brand's people, a document, or a reference picture. It takes three steps: action start with the kind, file name, type and exact size returns an asset_id and a short-lived put_url; PUT the file's bytes to put_url; action complete with that asset_id checks the stored file against the kind's type and size limits and puts it in the library, where it reads confirmed within seconds. A logo is also suggested as the brand's logo, and its light and dark versions are made at no charge. It works only on a member's own API key, and it spends no credits. Not for a fact that is not a file — that is `brand_kit.suggest`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "brand_kit" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "start", "complete" ] }, "kind": { "type": "string", "enum": [ "logo", "person_picture", "document", "reference" ] }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "mime_type": { "type": "string", "minLength": 1, "maxLength": 160 }, "byte_size": { "type": "integer", "exclusiveMinimum": 0 }, "label": { "type": "string", "minLength": 1, "maxLength": 240 }, "person": { "type": "string", "minLength": 1, "maxLength": 120 }, "asset_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "action": { "type": "string", "enum": [ "start", "complete" ] }, "state": { "type": "string", "enum": [ "open", "landed" ], "description": "open: send the bytes, then complete. landed: the file is in the library." }, "asset_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": [ "logo", "person_picture", "document", "reference" ] }, "put_url": { "description": "start: where to PUT the file's bytes, with the content-type in put_headers. It is the caller's own short-lived upload address.", "type": "string" }, "put_headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "fact_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "job_run_id": { "description": "complete: the confirm's job reference, for support. The file reads confirmed in seconds; read it as read_outcome_with says.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "read_outcome_with": { "type": "object", "properties": { "tool": { "type": "string", "const": "brand_kit.read" }, "kind": { "type": "string", "const": "asset" } }, "required": [ "tool", "kind" ], "description": "`brand_kit.read` with kind \"asset\" shows the outcome.", "additionalProperties": false }, "line": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "action", "asset_id", "kind", "line", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/keys.rotate": { "post": { "operationId": "call_keys_rotate", "summary": "Call keys.rotate", "description": "Propose, then confirm, replacing the API key making this call with a new one — 'rotate this key', 'swap in a fresh credential'. The current key keeps working for overlap_hours after the new key exists, then stops. The new key comes back once, on the confirm, so store it before anything else. Not for any other key — revoke or rotate those in Settings › API & MCP.", "tags": [ "keys" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "overlap_hours": { "description": "How many hours the current key keeps working after the new one exists, 0 to 168. Default 24.", "type": "integer", "minimum": 0, "maximum": 168 }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` whenever the call did not succeed, including when the tool itself returned a typed `ok: false` — this tool runs at account level, so there is no workspace boundary to distinguish. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "enum": [ "confirmation_required", "rotated" ] }, "overlap_hours": { "type": "integer" }, "previous_key_prefix": { "type": "string" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "key": { "type": "string" }, "key_prefix": { "type": "string" }, "key_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previous_key_expires_at": { "type": "string" } }, "required": [ "ok", "overlap_hours", "previous_key_prefix", "state" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/leads.capture": { "post": { "operationId": "call_leads_capture", "summary": "Call leads.capture", "description": "Send one lead from a form on the workspace's own website into Goosy — 'send this signup in as a lead', 'capture the demo request from our site', 'add the waitlist entry for jane@example.com'. The lead is stored, the submitter becomes the workspace's contact, the automations that start on a captured lead run, and the contact goes to the workspace's connected GoHighLevel; with no CRM connected the lead waits and is sent when one is connected. It answers with the lead's and the contact's ids, a submission_id, and any fields it ignored. To retry a call, send the same submission_id so nothing is stored twice. Not for a note on someone already a contact — that is `contact.note`. The contact's details reach the connected CRM and an automation may message them; this cannot be undone from here.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "leads" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the `idempotency_key` body field, which still works until 2026-12-31.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The submitter's email address. Required; the contact is matched on it." }, "name": { "description": "The submitter's name, as they typed it.", "type": "string", "maxLength": 200 }, "phone": { "description": "The submitter's phone number; sent to the CRM in international form when it can be read as one.", "type": "string", "maxLength": 64 }, "form": { "description": "Your name for the form on your site (lowercase letters, digits, - or _), e.g. newsletter or demo_request. An automation can start only on leads from one form.", "type": "string", "maxLength": 64 }, "fields": { "description": "Every other field the form collected, by its own name, as strings. Stored with the lead as sent.", "type": "object", "propertyNames": { "type": "string", "maxLength": 100 }, "additionalProperties": { "type": "string", "maxLength": 4000 } }, "utm": { "description": "The visit's first-touch campaign tags and click ids, when your site kept them, by their URL names: utm_source, utm_medium, utm_campaign, utm_term, utm_content, fbclid, gclid, li_fat_id. Any other key is dropped and listed in ignored_fields.", "type": "object", "propertyNames": { "type": "string", "maxLength": 32 }, "additionalProperties": { "type": "string", "maxLength": 512 } }, "consent": { "description": "What the submitter agreed to, recorded with the lead as sent.", "type": "object", "properties": { "email": { "description": "The submitter agreed to email.", "type": "boolean" }, "sms": { "description": "The submitter agreed to text messages at the phone given.", "type": "boolean" }, "text": { "description": "The consent wording the submitter saw.", "type": "string", "maxLength": 4000 } }, "additionalProperties": false }, "submission_id": { "description": "Optional. An id naming this submission, also accepted as the Idempotency-Key header; with none, the answer's submission_id names it. Send the same value only when retrying the same submission: a retry returns the first answer and stores nothing again.", "type": "string", "minLength": 1, "maxLength": 200 }, "idempotency_key": { "description": "Deprecated on REST: send the `Idempotency-Key` header instead. Still accepted until 2026-12-31; if both are sent they must match.", "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "email" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "lead_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "contact_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "submission_id": { "type": "string" }, "replayed": { "type": "boolean" }, "ignored_fields": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "contact_id", "ignored_fields", "lead_id", "replayed", "submission_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/domain.search": { "post": { "operationId": "call_domain_search", "summary": "Call domain.search", "description": "Find domain names the member could buy and what each costs — 'what domains are available?', 'is mybrand.com free?', 'find me a good name for this'. Find domain names the customer could buy, with what each costs per year. Every name is for ONE year and renews at the same kind of price — there is no first-year discount that jumps later. Read the price back before anyone commits to anything, and note that a name marked premium costs more to renew as well. This only looks; it never buys. Not for getting a name ready to buy — that is `domain.purchase`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "domain" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "What the customer wants their address to be — a bare name like `acme` or a full one like `acme.com`. Pass what they said." }, "tlds": { "description": "Optional. Restrict to these endings (`com`, `io`, `co`), without the dot. Leave it out to let the registrar suggest.", "type": "array", "items": { "type": "string" } }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "available": { "type": "boolean" }, "source": { "type": "string" }, "customer_price_cents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "customer_renewal_price_cents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premium": { "type": "boolean" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "available", "source", "customer_price_cents", "customer_renewal_price_cents", "currency", "premium", "unavailable_reason" ], "additionalProperties": false } }, "term_years": { "type": "number" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "candidates", "term_years", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/domain.status": { "post": { "operationId": "call_domain_status", "summary": "Call domain.status", "description": "Say whether a domain's setup has come through yet — 'is my domain verified?', 'did the DNS work?', 'is it ready yet?'. Check whether a domain's Goosy Grow use is resolving yet, and record it as verified when it is. If checkable is false, say plainly that this one cannot be confirmed from here because Goosy Grow generates those records for the account — do not present it as failing or ask the member to wait. Otherwise relay the state and, when it is not verified yet, what DNS actually answered. Not for a page's own addresses — that is `page.domain_status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "domain" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The domain, as a UUID. Take it from the conversation's context or from the workspace's domain list — never invent one." }, "use": { "type": "string", "enum": [ "mail", "crm_links", "funnel" ], "description": "What the domain should be used for in Goosy Grow: `mail` (sending email), `crm_links` (the branded links in emails and texts), or `funnel` (funnels and sites)." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "domain_id", "use" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "use": { "type": "string", "enum": [ "mail", "crm_links", "funnel" ] }, "state": { "type": "string" }, "just_verified": { "type": "boolean" }, "checkable": { "type": "boolean" }, "observed": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "checkable", "domain_id", "hostname", "just_verified", "observed", "state", "use", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/domain.records": { "post": { "operationId": "call_domain_records", "summary": "Call domain.records", "description": "Show what DNS a domain has and what still has to be added — 'what records do I need?', 'is the DNS set up?', 'why isn't my domain working yet?'. Show a domain's DNS: if we manage it, exactly what's in place (the records we added are marked); if we don't, the records the customer still has to add plus what the domain answers with right now. zone_held false is a normal answer, not a problem. ALWAYS relay the copy_card lines — they're written for the customer to follow. Not for whether the domain is serving yet — that is `page.domain_status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "domain" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The domain, as a UUID. Take it from the conversation's context or from the workspace's domain list — never invent one." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "domain_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "zone_held": { "type": "boolean" }, "zone_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "source": { "type": "string" }, "placed_by_us": { "type": "boolean" } }, "required": [ "type", "name", "value", "priority", "ttl", "source", "placed_by_us" ], "additionalProperties": false } }, "copy_card": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "copy_card", "domain_id", "hostname", "records", "zone_held", "zone_name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/domain.set_use": { "post": { "operationId": "call_domain_set_use", "summary": "Call domain.set_use", "description": "Set one of the member's domains up for sending email, branded links, or funnels and sites — 'use this domain for my emails', 'set up my links domain', 'I want funnels on my own address'. Set a domain up for one of Goosy Grow's uses: mail (sending email), crm_links (branded links in emails and texts), or funnel (funnels and sites). Where we manage the domain's DNS we add the records for the customer; where we do not, we work out exactly which records they need. Either way ONE step is always theirs: opening Goosy Grow and adding the domain on the screen this returns. ALWAYS relay the copy_card lines and the deep_link — that is the point of the call — and never say the setup is finished, because it is not until they have clicked and domain.status confirms it. outcome zone_not_held and records_from_grow_screen are normal answers, not errors. Not for pointing a domain at a site — that is `domain.connect`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "domain" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The domain, as a UUID. Take it from the conversation's context or from the workspace's domain list — never invent one." }, "use": { "type": "string", "enum": [ "mail", "crm_links", "funnel" ], "description": "What the domain should be used for in Goosy Grow: `mail` (sending email), `crm_links` (the branded links in emails and texts), or `funnel` (funnels and sites)." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "domain_id", "use" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "use": { "type": "string", "enum": [ "mail", "crm_links", "funnel" ] }, "state": { "type": "string" }, "outcome": { "type": "string" }, "deep_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "type": "string" }, "screen_path_verified": { "type": "boolean" }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } }, "required": [ "type", "name", "value", "source" ], "additionalProperties": false } }, "copy_card": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "copy_card", "deep_link", "domain_id", "hostname", "outcome", "records", "screen", "screen_path_verified", "state", "use", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/domain.connect": { "post": { "operationId": "call_domain_connect", "summary": "Call domain.connect", "description": "Point a domain the member already owns at one of their sites — 'I want to use mydomain.com for this', 'connect the domain I bought', 'hook my own address up to this page'. Connect a domain the customer already owns to one of their pages. It reserves the name and starts the certificate, then hands back the DNS records they must add at whoever manages that domain's DNS. ALWAYS relay those records and the copy_card — the connection does not finish until the customer adds them. Never say the domain is live: use domain.records or page.domain_status to check. Not for moving a connected domain from one site to another — that is `domain.point_at_site`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "domain" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1, "description": "The domain the customer already owns, e.g. example.com or offers.example.com. Pass what they said — a pasted URL, a trailing dot or mixed case are all normalized. A name under the platform's own address is refused." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "hostname", "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "activation_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dcv_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overall": { "type": "string" }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "priority": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "source": { "type": "string" }, "placed_by_us": { "type": "boolean" } }, "required": [ "type", "name", "value", "priority", "ttl", "source", "placed_by_us" ], "additionalProperties": false } }, "copy_card": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "activation_status", "copy_card", "dcv_status", "domain_id", "hostname", "overall", "records", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/domain.point_at_site": { "post": { "operationId": "call_domain_point_at_site", "summary": "Call domain.point_at_site", "description": "Move a domain the member already has onto a different site — 'point mydomain.com at the new page instead', 'move my domain to this site', 'that address should go somewhere else now'. Move one of the customer's domains onto a different page. If serving_now comes back false the address is assigned but nothing is being served on it yet — read revision to tell which case it is. revision null: the page has never been published, so say that and offer to publish. revision set: this is a name we bought for the customer and it is not answering on the internet yet, so say that instead and never blame the page. Either way, do not call it live. The address we gave a page (its goosydoes.com name) belongs to that page and cannot be moved. Not for connecting a domain for the first time — that is `domain.connect`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "domain" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The domain, as a UUID. Take it from the conversation's context or from the workspace's domain list — never invent one." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "domain_id", "site_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "site_name": { "type": "string" }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "serving_now": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/domain.transfer_out": { "post": { "operationId": "call_domain_transfer_out", "summary": "Call domain.transfer_out", "description": "Give the member the steps to move a domain we bought them to another registrar — 'I want to move my domain elsewhere', 'how do I transfer this out?', 'get me the auth code'. Give the customer the exact steps to move a domain we registered for them to another registrar, and say whether it may leave yet. We can't do the move for them — the unlock and the authorization code are done in the registrar's own dashboard — so relay guided_step in order. Relay the eligibility reason WORD FOR WORD: eligible means no hold is visible from the registration date, NOT a guarantee the transfer will be accepted. This prepares only; nothing is transferred by this call. Not for pointing it at another site here — that is `domain.point_at_site`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "domain" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The domain, as a UUID. Take it from the conversation's context or from the workspace's domain list — never invent one." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "domain_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "domain_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "supported": { "type": "boolean" }, "reason": { "type": "string" }, "guided_step": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "url", "steps" ], "additionalProperties": false }, "eligibility": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "earliest_transfer_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "eligible", "reason", "earliest_transfer_at" ], "additionalProperties": false }, "hold_window_days": { "type": "number" }, "auto_approve_after_days": { "type": "number" }, "transfer_state": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/site.request": { "post": { "operationId": "call_site_request", "summary": "Call site.request", "description": "Do something through a site's own backend — 'save that through the site's admin', 'add a record the way the site does it', 'hit my site's own API for me'. Call one of this site's OWN routes — its admin save route, its API — signed in as the member, exactly as their browser would. Use it to operate a site's own backend: add a record, change a setting, read an admin listing. The path is site-local and starts with a slash; the site decides what each route does, so read the site's code or ask the member rather than guessing a route or a body shape. A members-only route is reachable this way and no other way from chat. A GET runs straight away; a POST, PUT, PATCH or DELETE changes the live site, so the member sees the method, the path and the site on a card and approves it before anything is sent. Not for reading or changing the site's own database — that is `site.database.query` or `site.database.execute`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "site" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The site, as a UUID. Take it from page.list or from the conversation's context — never invent one." }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "description": "The HTTP method the site's route expects. Use GET to read and POST/PUT/PATCH/DELETE to change something." }, "path": { "type": "string", "maxLength": 2048, "pattern": "^\\/(?![/\\\\])[^\\s\\\\@]*$", "description": "The route on the site, starting with a slash — for example /api/admin/save. Include the query string if the route needs one. Never a full URL and never another host." }, "body": { "description": "The JSON body, for POST, PUT and PATCH. Shape it the way the site's own route expects; if you do not know that shape, read the site's code or ask the operator rather than guessing." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "method", "path" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "hostname": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "path": { "type": "string" }, "status": { "type": "integer" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "body": {}, "truncated": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/site.database.query": { "post": { "operationId": "call_site_database_query", "summary": "Call site.database.query", "description": "Look inside a site's own database — 'what's in my site's database?', 'how many bookings are stored?', 'show me the products the site has'. Read this site's own database with one read-only SQL statement. It is the site's whole schema — the same database the site's own code reads as env.DB — so start with `select name from sqlite_master where type='table'` if you do not know it. Put every value in `params` as a ? placeholder. The statement must start with select, with, explain, or pragma table_info / table_list and carry no semicolon: this tool REFUSES anything that could change data or schema. Not for changing data or schema — that is `site.database.execute`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "site" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The site, as a UUID. Take it from page.list or from the conversation's context — never invent one." }, "sql": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "ONE read-only SQL statement for this site's own SQLite (D1) database. It must start with select, with, explain, or pragma table_info / pragma table_list, carry no semicolon, and change nothing — anything that inserts, updates, deletes, replaces, creates, drops, alters or attaches is refused here; site.database.execute is the door for those. Put every value in `params` as a ? placeholder. Use `select name from sqlite_master where type='table'` first if you do not know the schema." }, "params": { "description": "The values for the ? placeholders, in order. Always strings — SQLite converts them.", "maxItems": 256, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "sql" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "rows": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "row_count": { "type": "integer" }, "truncated": { "type": "boolean" }, "rows_read": { "type": "integer" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "row_count", "rows", "rows_read", "site_id", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/site.database.execute": { "post": { "operationId": "call_site_database_execute", "summary": "Call site.database.execute", "description": "Change what a site's own database holds — 'add that product to my site's shop', 'update the price in the site's database', 'delete that stale record from the site'. Change this site's own database with one SQL statement — insert, update, delete, or a schema change the site's code expects. Calling it raises the approval card showing the exact statement — and, for an update or delete, how many rows it touches — which is the member's confirmation. Put every value in `params` as a ? placeholder, and read the schema with site.database.query before writing. NEVER run a delete or update without a where clause, and never describe anything as changed before the member has approved. Not for reading the database — that is `site.database.query`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "site" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "The site, as a UUID. Take it from page.list or from the conversation's context — never invent one." }, "sql": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "ONE SQL statement for this site's own SQLite (D1) database. Put every value in `params` as a ? placeholder — never paste a value into the SQL, not even one the operator typed. Use site.database.query with `select name from sqlite_master where type='table'` first if you do not know the schema." }, "params": { "description": "The values for the ? placeholders, in order. Always strings — SQLite converts them.", "maxItems": 256, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "site_id", "sql" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "changes": { "type": "integer" }, "rows_written": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/workspace_sets.list": { "post": { "operationId": "call_workspace_sets_list", "summary": "Call workspace_sets.list", "description": "List this account's NAMED groups of brands — the sets a command can address, each with the brands YOU can actually reach in it. Use it before workspace_sets.update to find the setId, and whenever the operator names a group ('the north america ones') so you address the set they already have instead of describing one. Read-only. Not for the individual brands this account can open — that is `workspace_sets.list_brands`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "workspace_sets" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "sets": { "type": "array", "items": { "type": "object", "properties": { "setId": { "type": "string" }, "handle": { "type": "string" }, "name": { "type": "string" }, "selectorKind": { "type": "string" }, "memberCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "memberNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "setId", "handle", "name", "selectorKind", "memberCount", "memberNames" ], "additionalProperties": false } }, "unrecognizedCount": { "type": "number" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "sets", "unrecognizedCount", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/workspace_sets.list_brands": { "post": { "operationId": "call_workspace_sets_list_brands", "summary": "Call workspace_sets.list_brands", "description": "List the brands in this account you can actually open, each with the id a group needs. Use it whenever the operator names brands in their own words ('the two new locations', 'our Austin one') so you can turn those names into ids for workspace_sets.create — never invent or guess an id, and never ask the operator to find one. Read-only. Not for the named groups already set up — that is `workspace_sets.list`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "workspace_sets" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "brands": { "type": "array", "items": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "displayName": { "type": "string" }, "slug": { "type": "string" }, "companyType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "workspaceId", "displayName", "slug", "companyType" ], "additionalProperties": false } }, "truncated": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "brands", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.list": { "post": { "operationId": "call_page_list", "summary": "Call page.list", "description": "List this workspace's customer pages — name, draft/live status, address, last activity and lead count — plus the workspace totals (total_count, live_count, leads_this_month). The reply is ONE PAGE of sites, newest activity first: when it carries next_cursor there are more, so say how many you showed of total_count and pass next_cursor as cursor to read the next page (if the sites changed in between, the cursor is refused: start again from the first page and read the list over rather than joining it to what you have). Pass list 'templates' to read the template catalogue instead — the first-party template ids page.create accepts and every saved template this account can start from, named so you can offer them by name, also one page at a time. That template list is WIDER than this workspace: some were published by other workspaces in the same account and some are ours and shipped to every account — each row says which (`scope`), whether this workspace authored it (`owned_by_this_workspace`), and whether you may withdraw it (`retirable`). Only a row with `retirable: true` can be retired here. Reach for sites when the member asks WHICH sites they have — 'what pages do I have?', 'show me my sites', 'is the pricing page live yet?' — or when they name a site that is NOT the one already open on screen and you need its id; reach for templates only before offering a template by name. Not for one site's own state — that is `page.read` — and not for finding the site already open on their screen: that surface already carries its id, and listing the workspace to rediscover it is the hunt that ends in the wrong id.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "include_archived": { "description": "True to include archived pages. Leave unset for the board's normal view.", "type": "boolean" }, "list": { "description": "Which list to read. 'sites' (the default) is the workspace's pages. 'templates' is the template catalogue page.create starts from — ask for it only when the member wants to pick or hear about a template; it returns no sites.", "type": "string", "enum": [ "sites", "templates" ] }, "limit": { "description": "How many rows to return — at most 50; omit for 10 sites or 7 templates. The reply is one PAGE: a next_cursor in it says rows remain.", "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "cursor": { "description": "Where to continue: pass the next_cursor from the previous reply, with the same list, include_archived and name. Omit it for the first page. If the list changed since that page, the cursor is refused: start again without it.", "type": "string", "minLength": 1 }, "name": { "description": "The site's name or address as the member said it (\"Spring promo\", \"spring-promo.example.com\"). Returns just that site with its site_id — an exact name or address first, else the one site whose name starts with it. When several fit, the result lists them as candidates: ask the member which one, never pick. Use this whenever a verb needs a site_id for a site they NAMED. Not with list templates — that call is refused.", "type": "string", "minLength": 1, "maxLength": 253 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "sites": { "type": "array", "items": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "status": { "type": "string" }, "hostname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updated_at": { "type": "string" }, "archived": { "type": "boolean" }, "lead_count": { "type": "integer", "minimum": 0 } }, "required": [ "site_id", "name", "status", "hostname", "published_at", "updated_at", "archived", "lead_count" ], "additionalProperties": false } }, "list": { "type": "string", "enum": [ "sites", "templates" ] }, "next_cursor": { "type": "string" }, "templates_total": { "type": "integer", "minimum": 0 }, "total_count": { "type": "integer", "minimum": 0 }, "live_count": { "type": "integer", "minimum": 0 }, "leads_this_month": { "type": "integer", "minimum": 0 }, "template_ids": { "type": "array", "items": { "type": "string" } }, "name_match": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "exact", "prefix", "ambiguous", "none" ] }, "name": { "type": "string" }, "searched": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "kind", "name", "searched", "total" ], "additionalProperties": false }, "blueprints": { "type": "array", "items": { "type": "object", "properties": { "blueprint_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "platform", "tenant" ] }, "owned_by_this_workspace": { "type": "boolean" }, "retirable": { "type": "boolean" } }, "required": [ "blueprint_id", "name", "description", "scope", "owned_by_this_workspace", "retirable" ], "additionalProperties": false } }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "blueprints", "leads_this_month", "live_count", "sites", "template_ids", "total_count", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.list_files": { "post": { "operationId": "call_page_list_files", "summary": "Call page.list_files", "description": "Answer a member's question about which FILES a site is built from — 'what files does this site have?', 'show me the code', 'which file is the hero in?', 'where does the pricing copy live?'. No site id is needed — it works on the site the member has open on screen. It is for showing and explaining the source; a change the member asks for goes to `page.edit`, whose coding agent finds the place itself. It is the same tree the Files board shows, for every site whose files we hold, however it was made or brought in. A site we hold no source for answers kind: no_source_snapshot; say so rather than inventing files. A BIG PROJECT ANSWERS IN PAGES: total is the real file count, and when more files follow the result carries next_cursor — call again with cursor: next_cursor and the same path_prefix and contains to read on (if the site's files changed in between, the cursor is refused: start again from the first page and read it over rather than joining the lists), or pass path_prefix (`app/`, `components/`, `src/pages/`) to walk one directory at a time. NEVER guess a path: if you have not seen it listed here, page or narrow until you have. CHECK can_write: when it is false this site's files are READ-ONLY here — answer questions about them and offer no edit, because every edit will refuse it. To answer WHERE some words live — the date, headline or sentence a member asks about — pass contains with a short fragment of them: only the files holding it are listed, each with match_line and match_text. Not for what is inside one file, or for making a change — that is `page.read_file` or `page.edit`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "Optional site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy and nothing to look up. OMIT IT ENTIRELY and this call lists the files of that on-screen site; that is the PRIMARY path, not a fallback, and the turn's own surface resolves it server-side. Pass it only when the member explicitly named a DIFFERENT site and you took its id from page.list. Never pass a board, board-item, thread or any other id that merely happens to be nearby — those name different objects and will be refused.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "path_prefix": { "description": "Optional. List only the paths that start with this — `app/`, `components/`, `src/pages/`. Use it on a large project to walk one directory at a time; omit it for the first call, which shows the top of the tree and the true total.", "type": "string", "maxLength": 1024 }, "cursor": { "description": "Optional. Where to continue: when a result carries next_cursor there are more files — call again with cursor set to it and the same site_id, path_prefix and contains to read the rest. Omit it for the first page. Never guess a path you have not seen listed; page or narrow instead.", "type": "string", "minLength": 1 }, "contains": { "description": "Optional. Find WHERE some words live: only the text files whose contents contain this (case-insensitive, within one line) are listed, each with match_line and match_text — the first line it appears on. Use a short fragment of the words that are on the page NOW, e.g. 'Sept 22' to find the date a member asked to change; then page.read_file that file around match_line. total counts the matching files.", "type": "string", "minLength": 1, "maxLength": 1024 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": [ "source_snapshot", "no_source_snapshot" ] }, "source_ref": { "type": "string" }, "reason": { "type": "string", "enum": [ "bundle", "not_generated" ] }, "can_write": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "kind": { "type": "string", "enum": [ "page", "style", "script", "config", "image", "other" ] }, "match_line": { "type": "integer", "exclusiveMinimum": 0 }, "match_text": { "type": "string" } }, "required": [ "path", "size", "kind" ], "additionalProperties": false } }, "truncated": { "type": "boolean" }, "total": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "can_write", "files", "kind", "site_id", "total", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.read_file": { "post": { "operationId": "call_page_read_file", "summary": "Call page.read_file", "description": "Answer a member's question about what is IN one of a site's files — 'what's in Hero.astro?', 'show me the homepage code', 'let me see that file', 'what does the header say in the code?'. No site id is needed — it works on the site the member has open on screen. It reads one source file in a window of lines, for showing and explaining it; a change the member asks for goes to `page.edit`, whose coding agent reads the files itself. The result carries the source_ref the file was read at. When has_more is true the file continues; read the next window from end_line + 1 to answer about the rest. A binary file answers kind: binary with no content. Not for finding which file holds something, or for making a change — that is `page.list_files` or `page.edit`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "Optional site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy and nothing to look up. OMIT IT ENTIRELY and this call reads from that on-screen site; that is the PRIMARY path, not a fallback, and the turn's own surface resolves it server-side. Pass it only when the member explicitly named a DIFFERENT site and you took its id from page.list. Never pass a board, board-item, thread or any other id that merely happens to be nearby — those name different objects and will be refused.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The file's project-relative path exactly as page.list_files reported it (for example `src/pages/index.astro`). Never a leading slash, never `..`." }, "start_line": { "description": "The first line to read (1-based). Leave it out to start at the top; when the result says has_more, call again from end_line + 1.", "type": "integer", "minimum": 1 }, "max_lines": { "description": "How many lines to read, at most 200. A long file is read in windows; never guess the part you have not read.", "type": "integer", "minimum": 1, "maximum": 200 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "path" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "path": { "type": "string" }, "source_ref": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "binary" ] }, "size": { "type": "integer", "minimum": 0 }, "content": { "type": "string" }, "start_line": { "type": "integer", "minimum": 1 }, "end_line": { "type": "integer", "minimum": 0 }, "total_lines": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "has_more", "kind", "path", "site_id", "size", "source_ref", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.checkpoint": { "post": { "operationId": "call_page_checkpoint", "summary": "Call page.checkpoint", "description": "Say what has changed on a site and where it stands now — 'what did you change?', 'what have we got saved?', 'can I go back to before that?', 'why did the last build fail?', 'what version is this on?'. No site id is needed — it works on the site the member has open on screen. It reports where the site's source stands: the checkpoint it is at (current_source_ref — every edit is made from it), the ledger of checkpoints newest first with each one's build status and revision, and the newest build with its failure log tail when it failed. A checkpoint is made by every change to the site's files and by the member's save; use this to name a checkpoint for page.rollback, a revision for page.republish_revision, or to read why the last build failed. Not for undoing a change — that is `page.rollback`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "Optional site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy and nothing to look up. OMIT IT ENTIRELY and this call reads that on-screen site; that is the PRIMARY path, not a fallback, and the turn's own surface resolves it server-side. Pass it only when the member explicitly named a DIFFERENT site and you took its id from page.list. Never pass a board, board-item, thread or any other id that merely happens to be nearby — those name different objects and will be refused.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "current_source_ref": { "type": "string" }, "checkpoints": { "type": "array", "items": { "type": "object", "properties": { "source_ref": { "type": "string" }, "stored_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "type": "integer", "minimum": 0 }, "is_current": { "type": "boolean" }, "build_status": { "anyOf": [ { "type": "string", "enum": [ "queued", "pending", "running", "retrying", "succeeded", "failed" ] }, { "type": "null" } ] }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source_ref", "stored_at", "bytes", "is_current", "build_status", "revision" ], "additionalProperties": false } }, "truncated": { "type": "boolean" }, "latest_build": { "anyOf": [ { "type": "object", "properties": { "build_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_ref": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "pending", "running", "retrying", "succeeded", "failed" ] }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "log_tail": { "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "code", "log_tail", "truncated" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "build_run_id", "source_ref", "status", "revision", "failure" ], "additionalProperties": false }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "checkpoints", "current_source_ref", "latest_build", "site_id", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.domain_status": { "post": { "operationId": "call_page_domain_status", "summary": "Call page.domain_status", "description": "Answer 'is my domain live yet?' for a page — 'is my domain working', 'why isn't my domain connected', 'check my domain again'. Every address the page holds comes back with the domains card's state (Live, Waiting for record, Issuing certificate or Needs attention) and, when something is wrong, a reason that says why; relay the state and the reason in the member's words, and call a name connected only when its state is Live. A custom domain still settling is re-checked on the spot and the check is recorded, so checked_at is the time of this answer; if rechecked is false for a domain, say the state is the last one we recorded. It only reads and costs nothing. Not for a Goosy Grow domain use such as mail or links — that is `domain.status`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "hostname": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "state": { "type": "string", "enum": [ "live", "redirected_externally", "waiting_for_record", "issuing_certificate", "needs_attention" ] }, "state_label": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "state": { "type": "string" } }, "required": [ "key", "state" ], "additionalProperties": false } }, "checked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rechecked": { "type": "boolean" } }, "required": [ "hostname", "type", "status", "state", "state_label", "reason", "steps", "checked_at", "rechecked" ], "additionalProperties": false } }, "cname_target": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "cname_target", "domains", "site_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.connection_summary": { "post": { "operationId": "call_page_connection_summary", "summary": "Call page.connection_summary", "description": "Say where this workspace's articles get published when they do not go on our own site — 'where do my posts go?', 'is my WordPress connected?', 'which site do articles land on?'. Read where this workspace publishes articles when it does not publish natively — the connected WordPress or Webflow site. Call it before page.publish_article so you can name the destination. It returns no password or token, and none exists to ask for. Not for publishing the article — that is `page.publish_article`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "connected": { "type": "boolean" }, "platform": { "type": "string" }, "site_label": { "type": "string" }, "collection_id": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "connected", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.set_tracking": { "post": { "operationId": "call_page_set_tracking", "summary": "Call page.set_tracking", "description": "Make a form on one of the brand's Pages sites count as a conversion, or stop it counting, or turn one named tracking pixel off for that site, or back on — 'only count the application form as a conversion', 'turn the Meta pixel off here', 'don't track this page'. Call it from any screen: on a site's own page it acts on that site; elsewhere, read the named site's id with `page.list` first and pass it as site_id. A conversion change names conversion_forms, each form by the lowercase name it submits as its `form` field: only those forms' leads are reported to the ad platforms as conversions, and null puts every form back. A pixel change names provider and enabled; which pixels exist at all comes from the workspace's connections. If needs_republish comes back true, say the published version still carries the old tags until the page is republished. If rebuild_queued comes back false, do NOT say the pixel has stopped firing — the override is stored but no new build is on its way. Not for which Google Analytics conversions the performance cards show — that is `connections.set_conversion_events`; not for an imported site's cookie consent banner, or all of its ad pixels at once — that is `page.set_platform_properties`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "provider": { "description": "Which connected pixel to toggle. Use a provider key from page.read's pixels list — a provider we do not place is refused.", "type": "string" }, "enabled": { "description": "False takes the pixel off THIS page; true puts it back. Which pixels exist at all is decided by the workspace's Connections, not here.", "type": "boolean" }, "conversion_forms": { "description": "The forms whose leads count as conversions sent to the ad platforms, by the name each form submits as its `form` field — ['application'] makes only the application form a conversion. null makes every form one again; [] makes none. Omit to leave them as they are.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "disabled_providers": { "type": "array", "items": { "type": "string" } }, "needs_republish": { "type": "boolean" }, "rebuild_queued": { "type": "boolean" }, "conversion_forms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "site_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.set_share": { "post": { "operationId": "call_page_set_share", "summary": "Call page.set_share", "description": "Set the site's link preview: the title, text and card that other sites show when someone shares or links the site — a social post, a message, a search result. Reach for it when the member talks about a link preview, a shared link, a social post or a search result, or says \"when someone shares…\": 'change the share title', 'make the description say …', 'use the big picture card on X'. Call it on the ask, with no look at the files; the site's own code is not touched. Name only the fields the member asked to change. It does NOT change the share image (that is a picture edit) and cannot clear a field. Report each changed field and its new value; the live card updates on the next fetch. Not for the share image, or for what a page is called or listed as in the site's page list and navigation (\"call / name / list / show as …\") — that is `page.edit` or `page.set_page_label`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "description": "The title the site's link card should show, in the member's words. Omit it to leave the title as it is.", "type": "string", "minLength": 1, "maxLength": 1000 }, "description": { "description": "The description the site's link card should show, in the member's words. Omit it to leave the description as it is.", "type": "string", "minLength": 1, "maxLength": 1000 }, "twitter_card": { "description": "How X / Twitter lays out the card: summary_large_image is the wide picture card, summary the small square one. Omit it to leave the layout as it is.", "type": "string", "enum": [ "summary", "summary_large_image" ] }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "changed": { "type": "array", "items": { "type": "string", "enum": [ "title", "description", "twitter_card" ] } }, "share": { "type": "object", "properties": { "title": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "value", "source" ], "additionalProperties": false }, "description": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "value", "source" ], "additionalProperties": false }, "twitter_card": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "value", "source" ], "additionalProperties": false } }, "required": [ "title", "description", "twitter_card" ], "additionalProperties": false }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "changed", "share", "site_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.write_article": { "post": { "operationId": "call_page_write_article", "summary": "Call page.write_article", "description": "Put a finished article on a site's blog — 'add this post to the blog', 'put this write-up on my site', 'I want this article on the site'. Write a finished article into a site's blog. YOU write the article — pass the headline, a one-sentence summary and the body as subheadings with their paragraphs; nothing here generates copy for you. It does NOT publish: the post is stored and the site is rebuilt, and page.publish_article is what puts it in front of readers. If build_run_id is missing, say the rebuild has not started. Not for putting the article in front of readers — that is `page.publish_article`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The article headline, as it should appear. Write it — do not ask the tool to invent one." }, "summary": { "type": "string", "minLength": 1, "maxLength": 320, "description": "One sentence. It becomes the page's meta description and the archive card's summary, so make it describe the article rather than tease it." }, "sections": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "heading": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The subheading." }, "body": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1200 }, "description": "The paragraphs under this subheading." } }, "required": [ "heading", "body" ], "additionalProperties": false }, "description": "The article body, in order: each entry is a subheading plus its paragraphs. Plain text only — it is escaped, so markup is shown rather than rendered." }, "slug": { "description": "Optional URL slug. Leave it out to derive one from the title. A slug that already exists on this site is refused rather than suffixed — a second permanent URL is not what the operator asked for.", "type": "string", "maxLength": 72 }, "author_name": { "description": "Optional byline. Leave it out unless the operator named an author — an invented author is a claim on their site.", "type": "string", "maxLength": 120 }, "image_url": { "description": "Optional absolute https URL of the lead image. Leave it out unless the operator supplied one.", "type": "string" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "title", "summary", "sections" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "route": { "type": "string" }, "slug": { "type": "string" }, "source_ref": { "type": "string" }, "build_run_id": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "route", "site_id", "slug", "source_ref", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.ingest_bundle": { "post": { "operationId": "call_page_ingest_bundle", "summary": "Call page.ingest_bundle", "description": "Bring in a site the member already built somewhere else — 'import my existing site', 'I have a zip of my site', 'pull in the one I built in Webflow'. It takes a public https:// link to a .zip — either a finished build or a project we compile. Give it a site_id to replace an existing site, or leave it out to create a new one. It does NOT publish: say the site was imported, not that it is live. A private, local or metadata address is refused, and so is http:// — relay that refusal rather than retrying. If findings come back, they are advisory notes about search/AI discovery, never a failure of the import. The import_report says what we detected, what came across, what we changed to host it and what could not be brought over: relay those lists, never summarise them away. While import_report.status is \"compiling\" the site is still being built, so page_count is not yet the answer. Not for building a new site from scratch — that is `page.create`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "A full https:// link to a .zip of the site. It must be a public address — a link to a private network, a local address or a cloud metadata endpoint is refused, and so is http://. Pass the operator's link as given; never invent one." }, "site_id": { "description": "Optional. The EXISTING site to import into, replacing what is there. Leave it out to create a new site.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "description": "Optional name for the NEW site this import creates. Ignored when site_id is given.", "type": "string", "maxLength": 80 }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "site_name": { "type": "string" }, "kind": { "type": "string", "enum": [ "bundle", "prebuilt", "source" ] }, "revision": { "type": "string" }, "build_run_id": { "type": "string" }, "object_count": { "type": "integer", "minimum": 0 }, "page_count": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 }, "findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "rule", "severity", "path", "message" ], "additionalProperties": false } }, "import_report": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "staged", "compiling", "refused" ] }, "detected_kind": { "type": "string", "enum": [ "bundle", "prebuilt", "source:astro", "source:vite", "source:next", "source:static-generator", "not_a_site" ] }, "markers": { "type": "array", "items": { "type": "string" } }, "carried": { "type": "object", "properties": { "pages": { "type": "integer", "minimum": 0 }, "assets": { "type": "integer", "minimum": 0 }, "routes": { "type": "array", "items": { "type": "string" } } }, "required": [ "pages", "assets", "routes" ], "additionalProperties": false }, "approximated": { "type": "array", "items": { "type": "string" } }, "not_carried": { "type": "array", "items": { "type": "string" } }, "compile_log_tail": { "type": "string" }, "next_step": { "type": "string" } }, "required": [ "status", "detected_kind", "markers", "carried", "approximated", "not_carried" ], "additionalProperties": false }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "bytes", "findings", "import_report", "kind", "object_count", "page_count", "site_id", "site_name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.run_build": { "post": { "operationId": "call_page_run_build", "summary": "Call page.run_build", "description": "Build the site again and say what the build reports — 'try building it again', 'build it now', 'did that fix the build?', 'run it again and see if it works'. No site id is needed — it works on the site the member has open on screen. It builds the site's current checkpoint on the rail again — after a build failed for a reason you have fixed, or to re-run one. Every change to the site's files already builds, so you rarely need this. The tool waits a short while: a build that finishes in time answers with its outcome, and a FAILED build answers with the failing step's log tail — read it and fix the file it names. A build still running answers still_running: true with its run id; the member's editor shows the log as it lands, and page.checkpoint reports the outcome later. Not for reading why the last build failed without re-running it — that is `page.checkpoint`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The site to build, as the site_id `page.list` returned for it.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "source_ref": { "type": "string" }, "build_run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "pending", "running", "retrying", "succeeded", "failed" ] }, "revision": { "type": "string" }, "failure": { "type": "object", "properties": { "code": { "type": "string" }, "log_tail": { "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "code", "log_tail", "truncated" ], "additionalProperties": false }, "still_running": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "build_run_id", "site_id", "source_ref", "status", "still_running", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.restore_checkpoint": { "post": { "operationId": "call_page_restore_checkpoint", "summary": "Call page.restore_checkpoint", "description": "Undo a change to the site the member is working on — 'undo that', 'put it back how it was', 'I liked it better before', 'take that last change back', 'go back to before the build broke'. Every applied edit leaves a checkpoint, so this is the undo for anything that changed the site's source. This is the member's own working copy. No site id is needed — it works on the site the member has open on screen. It restores the site's DRAFT source to a previous checkpoint and rebuilds — the undo for any change to the site's files (name the checkpoint before it in page.checkpoint's ledger). The live site is untouched; the preview follows the rebuild. The checkpoint left behind stays in the ledger, so a rollback can itself be rolled back. A checkpoint whose archive is gone is refused; relay that and offer another. Not for the live site visitors see — that is `page.republish_revision`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "Optional site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy and nothing to look up. OMIT IT ENTIRELY and this call acts on that on-screen site; that is the PRIMARY path, not a fallback, and the turn's own surface resolves it server-side. Pass it only when the member explicitly named a DIFFERENT site and you took its id from page.list. Never pass a board, board-item, thread or any other id that merely happens to be nearby — those name different objects and will be refused.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "source_ref": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The checkpoint to go back to — a source_ref from page.checkpoint's ledger. This changes the DRAFT source and its preview only; the live site is untouched (page.republish_revision is the live one)." }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "source_ref" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "restored_from_ref": { "type": "string" }, "source_ref": { "type": "string" }, "base_source_ref": { "type": "string" }, "build_run_id": { "type": "string" }, "build_enqueue_error": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "base_source_ref", "restored_from_ref", "site_id", "source_ref", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.create": { "post": { "operationId": "call_page_create", "summary": "Call page.create", "description": "Make a brand-new website — 'build me a site for my consultancy', 'I need a landing page', 'make a website for the new product'. Create a multi-page website from a blueprint — home, about and contact with working navigation and the full search/AI discovery file set. Describe what the site is for with intent, or leave it out to get starter copy with no paid generation. When the member asked for the site themselves in this conversation it creates it at once — report what the result says; only a site nobody asked for raises its approval card first, which is the member's confirmation, and then it can still be refused. It does NOT publish either: the site is built, not put on the internet, and if build_run_id is missing say the build has not started yet — quoting build_enqueue_error as the reason when it is present, and offering to try the build again. If draft_error comes back and source_ref does not, NOTHING WAS DRAFTED: the site exists and is openable but empty, so say exactly that, quote the reason, and offer to try again ON THAT site_id — never call page.create a second time for the same request, which would leave the member with two pages. Not for changing a site that already exists — that is `page.edit`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Optional name for the site. Leave it out to take the default.", "type": "string", "maxLength": 80 }, "intent": { "description": "What this site is for, in the operator's own terms. Leave it out to get the blueprint's starter copy with no paid generation. Do not invent claims, offers or statistics. A site generated from the general-marketing template carries a lead-capture form on its landing page — email and name, with a consent line — so a request for one is met by creating the site and needs nothing here; anything else about the form (extra fields, different wording, moving it, or taking it off) is a page.edit once the site exists. Two states where a new site does NOT show one, and neither is a reason to tell the member they cannot have a form: a site copied from a saved blueprint carries whatever form that blueprint had, which may be none, and a form saved as `enabled: false` is stored but not rendered. In both cases a page.edit puts one on any page. IGNORED when blueprint_id names one of this workspace's saved blueprints: that path copies the saved template verbatim and runs no generation, so say the copy ran unchanged rather than implying these words shaped it.", "type": "string", "maxLength": 2000 }, "blueprint_id": { "description": "Which blueprint to start from — a first-party template id or one of this workspace's own saved blueprint ids, both listed by page.list with list 'templates'. Starting from a saved blueprint copies that template and runs no generation. Leave it out for the default general marketing site; an unknown id is refused server-side.", "type": "string" }, "inspiration_url": { "description": "Optional full https:// link to a site to take structural inspiration from. Its wording and offers are never reproduced. IGNORED when blueprint_id names one of this workspace's saved blueprints — that path copies a saved template and takes structure from nothing else.", "type": "string" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "blueprint_id": { "type": "string" }, "source_ref": { "type": "string" }, "draft_error": { "type": "string" }, "build_run_id": { "type": "string" }, "build_enqueue_error": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.patch_file": { "post": { "operationId": "call_page_patch_file", "summary": "Call page.patch_file", "description": "Change something on a site by writing its FILES — 'add more space between these cards', 'change the button text to Book a call', 'fix the typo in the footer', 'make the hero heading bigger'. This is the one way every site whose files we hold is changed, however it was made or brought in: copy, styling, layout, a component, a page. Read each file with page.read_file first — start from the selected element's file and line when the turn gives them, or from page.edit's `located`, or find the words with page.list_files and `contains` — and copy `find` text exactly; a hunk that matches nowhere or more than once refuses the whole call and nothing is written. No site id is needed — it works on the site the member has open on screen. One call is ONE saved version, so send a whole change in one call. While a live workbench is showing the site the change appears there in place and no build runs (the result says build_deferred; relay its build_hint); otherwise a build follows and takes a minute or two. The result is the diff (say what it shows, never more), the new source_ref and base_source_ref (page.rollback to it undoes this). Which directories are editable depends on the project: refusals name the reason, so relay them rather than retrying. Dependency manifests and lockfiles, build configuration, generated files, and anything under a build or tooling directory are always refused. A site whose files are READ-ONLY here is refused — page.list_files reports can_write: false for one, so check that before composing a patch. A change the member asked for in this conversation is written at once; only a change nobody asked for — or any change, when the member has asked to see each one first — raises its approval card, which is the member's confirmation, and is not made, saved or built unless they approve it there. Not for rewriting whole named files from an instruction — that is `page.edit_file`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "files": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 1024 }, "hunks": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string", "maxLength": 64000 }, "replace": { "type": "string", "maxLength": 64000 } }, "required": [ "find", "replace" ], "additionalProperties": false } } }, "required": [ "path", "hunks" ], "additionalProperties": false } }, "expected_source_ref": { "type": "string" }, "summary": { "type": "string", "maxLength": 2000 }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "files" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "source_ref": { "type": "string" }, "base_source_ref": { "type": "string" }, "build_run_id": { "type": "string" }, "build_enqueue_error": { "type": "string" }, "build_deferred": { "type": "boolean" }, "workbench_pushed": { "type": "boolean" }, "build_hint": { "type": "string" }, "changed_paths": { "type": "array", "items": { "type": "string" } }, "diff": { "type": "string" }, "diff_truncated": { "type": "boolean" }, "selected_element": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.edit_file": { "post": { "operationId": "call_page_edit_file", "summary": "Call page.edit_file", "description": "Change named files of a site from an instruction — 'redo the pricing section in Pricing.astro', 'rewrite this component', 'change the hero copy in src/components/Hero.astro', 'restructure that page's markup'. Goosy's coding agent makes the change in the site's files in place, starting from the files named in paths, and the result is one checkpoint (page.rollback undoes it) with the agent's own one-line summary — relay that, never more. It works on every site whose files we hold, however it was made or brought in; a site whose files are READ-ONLY here is refused, and so are dependency manifests, lockfiles, build configuration and generated files. Each call is a paid authoring run on the site's own plan, and it raises its approval card first, which is the member's confirmation. While a live workbench is showing the site the change appears there and no build runs (the result says build_deferred; relay its build_hint); otherwise a build follows. Not for a change of a few exact lines you already have — that is `page.patch_file`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "paths": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "instruction": { "type": "string", "minLength": 1, "maxLength": 2000 }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "paths", "instruction" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "source_ref": { "type": "string" }, "build_run_id": { "type": "string" }, "summary": { "type": "string" }, "build_deferred": { "type": "boolean" }, "workbench_pushed": { "type": "boolean" }, "build_hint": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.schedule_publish": { "post": { "operationId": "call_page_schedule_publish", "summary": "Call page.schedule_publish", "description": "Put a site live at a chosen time instead of now — 'publish it on Monday morning', 'schedule this to go live at 9am', 'put it up next Tuesday'. Schedule a page to publish at a chosen time. Send `at` as an ISO-8601 timestamp WITH its UTC offset, resolved against the member's own timezone. It must be at least five minutes away and within the next year. This is a public, consequential act. Call it on the ask: it raises the approval card showing the page's name, its address and the time being committed to, which is the member's confirmation. Never say a page is scheduled unless the result says it is. If `replaced` is true, say you moved an existing schedule rather than adding a second one. Not for publishing right now — that is `page.publish`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "at": { "type": "string", "minLength": 1, "description": "When to publish, as an ISO-8601 timestamp that INCLUDES the UTC offset (for example 2026-09-08T09:00:00-06:00). Never send a bare local time — it would be read as UTC and the page would publish at the wrong hour. Resolve the operator's words against their timezone and state the time back to them in their own words. It must be at least five minutes from now and within the next year." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "at" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "at": { "type": "string" }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hostname": { "type": "string" }, "replaced": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.cancel_scheduled_publish": { "post": { "operationId": "call_page_cancel_scheduled_publish", "summary": "Call page.cancel_scheduled_publish", "description": "Call off a publish that was scheduled for later — 'cancel that scheduled publish', 'don't put it live tomorrow after all', 'stop it going out on Friday'. Call off a page's scheduled publish. If `cancelled` is true, say the scheduled publish has been called off. If it is false, nothing was waiting — say so plainly (it may have already published, or already been cancelled) rather than reporting an error; either way the page will not publish on a timer. Not for moving the publish to another time — that is `page.schedule_publish`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "cancelled": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.publish_article": { "post": { "operationId": "call_page_publish_article", "summary": "Call page.publish_article", "description": "Publish an article that has already been written — 'publish that blog post', 'send the article to our WordPress'. target 'native' publishes it on the site hosted here; 'byo' sends the article to the brand's own connected WordPress or Webflow site; 'both' does each. This is irreversible in front of readers. Call it on the ask: it raises the approval card showing where the article would land, which is the member's confirmation. If the result carries 'skipped', say plainly which half did NOT happen and why. Not for writing the article — that is `page.write_article`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "route": { "type": "string", "description": "The article's route on the site, e.g. /blog/how-we-ship. page.write_article returns it." }, "target": { "description": "Where to publish: 'native' puts the RevAStack site itself on the internet, 'byo' pushes the article to the workspace's connected WordPress or Webflow site, 'both' does each. Omit for 'native'.", "type": "string", "enum": [ "native", "byo", "both" ] }, "publish_live": { "description": "BYO only. Leave it out or pass false to create the article as a draft on the connected site for review; true publishes it to readers immediately, which cannot be undone from here.", "type": "boolean" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "route" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "route": { "type": "string" }, "native_url": { "type": "string" }, "external_id": { "type": "string" }, "external_status": { "type": "string" }, "skipped": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.publish_as_blueprint": { "post": { "operationId": "call_page_publish_as_blueprint", "summary": "Call page.publish_as_blueprint", "description": "Save one of this workspace's sites as a template to start new sites from — 'save this as a template', 'I want to reuse this layout', 'make this the starting point for the next one'. Save one of this workspace's sites as a reusable template, so new sites can be created from a copy of it with this brand's name and colours substituted in. It does NOT put anything on the internet — the site's own live address is unchanged — and it copies the site's most recent BUILT version, so a site that has never finished a build is refused. Pass blueprint_id only to update a template that already exists. Not for withdrawing a saved template — that is `page.retire_blueprint`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What the gallery calls this template. Unique within the workspace — a name already in use is refused, so ask the operator for another rather than inventing a variation." }, "description": { "description": "Optional one line on what the template is for, shown under its name.", "type": "string", "maxLength": 500 }, "blueprint_id": { "description": "Only when UPDATING a template that already exists — the saved blueprint's UUID, from page.list with list 'templates'. This re-points it at the site's newest built version. Leave it out to save a NEW template.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "blueprint_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "status": { "type": "string" }, "source_revision_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "updated": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.retire_blueprint": { "post": { "operationId": "call_page_retire_blueprint", "summary": "Call page.retire_blueprint", "description": "Stop offering one of this workspace's saved templates — 'retire that template', 'take that starting point off the list', 'we shouldn't use that one any more'. Stop offering one of THIS WORKSPACE's saved templates. Sites already created from it are completely unaffected and keep working; the template is only withdrawn from the list of things a new site can be created from. If it was already retired, say so rather than implying anything changed. ⚠️ page.list shows templates this workspace cannot retire — ones another workspace in the account published, and ours that ship to every account. Only call this for a row whose `retirable` is true; for any other, tell the member whose it is instead of attempting it. Not for saving a site as a template — that is `page.publish_as_blueprint`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "blueprint_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$", "description": "One of this workspace's SAVED blueprints, as a UUID. page.list with list 'templates' returns them by name; a built-in template id (a slug like general-marketing) is NOT one of these and is refused." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "blueprint_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "blueprint_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "status": { "type": "string" }, "changed": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.create_preview_link": { "post": { "operationId": "call_page_create_preview_link", "summary": "Call page.create_preview_link", "description": "Give the member a private link so they can show a site to someone before it goes live — 'send me a link I can share', 'can my client see this first?', 'I want to show someone before publishing'. Issue a shareable preview link for a page — an unguessable, expiring URL that shows one revision WITHOUT publishing it. Nothing goes live and no address changes. Give the member the whole url immediately and say when it expires: it is shown once and cannot be looked up again. If the revision is not the live one, say so. Not for letting one person past a password — that is `page.mint_access_link`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "revision": { "type": "string" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.revoke_preview_link": { "post": { "operationId": "call_page_revoke_preview_link", "summary": "Call page.revoke_preview_link", "description": "Kill a preview link so it stops opening the site — 'cancel that share link', 'stop that link working', 'revoke the preview I sent out'. Kill a shareable preview link so it stops opening the page. Pass the token from the link — nothing stores it, so it has to come from this conversation or from the member. A link that had already expired reports the same success; say the link no longer works either way, and do not repeat the token back. Not for making a new preview link — that is `page.create_preview_link`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "token": { "type": "string", "minLength": 1, "description": "The token from the preview link — the last path segment of the URL, or the whole URL if that is what the operator gave you. Nothing stores it, so it must come from the conversation or from them." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "revoked": { "type": "boolean" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.set_password": { "post": { "operationId": "call_page_set_password", "summary": "Call page.set_password", "description": "Put a password in front of a published site — 'password-protect this page', 'only people with the password should see it', 'lock this site down'. Put one shared password in front of a page that is already published. Anyone with the address must type it to get in. Setting or changing it immediately kills every private link and every visitor's saved unlock, so say that. Never repeat the password back in your reply, and never suggest one — use exactly what the member gave you. Not for letting one person in without the password — that is `page.mint_access_link`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "password": { "type": "string", "minLength": 8, "maxLength": 256, "description": "The password visitors will type, 8-256 characters. Use exactly what the operator gave you — never invent one, never suggest one, and do not repeat it back in your reply." }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "required": [ "password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "access_version": { "type": "integer" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.clear_password": { "post": { "operationId": "call_page_clear_password", "summary": "Call page.clear_password", "description": "Take the password off a site so anyone with the address can read it — 'make this page public again', 'remove the password', 'anyone should be able to see it'. Remove the password from a page, making it readable by anyone with the address. It makes the page PUBLIC: afterwards say plainly that it is now public and that every private link for it has stopped working. Not for letting one person in while keeping the password — that is `page.mint_access_link`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "access_version": { "type": "integer" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/page.mint_access_link": { "post": { "operationId": "call_page_mint_access_link", "summary": "Call page.mint_access_link", "description": "Let one person past a site's password without telling them the password — 'let my client in without the password', 'send them a private way in', 'give this one person access'. Mint a private link that lets one person past a page's password without knowing it. Only works on a page that HAS a password. Give the member the whole url immediately and say when it expires: it is shown once and cannot be looked up again. Setting or clearing the password kills it. Not for a preview of a version that is not live — that is `page.create_preview_link`. Over the API it answers in two calls: without confirmation_id it proposes — says what would happen, returns a confirmation_id and changes, spends and sends nothing; the same arguments again with that confirmation_id, on a member's own API key, do it.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "page" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "description": "The SITE the member means, as a site UUID. You are NOT shown the id of the site open on screen — it never appears in your context, so there is nothing to copy. When they say 'this site', 'the site I'm looking at', or name no site at all, they mean that on-screen site, and the way to reach it is: where this schema leaves site_id OPTIONAL, OMIT IT ENTIRELY — that is the primary path, not a fallback, and the turn's own surface resolves it server-side. Where the schema REQUIRES it, call page.list with `name` set to the site they named — it returns that one site's id, or the candidates to ask them about. Never pass a board, board-item, thread or any other id that merely happens to be nearby in the conversation — those name different objects and will be refused — and never one you composed.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ttl_minutes": { "description": "Optional. How many minutes the link should last. The action clamps it into the allowed range; omit for the default.", "type": "integer", "exclusiveMinimum": 0 }, "confirmation_id": { "description": "Omit to propose: the first call says what would happen, returns a confirmation_id and changes nothing. To go ahead, send the same arguments again with that confirmation_id, on a member's own API key; a service account's key can propose but never confirm.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workspace": { "description": "Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The call was admitted and dispatched. `ok` says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "x-goosy-tool-error": { "description": "`true` when a boundary step refused the call — workspace resolution failed or could not be read. A tool that ran and returned its own typed `ok: false` reports `false` here. **Branch on `ok` in the body for the outcome; this header is the transport-level hint.**", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "The tool ran and answered.", "properties": { "ok": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "confirmation_required" }, "confirmation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_summary": { "type": "string", "description": "What will happen, in one sentence, for a person to approve before confirming." }, "site_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "expires_at": { "type": "string" }, "workspace": { "type": "string", "description": "The slug of the workspace this call ran in." }, "working_in": { "type": "object", "properties": { "label": { "type": "string", "description": "The chip words — e.g. \"working in: Acme Main\"." }, "note": { "type": "string", "description": "Why this workspace — e.g. \"your default\", \"this call only\"." }, "workspace": { "type": "string", "description": "The resolved workspace's slug." }, "source": { "type": "string", "enum": [ "call-override", "key-pin", "stored-default", "sole-reachable" ], "description": "Which rung of the R7 precedence resolved the workspace." } }, "required": [ "label", "note", "workspace", "source" ], "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.", "additionalProperties": false } }, "required": [ "ok", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request could not be used: the body is present but not a JSON object (`tenant_api.malformed_body`); it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`); or the `Idempotency-Key` header is malformed (`tenant_api.idempotency_key_invalid`), disagrees with the body's `idempotency_key` (`tenant_api.idempotency_key_conflict`), or was sent to an action that cannot replay a retry (`tenant_api.idempotency_unsupported`). Nothing ran.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No bearer credential, or one that did not resolve. Deliberately ONE undifferentiated answer for absent / unknown / revoked / expired, so the endpoint is never an oracle over the key space.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential is good but the surface is not open to it — the platform or account API switch is off, or the holder lacks the `api.access` capability. The `code` says which.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such tool. The body names no tool and is identical for every unrecognised name.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over this key's per-minute cap. Carries `Retry-After` and `error.retry_after_seconds`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "x-request-id": { "description": "This request's id: the `x-request-id` you sent when it was well formed, otherwise one generated for you. Quote it to support; it is recorded on every audit row the call wrote.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745: this refusal's nested `error` object is deprecated, since this instant (`@`).", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594: the nested `error` object may be removed after this date (2026-12-31).", "schema": { "type": "string" } }, "Link": { "description": "The page that says what to read instead (`rel=\"deprecation\"`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests this key may make in a rolling minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Remaining": { "description": "Requests left in the current rolling minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Reset": { "description": "Whole seconds until the window frees more requests.", "schema": { "type": "integer", "minimum": 1 } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tools/workspace_sets.create": { "post": { "operationId": "call_workspace_sets_create", "summary": "Call workspace_sets.create", "description": "Name a group of brands in this account so a command can address it later ('post this to the north america set'). Say which brands ONE way: the specific brands they picked, every brand of a business type, or every brand set up from one template. The operator sees an approve card naming the group and the brands it covers before anything is created: never say the group exists until the result says so. Requires the sharing permission (Owner/Admin by default). Not for changing a group that already exists — that is `workspace_sets.update`.\n\nEvery result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with `workspace_ambiguous` and lists the choices — offer them, never pick one.", "tags": [ "workspace_sets" ], "parameters": [ { "name": "x-request-id", "in": "header", "required": false, "description": "Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from `A–Z a–z 0–9 . _ : -`, starting with a letter or digit; anything else is replaced by a generated id.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What the operator calls this group of brands, in their words — 'North America', 'The three new locations'." }, "selector": { "anyOf": [ { "type": "object", "properties": { "workspace_ids": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Brand ids, from workspace_sets.list_brands (or workspace_sets.list, or the surface context) — never invented." } }, "required": [ "workspace_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "company_type": { "type": "string", "description": "A business-type key, from assets.list_company_types — never invented." } }, "required": [ "company_type" ], "additionalProperties": false }, { "type": "object", "properties": { "template_links_of": { "type": "string", "description": "The id of the TEMPLATE brand whose set-up-from-it brands make the set." } }, "required": [ "template_links_of" ], "additionalProperties": false } ], "description": "Exactly ONE of: {workspace_ids:[...]} the brands they picked · {company_type:'...'} every brand of that business type · {template_links_of:'