{ "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. 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": { "error": { "type": "object", "properties": { "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": { "type": "number", "description": "On a 429: whole seconds to wait. Mirrors `Retry-After`." } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "description": "A request the boundary refused before dispatching anything. The same shape the MCP endpoint answers its own refusals with, so one client branch covers both transports." }, "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": { "type": "array", "items": { "type": "string" }, "description": "On a workspace refusal: the slugs this key may pass as `workspace`." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false }, "description": "On `invalid_arguments`: which fields failed, and why." } }, "required": [ "ok", "code", "message" ], "additionalProperties": false, "description": "A call that was admitted and dispatched, and did not succeed." }, "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" ], "additionalProperties": false, "description": "A Pages preview-link request that did not succeed." }, "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" ], "additionalProperties": false, "description": "A Pages asset upload that did not succeed." } } }, "paths": { "/api/v1/tools/content.status": { "post": { "operationId": "call_content_status", "summary": "Call content.status", "description": "Read where this workspace's content stands — 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.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "variants_in_progress", "ready", "approved", "scheduled", "publishing", "published", "verified", "failed" ], "description": "Only pieces in this lifecycle state." }, "format": { "type": "string", "enum": [ "posts", "stories", "shorts_clips", "long_form", "articles", "podcast" ], "description": "Only pieces of this format." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "How many pieces to return, newest-updated first." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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", "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." }, "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": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "counts", "pieces", "total", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 — the format rows the active cadence plans, every piece bucketed into its day column, and the zone those columns are in. This is the same grid /schedule draws, so the answer and the screen always agree.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "week": { "type": "string", "description": "Any date in the wanted week, as YYYY-MM-DD. Omit for the current week." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "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": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "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 body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 — 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.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Match items whose name contains this text. Omit to browse the shelf." }, "roll": { "type": "string", "enum": [ "images", "clips", "videos", "documents" ], "description": "Only this shelf. Omit to search all of them." }, "pinned_only": { "type": "boolean", "description": "Only items someone has pinned." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25, "description": "How many items to return. Pinned items come first." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "null" ] }, "finalized_at": { "type": [ "string", "null" ], "description": "When it was promoted into the library." }, "source_board_id": { "type": [ "string", "null" ], "description": "The board it was made on, when that board still exists." }, "source_board_name": { "type": [ "string", "null" ] }, "preview_image_generation_id": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "items", "search_window", "total", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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. Use it to confirm an item still exists and to see where it was made before you reference 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": [ "library" ], "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": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "null" ] }, "finalized_at": { "type": [ "string", "null" ], "description": "When it was promoted into the library." }, "source_board_id": { "type": [ "string", "null" ], "description": "The board it was made on, when that board still exists." }, "source_board_name": { "type": [ "string", "null" ] }, "preview_image_generation_id": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "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 body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 — 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.\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" ], "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": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "How many chunks to return, closest match first." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "hits", "query", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 — 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. Connecting an account is an operator decision made on screen, so there is no connect verb 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": [ "connections" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "null" ], "description": "Which account or grant it rides, when it names one." }, "note": { "type": [ "string", "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": { "type": [ "string", "null" ], "description": "Which account or grant it rides, when it names one." }, "note": { "type": [ "string", "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": { "type": [ "string", "null" ], "description": "Which account or grant it rides, when it names one." }, "note": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "available", "coming_soon", "connected", "counts", "needs_attention", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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. Say the figure back exactly as given — never work one out or recall one. Topping up is done by a person on Settings → Billing; you cannot do it here.", "tags": [ "credits" ], "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-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 body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 — 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.\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" ], "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": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A working title. Omit to leave it untitled." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "null" ], "description": "When it is planned to publish, ISO 8601 UTC." }, "week_block_id": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "filled_planned_slot", "format", "piece_id", "scheduled_for", "week_block_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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. This is the only thing it changes — it never edits, regenerates, moves or removes the work itself, and there is no verb here that can.\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" ], "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": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "id", "name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 images onto a board in this workspace. This SPENDS CREDITS, so it takes two calls: the first returns what would be made plus a confirmation id and charges nothing, and the second — carrying that id back — is what actually runs it. There is no way to run it in one call, by design.\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" ], "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": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "How many images to make. Each one costs credits." }, "shape": { "type": "string", "enum": [ "1:1", "3:4", "4:3", "9:16", "16:9" ], "description": "The aspect ratio. Omit for the workspace default." }, "confirmation_id": { "type": "string", "description": "Leave this out on the first call: the answer will describe the run and hand you an id. Send that id back, unchanged, to actually run it." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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 }, "status": { "type": "string", "enum": [ "confirmation_required", "dispatched" ], "description": "confirmation_required — nothing ran and nothing was charged; dispatched — the run is under way." }, "confirmation_id": { "type": [ "string", "null" ], "description": "Present only while confirmation is required. Send it back on the second call." }, "request_summary": { "type": [ "string", "null" ], "description": "Present only while confirmation is required — what will be made, in one sentence, for a person to approve." }, "count": { "type": "integer", "description": "How many images this run covers." }, "aspect_ratio": { "type": "string" }, "board_id": { "type": "string" }, "run_id": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "aspect_ratio", "board_id", "confirmation_id", "count", "request_summary", "run_id", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 existing image on a board in this workspace. This spends credits and requires two calls: request a confirmation, then return its id to dispatch the recorded 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": [ "images" ], "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": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "How many images to make. Each one costs credits." }, "shape": { "type": "string", "enum": [ "1:1", "3:4", "4:3", "9:16", "16:9" ], "description": "The aspect ratio. Omit for the workspace default." }, "confirmation_id": { "type": "string", "description": "Leave this out on the first call: the answer will describe the run and hand you an id. Send that id back, unchanged, to actually run it." }, "parent_generation_id": { "type": "string", "format": "uuid", "description": "The existing image on this board to edit." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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 }, "status": { "type": "string", "enum": [ "confirmation_required", "dispatched" ], "description": "confirmation_required — nothing ran and nothing was charged; dispatched — the run is under way." }, "confirmation_id": { "type": [ "string", "null" ], "description": "Present only while confirmation is required. Send it back on the second call." }, "request_summary": { "type": [ "string", "null" ], "description": "Present only while confirmation is required — what will be made, in one sentence, for a person to approve." }, "count": { "type": "integer", "description": "How many images this run covers." }, "aspect_ratio": { "type": "string" }, "board_id": { "type": "string" }, "run_id": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "aspect_ratio", "board_id", "confirmation_id", "count", "request_summary", "run_id", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 2000 }, "input": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "citations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "excerpt": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "additionalProperties": false }, "maxItems": 32 } }, "required": [ "text" ], "additionalProperties": false }, "confirmation_id": { "type": "string", "format": "uuid", "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required for a new non-confirmation managed API call." }, "requestedOutputTokens": { "type": "integer", "exclusiveMinimum": 0, "description": "Required for an initial text request and bounded by the admitted policy." }, "tier": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional configured writing tier. Omit to use the grant default." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "mode": { "type": "string", "enum": [ "answer", "semantic", "serp" ], "default": "answer" }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }, "freshnessDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "includeDomains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 10 }, "excludeDomains": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "maxItems": 10 }, "confirmation_id": { "type": "string", "format": "uuid", "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required for a new non-confirmation managed API call." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 bounded managed web page for the credential-bound workload.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "confirmation_id": { "type": "string", "format": "uuid", "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required for a new non-confirmation managed API call." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 bounded managed image references for the credential-bound workload.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 300 }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }, "imageType": { "type": "string", "enum": [ "face", "photo" ] }, "size": { "type": "string", "enum": [ "medium", "large" ] }, "aspect": { "type": "string", "enum": [ "square", "tall", "wide" ] }, "usageRights": { "type": "string", "enum": [ "creative_commons_licenses", "commercial_or_other_licenses" ] }, "confirmation_id": { "type": "string", "format": "uuid", "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required for a new non-confirmation managed API call." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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": "Acquire one managed image search result into the credential-bound site 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": [ "images" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "searchRequestId": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "minimum": 1 }, "confirmation_id": { "type": "string", "format": "uuid", "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required for a new non-confirmation managed API call." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 the current workspace's project and board tree through a bearer-key API principal. The result supplies the board ids used by board.move.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "minLength": 1, "maxLength": 40 }, "root_board_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, "name": { "type": "string" }, "kind": { "type": "string" }, "parent_board_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "answer_note", "roots", "truncated", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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.create_folder": { "post": { "operationId": "call_board_create_folder", "summary": "Call board.create_folder", "description": "Create one named project in the resolved workspace, with a required idempotency key so retrying the same request cannot create a duplicate.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parent_board_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A stable caller-chosen identity for safe retries of this create." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "required": [ "name", "idempotency_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-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" }, "name": { "type": "string" }, "parent_board_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "answer_note", "board_id", "name", "parent_board_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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.move": { "post": { "operationId": "call_board_move", "summary": "Call board.move", "description": "Move one named board into a project or to the workspace tree root, after resolving its current parent from the same workspace's tree.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid" }, "to_parent_board_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "from_parent_board_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "required": [ "board_id", "to_parent_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-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" }, "name": { "type": "string" }, "from_parent_board_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "to_parent_board_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "answer_note", "board_id", "from_parent_board_id", "name", "to_parent_board_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 and place it on an existing board, or create its board through the canonical board creator.\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" ], "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": { "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" ], "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": { "type": "boolean", "description": "Leave it out unless a row is meaningless without this column." }, "source": { "type": "string", "maxLength": 80, "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." } }, "required": [ "key", "label", "type" ], "additionalProperties": false, "description": "One typed column of a data table." }, "maxItems": 100, "description": "The typed header. At most 100 columns. Every column key must be unique in the table." }, "board_id": { "type": "string", "format": "uuid", "description": "The project board this table lands on — take it from `board.tree`, never invent one. Leave it out and a new board is created for it." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "type": "string", "minLength": 1, "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." } }, "required": [ "name", "columns", "idempotency_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-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": { "type": [ "string", "null" ] }, "board_item_id": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "board_id", "board_item_id", "column_count", "name", "table_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 the typed Data tables in this workspace, optionally narrowed to one table or one 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": [ "data" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "description": "The table to describe." }, "board_id": { "type": "string", "format": "uuid", "description": "Describe every data table on this board instead of one table by id." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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": { "type": [ "string", "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": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "type", "required", "source" ], "additionalProperties": false } }, "sources": { "type": "object", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "tables", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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": "Query rows from one Data table using the same named-column filters, ordering and cursor contract as the product grid.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "description": "The table being asked about." }, "has_value_in": { "type": "array", "items": { "type": "string" }, "description": "Only rows that HAVE a value in every one of these columns." }, "missing_value_in": { "type": "array", "items": { "type": "string" }, "description": "Only rows with NO value in any one of these columns — this is how you answer 'which of these have no phone?'." }, "equals": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Column key to exact value. Only for columns that exist on the table." }, "order_by": { "type": "string", "description": "A column key to sort by. Leave it out for the natural order." }, "descending": { "type": "boolean", "description": "Sort the other way." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "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." }, "cursor": { "type": "string" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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", "additionalProperties": {} }, "source": { "type": "string" } }, "required": [ "row_id", "values", "source" ], "additionalProperties": false } }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "count_line", "returned", "rows", "table_id", "total", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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": "Append one validated manual row to a Data table. Reusing the same idempotency key never creates a second row.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid", "description": "The table gaining a row." }, "values": { "type": "object", "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 }, "workspace": { "type": "string", "minLength": 1, "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." } }, "required": [ "table_id", "values", "idempotency_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-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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "row_count", "row_id", "table_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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": "Update one cell while validating the complete row against the table schema.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid" }, "row_id": { "type": "string", "format": "uuid" }, "column_key": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ] }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "column_key", "row_id", "table_id", "values", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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": "Replace the explicit list of columns a public Page may read. Nothing is published implicitly.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table_id": { "type": "string", "format": "uuid" }, "published_columns": { "type": "array", "items": { "type": "string" } }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "published_columns", "table_id", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 the resolved workspace.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, "name": { "type": "string" }, "status": { "type": "string" }, "hostname": { "type": [ "string", "null" ] }, "published_revision": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" }, "latest_revision": { "type": [ "string", "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" }, { "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "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 body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 the sanitized durable status of one build after proving it belongs to this page.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid" }, "build_run_id": { "type": "string", "minLength": 1 }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, "build_run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "retrying" ] }, "revision": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "build_run_id", "revision", "site_id", "status", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 or confirm publication of one exact built revision to the public internet.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid" }, "confirmation_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, "revision": { "type": "string" }, "confirmation_id": { "type": "string", "format": "uuid" }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "revision", "site_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 belonging to a specific Page in the resolved workspace.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "string", "format": "uuid" }, "lead_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, "site_id": { "type": "string", "format": "uuid" }, "fields": { "type": "object", "additionalProperties": {} }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "submitted_at": { "type": "string" }, "crm_status": { "type": "string", "enum": [ "pending", "synced", "skipped", "failed" ] }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "crm_status", "email", "fields", "lead_id", "name", "site_id", "submitted_at", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 the resolved workspace with a stable retry identity.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_project_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "type": "string", "minLength": 1, "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." } }, "required": [ "idempotency_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-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" }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "board_id", "created", "name", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 or confirm one complete draft version on an existing automation board. Confirmation validates connector bindings, builder availability, the graph, and the trigger before writing.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 600 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 400 }, "kind": { "type": "string", "enum": [ "automated", "approval", "code_step", "delay", "conversation", "wait_for_event" ], "default": "automated" }, "implementation": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$" }, "params": { "type": "object", "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": { "type": "string", "minLength": 1, "maxLength": 32 }, "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 } }, "promptFirst": { "type": "boolean", "default": true } }, "required": [ "key", "label" ], "additionalProperties": false }, "minItems": 1, "maxItems": 24 }, "edges": { "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": {} }, "required": [ "from", "to" ], "additionalProperties": false }, "maxItems": 64 }, "trigger": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "manual" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "schedule" }, "cron": { "type": "string", "minLength": 1, "maxLength": 120 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind", "cron", "timezone" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "app_event" }, "event_key": { "type": "string", "minLength": 1, "maxLength": 120 }, "changed_fields": { "type": "array", "items": { "type": "string", "enum": [ "email", "name", "phone" ] }, "minItems": 1, "maxItems": 3 }, "date_field": { "type": "string", "enum": [ "date_of_birth" ] }, "offset_days": { "type": "integer", "minimum": 0, "maximum": 60 }, "pipeline_stage_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 40 } }, "required": [ "kind", "event_key" ], "additionalProperties": false } ] }, "review_gated": { "type": "boolean" }, "confirmation_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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", "saved" ] }, "board_id": { "type": "string", "format": "uuid" }, "expected_latest_version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "confirmation_id": { "type": "string", "format": "uuid" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "board_id", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 or confirm activation of one exact reviewed automation 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": [ "automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "type": "string", "format": "uuid" }, "confirmation_id": { "type": "string", "format": "uuid" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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", "activated" ] }, "board_id": { "type": "string", "format": "uuid" }, "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" }, "confirmation_id": { "type": "string", "format": "uuid" }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "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 body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 intersection.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "site" }, "site_id": { "type": "string", "format": "uuid" } }, "required": [ "kind", "site_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "workflow" }, "workflow_definition_id": { "type": "string", "format": "uuid" }, "workflow_definition_version_id": { "type": "string", "format": "uuid" } }, "required": [ "kind", "workflow_definition_id", "workflow_definition_version_id" ], "additionalProperties": false } ] }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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", "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "type": "array", "items": {} }, { "type": "object", "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" }, "account_policy_id": { "type": "string", "format": "uuid" }, "project_policy_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "operation_keys": { "type": "array", "items": { "type": "string" } }, "allowed_tiers": { "type": "array", "items": { "type": "string" } }, "default_tier": { "type": [ "string", "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 }, "standing_approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "disclosure_summary": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "standing_automation_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "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", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "effective", "operations", "writing_tiers", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 or confirm one exact managed policy, grant, standing approval, workflow enrollment, or revocation.\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" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "policy" }, "policy": { "anyOf": [ { "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" }, { "type": "null" } ] }, "operation_keys": { "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" ] }, "minItems": 1 }, "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" }, "project_board_id": { "type": "string", "format": "uuid" }, "policy_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "operation_keys": { "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" ] }, "minItems": 1 }, "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" }, "project_policy_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "previous_grant_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "target": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "site" }, "site_id": { "type": "string", "format": "uuid" }, "target_board_id": { "type": "string", "format": "uuid" } }, "required": [ "kind", "site_id", "target_board_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "workflow" }, "workflow_definition_id": { "type": "string", "format": "uuid" }, "workflow_definition_version_id": { "type": "string", "format": "uuid" }, "target_board_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "kind", "workflow_definition_id", "workflow_definition_version_id", "target_board_id" ], "additionalProperties": false } ] }, "operation_keys": { "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" ] }, "minItems": 1 }, "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 } }, "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" }, "disclosure_summary": { "type": "string", "minLength": 1 }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "standing_automation_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "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" } }, "required": [ "kind", "grant_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "standing_approval_revoke" }, "standing_approval_id": { "type": "string", "format": "uuid" } }, "required": [ "kind", "standing_approval_id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "workflow_enrollment" }, "site_grant_id": { "type": "string", "format": "uuid" }, "workflow_grant_id": { "type": "string", "format": "uuid" }, "standing_automation_id": { "type": "string", "format": "uuid" }, "site_standing_approval_id": { "type": "string", "format": "uuid" }, "workflow_standing_approval_id": { "type": "string", "format": "uuid" }, "previous_enrollment_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "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" }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "disclosure_summary": { "type": "string" }, "policy_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "activated": { "type": "boolean" }, "grant_id": { "type": "string", "format": "uuid" }, "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" }, "enrollment_id": { "type": "string", "format": "uuid" }, "workflow_definition_id": { "type": "string", "format": "uuid" }, "workflow_definition_version_id": { "type": "string", "format": "uuid" }, "service_actor_user_id": { "type": "string", "format": "uuid" }, "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "kind", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 to a synchronous terminal result.\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" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enrollmentId": { "type": "string", "format": "uuid" }, "input": { "type": "object", "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ] }, "default": {} }, "confirmation_id": { "type": "string", "format": "uuid", "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required for a new non-confirmation managed API call." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "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 durable status of one managed automation 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": [ "workflow" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "invocationRequestId": { "type": "string", "format": "uuid" }, "confirmation_id": { "type": "string", "format": "uuid", "description": "Confirms the stored exact call. When supplied, the stored request replaces all other body fields." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required for a new non-confirmation managed API call." }, "workspace": { "type": "string", "minLength": 1, "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." } }, "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-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" }, { "type": "null" } ] }, "expires_in_seconds": { "type": "integer", "exclusiveMinimum": 0 }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "succeeded", "failed", "uncertain", "running" ] }, { "type": "null" } ] }, "response": { "anyOf": [ {}, { "type": "null" } ] }, "error_code": { "type": [ "string", "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" ], "additionalProperties": false, "description": "Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result." } }, "required": [ "ok", "state", "working_in", "workspace" ] }, { "$ref": "#/components/schemas/ToolRefusal" } ] } } } }, "400": { "description": "The request body could not be used: it is present but not a JSON object (`tenant_api.malformed_body`), or it is a top-level array carrying more messages than this endpoint accepts (`tenant_mcp.batch_too_large`). Send the tool's arguments as a JSON object, or omit the body entirely.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/pages/{siteId}/preview-links": { "post": { "operationId": "createPagePreviewLink", "summary": "Create a Pages preview link", "description": "Creates a time-limited preview link for a site in the API key's workspace. Omit `ttlMinutes` for 10080 minutes; allowed whole-minute values are 5 through 43200. This REST-only endpoint has no MCP-tool equivalent. The returned token is a bearer capability and must be handled as a secret.", "tags": [ "pages" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "description": "The UUID of a site in the API key's workspace.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttlMinutes": { "type": "integer", "minimum": 5, "maximum": 43200 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The request succeeded. Read the `data` Result field.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "siteId": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "siteId", "revision", "url", "token", "expiresAt" ], "additionalProperties": false } }, "required": [ "ok", "data" ], "additionalProperties": false } } } }, "400": { "description": "The site id or JSON request body did not match the endpoint's strict schema.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "401": { "description": "No bearer credential, or one that did not resolve.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "403": { "description": "The key is not workspace-restricted, programmatic access is unavailable, or its holder lacks `pages.manage`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "404": { "description": "The site is not in the API key's workspace.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "409": { "description": "The site has no previewable revision.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "429": { "description": "The API key is over its rate limit. Wait for `Retry-After` before retrying.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "500": { "description": "An unexpected server error occurred while handling the request.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "503": { "description": "Preview hosting is temporarily unavailable in this environment.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } } } }, "delete": { "operationId": "revokePagePreviewLink", "summary": "Revoke a Pages preview link", "description": "Revokes a preview token for a site in the API key's workspace. This REST-only endpoint has no MCP-tool equivalent; the token belongs only in the JSON body.", "tags": [ "pages" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "description": "The UUID of a site in the API key's workspace.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The request succeeded. Read the `data` Result field.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "siteId": { "type": "string", "format": "uuid" } }, "required": [ "siteId" ], "additionalProperties": false } }, "required": [ "ok", "data" ], "additionalProperties": false } } } }, "400": { "description": "The site id or JSON request body did not match the endpoint's strict schema.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "401": { "description": "No bearer credential, or one that did not resolve.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "403": { "description": "The key is not workspace-restricted, programmatic access is unavailable, or its holder lacks `pages.manage`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "429": { "description": "The API key is over its rate limit. Wait for `Retry-After` before retrying.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } }, "500": { "description": "An unexpected server error occurred while handling the request.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; preview tokens and their outcome are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`; a preview token must not be sent in a referrer header.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePreviewLinkError" } } } } } } }, "/api/pages/{siteId}/assets": { "post": { "operationId": "uploadPageAsset", "summary": "Upload a Pages reference image", "description": "Uploads one reference image to the canonical board for a site in the API key's workspace. This REST-only endpoint has no MCP-tool equivalent. The request cannot select a tenant, workspace, or board.", "tags": [ "pages" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "description": "The UUID of a site in the API key's workspace.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "properties": { "file": { "type": "string", "format": "binary", "description": "The single image file to attach to the site board." } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "The image was stored and attached to the site's board.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; upload results are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "boardItemId": { "type": "string", "format": "uuid" }, "storageObjectId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" } }, "required": [ "boardItemId", "storageObjectId", "displayName" ], "additionalProperties": false } }, "required": [ "ok", "data" ], "additionalProperties": false } } } }, "400": { "description": "The site id or multipart request was invalid, or the file failed the image upload limits.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; upload results are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAssetError" } } } }, "401": { "description": "No bearer credential, or one that did not resolve.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; upload results are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAssetError" } } } }, "403": { "description": "The key is not workspace-restricted, programmatic access is unavailable, or its operator holder lacks `pages.manage`.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; upload results are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAssetError" } } } }, "404": { "description": "The site or its canonical board is not in the API key's workspace.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; upload results are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAssetError" } } } }, "429": { "description": "The API key is over its rate limit. Wait for `Retry-After` before retrying.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; upload results are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`.", "schema": { "type": "string", "const": "no-referrer" } }, "Retry-After": { "description": "Whole seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAssetError" } } } }, "500": { "description": "An unexpected server or storage error occurred while handling the upload.", "headers": { "x-goosy-api": { "description": "Present while this API is in beta; the value is `beta`.", "schema": { "type": "string", "const": "beta" } }, "Cache-Control": { "description": "Always `no-store`; upload results are never cacheable.", "schema": { "type": "string", "const": "no-store" } }, "Referrer-Policy": { "description": "Always `no-referrer`.", "schema": { "type": "string", "const": "no-referrer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAssetError" } } } } } } } } }