# Andy Developer Docs > Build and operate Andy Workspaces, Agents, Knowledge, Public Chat, and Widgets. # Andy Developer Docs Source: https://docs.andypartner.com/ Create a Workspace and Agent, give the Agent reviewed Knowledge, and expose it through Public Chat or the React Widget. The same tenant operations are available through `andy-partner`, HTTP, and MCP. Start with the [Quickstart](/quickstart). Use [Authentication](/authentication) for User login and scoped Workspace API Keys, then continue to [Workspaces and Agents](/workspaces-and-agents), [Knowledge](/knowledge), or [Widget](/widget). Andy publishes explicit Markdown at the matching `.md` URL for every page. Machine readers can discover the complete corpus through [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt), and [`/agent-readability.json`](/agent-readability.json). Public documentation covers only the released tenant contract. Billing, migrations, evaluations, dogfood controls, Platform Admin, and internal operator workflows are not public operations. --- # Authentication Source: https://docs.andypartner.com/authentication ## Sign in **Outcome:** establish a supported User session and select the intended Workspace. **Prerequisites:** complete first-time sign-up and any required User setup in the [Andy App](https://app.andypartner.com). ```sh andy auth login andy auth status --json andy workspace list --json andy workspace select --workspace ``` Interactive login uses Clerk-hosted OAuth Authorization Code with S256 PKCE. The CLI stores the User session in the operating-system credential store when available. Workspace selection is explicit: `--workspace`, then the current profile, then a sole available Workspace, then an interactive prompt. Ambiguous non-interactive requests fail closed. ## API Keys **Outcome:** give unattended automation least-privilege access to one Workspace. **Prerequisites:** only a current Workspace Admin using an interactive User credential can create, rotate, or revoke Workspace API Keys. ```sh andy api-key create --workspace --name "Knowledge sync" --scopes workspace:read,agent:read,knowledge_source:read,knowledge_source:write --save-as knowledge-sync --json andy profile select --name knowledge-sync andy auth status --json andy api-key rotate --workspace --key --save-as knowledge-sync-next --json andy api-key revoke --workspace --key --yes --json ``` Keys are bound to one Workspace. Prefer the operating-system credential store or a secret manager. `ANDY_API_KEY` is supported for unattended execution. Rotation leaves the previous key active until you verify the replacement and explicitly revoke it. Never commit a key or include it in logs or JSON evidence. ## Problems and recovery - Exit `3` means authentication, reauthentication, or first-time User setup is required. - Exit `4` means a stable authorization, role, scope, Entitlement, archived-Workspace, resource, or conflict problem. - A revoked or expired User session requires `andy auth login` again. - A revoked Workspace key must be replaced by a Workspace Admin; it cannot refresh itself. - Entitlement loss and archived Workspaces fail closed. Authentication never widens product authority. **Machine-readable verification:** run `andy auth status --json`; require `status` to be `ready`, inspect `auth.mode`, `workspace.id`, and `credential.scopes`, and preserve `meta.requestId` on failure. **Next step:** continue with [Workspaces and Agents](/workspaces-and-agents). The retired user-scoped key is not accepted, and no legacy credential or raw backend configuration is imported. --- # CLI Reference Source: https://docs.andypartner.com/cli-reference ## Outcome Discover every supported public operation and use the same contract through the CLI, HTTP, or MCP. ## Prerequisites - `andy-partner@0.1.2`, supported client range `^0.1.2`. - Node `>=20`. - A User session or Workspace API Key allowed by the operation metadata below. ## Build freshness - Public contract: `1` - Catalog operations: `30` - Catalog digest: `sha256:dc52a748f0e1107cad52882fa72f7319a31d2c79d3d337e3e6cc09b47861dd4b` - Generated by: `apps/docs/generate-cli-reference.ts` Run `andy help` for global flags and `andy --help` for command input details. Add `--json` for stable machine output. Successful calls exit `0`; transport/internal failures exit `1`; invalid input exits `2`; authentication/setup failures exit `3`; and stable business or authorization problems exit `4`. | CLI command | Operation ID | HTTP | MCP tool | Mutates | Stable problems | | --- | --- | --- | --- | --- | --- | | `auth status` | `identity.status` | `POST /api/public/operations/identity/status` | `andy_identity_status` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `setup_required`, `workspace_selection_required` | | `workspace list` | `workspace.list` | `POST /api/public/operations/workspaces/list` | `andy_workspace_list` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error` | | `workspace inspect` | `workspace.inspect` | `POST /api/public/operations/workspaces/inspect` | `andy_workspace_inspect` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found` | | `workspace create` | `workspace.create` | `POST /api/public/operations/workspaces/create` | `andy_workspace_create` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `permission_denied`, `idempotency_conflict` | | `workspace rename` | `workspace.rename` | `POST /api/public/operations/workspaces/rename` | `andy_workspace_rename` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `workspace_archived`, `idempotency_conflict` | | `workspace entitlements` | `workspace.entitlements.inspect` | `POST /api/public/operations/workspaces/entitlements/inspect` | `andy_workspace_entitlements_inspect` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found` | | `agent list` | `agent.list` | `POST /api/public/operations/agents/list` | `andy_agent_list` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `entitlement_required` | | `agent inspect` | `agent.inspect` | `POST /api/public/operations/agents/inspect` | `andy_agent_inspect` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `entitlement_required` | | `agent create` | `agent.create` | `POST /api/public/operations/agents/create` | `andy_agent_create` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` | | `agent configure` | `agent.configure` | `POST /api/public/operations/agents/configure` | `andy_agent_configure` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `idempotency_conflict` | | `agent delete` | `agent.delete` | `POST /api/public/operations/agents/delete` | `andy_agent_delete` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `workspace_archived`, `confirmation_required`, `idempotency_conflict` | | `api-key list` | `api_key.list` | `POST /api/public/operations/api-keys/list` | `andy_api_key_list` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found` | | `api-key create` | `api_key.create` | `POST /api/public/operations/api-keys/create` | `andy_api_key_create` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` | | `api-key rotate` | `api_key.rotate` | `POST /api/public/operations/api-keys/rotate` | `andy_api_key_rotate` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` | | `api-key revoke` | `api_key.revoke` | `POST /api/public/operations/api-keys/revoke` | `andy_api_key_revoke` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `confirmation_required`, `idempotency_conflict` | | `knowledge-source list` | `knowledge_source.list` | `POST /api/public/operations/knowledge-sources/list` | `andy_knowledge_source_list` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` | | `knowledge-source inspect` | `knowledge_source.inspect` | `POST /api/public/operations/knowledge-sources/inspect` | `andy_knowledge_source_inspect` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` | | `knowledge-source add` | `knowledge_source.add` | `POST /api/public/operations/knowledge-sources/add` | `andy_knowledge_source_add` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` | | `knowledge-source wait` | `knowledge_source.wait` | `POST /api/public/operations/knowledge-sources/wait` | `andy_knowledge_source_wait` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed`, `processing_timeout` | | `knowledge-source reconcile` | `knowledge_source.reconcile` | `POST /api/public/operations/knowledge-sources/reconcile` | `andy_knowledge_source_reconcile` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `confirmation_required`, `idempotency_conflict` | | `knowledge-source replace` | `knowledge_source.replace` | `POST /api/public/operations/knowledge-sources/replace` | `andy_knowledge_source_replace` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` | | `knowledge-source delete` | `knowledge_source.delete` | `POST /api/public/operations/knowledge-sources/delete` | `andy_knowledge_source_delete` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `confirmation_required`, `idempotency_conflict` | | `public-chat inspect` | `public_chat.inspect` | `POST /api/public/operations/public-chats/inspect` | `andy_public_chat_inspect` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` | | `public-chat enable` | `public_chat.enable` | `POST /api/public/operations/public-chats/enable` | `andy_public_chat_enable` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed`, `idempotency_conflict` | | `public-chat disable` | `public_chat.disable` | `POST /api/public/operations/public-chats/disable` | `andy_public_chat_disable` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `confirmation_required`, `idempotency_conflict` | | `public-chat url` | `public_chat.url` | `POST /api/public/operations/public-chats/url` | `andy_public_chat_url` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` | | `widget inspect` | `widget.inspect` | `POST /api/public/operations/widgets/inspect` | `andy_widget_inspect` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` | | `widget configure` | `widget.configure` | `POST /api/public/operations/widgets/configure` | `andy_widget_configure` | yes | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed`, `confirmation_required`, `idempotency_conflict` | | `widget manifest` | `widget.manifest` | `POST /api/public/operations/widgets/manifest` | `andy_widget_manifest` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` | | `widget verify` | `widget.verify` | `POST /api/public/operations/widgets/verify` | `andy_widget_verify` | no | `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed` | Every response includes a request ID. Mutations accept an idempotency key, and the client reuses the same key for its single retry. Destructive commands require explicit confirmation. ## Operation schemas ### auth status - Operation ID: `identity.status` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `optional` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/identity/status` - MCP: `andy_identity_status` — Inspect Andy identity status. Return the current Andy identity, selected Workspace, authentication mode, availability, and request ID without exposing credentials. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `setup_required`, `workspace_selection_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "version": { "type": "string" }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "version", "endpoint" ], "additionalProperties": false }, "auth": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "user", "workspace_api_key" ] }, "secretLocation": { "type": "string", "enum": [ "os_store", "environment", "secret_file", "unknown" ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "mode", "secretLocation", "expiresAt" ], "additionalProperties": false }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "email", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "workspace": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "member" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "id", "name", "slug", "role", "status" ], "additionalProperties": false }, { "type": "null" } ] }, "credential": { "anyOf": [ { "type": "object", "properties": { "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspace:read", "agent:read", "agent:write", "knowledge_source:read", "knowledge_source:write", "public_chat:read", "public_chat:write", "widget:read", "widget:write" ] } } }, "required": [ "keyPrefix", "scopes" ], "additionalProperties": false }, { "type": "null" } ] }, "availability": { "type": "object", "properties": { "api": { "type": "boolean" }, "mcp": { "type": "boolean" } }, "required": [ "api", "mcp" ], "additionalProperties": false }, "status": { "type": "string", "const": "ready" } }, "required": [ "client", "auth", "user", "workspace", "credential", "availability", "status" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### workspace list - Operation ID: `workspace.list` - Authentication: `oauth_token` - Workspace selection: `none` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/workspaces/list` - MCP: `andy_workspace_list` — List Andy Workspaces. List the Workspaces available to the connected Andy identity. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "pageSize": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "pageSize" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "member" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "id", "name", "slug", "role", "status" ], "additionalProperties": false } } }, "required": [ "workspaces" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### workspace inspect - Operation ID: `workspace.inspect` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/workspaces/inspect` - MCP: `andy_workspace_inspect` — Inspect an Andy Workspace. Inspect the selected Workspace without exposing billing credentials. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "member" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "id", "name", "slug", "role", "status" ], "additionalProperties": false } }, "required": [ "workspace" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### workspace create - Operation ID: `workspace.create` - Authentication: `oauth_token` - Workspace selection: `none` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/workspaces/create` - MCP: `andy_workspace_create` — Create an Andy Workspace. Create a Workspace owned by the current User under existing Plan and trial rules. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `permission_denied`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "member" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "id", "name", "slug", "role", "status" ], "additionalProperties": false } }, "required": [ "workspace" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### workspace rename - Operation ID: `workspace.rename` - Authentication: `oauth_token` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/workspaces/rename` - MCP: `andy_workspace_rename` — Rename an Andy Workspace. Rename the selected Workspace as a current Admin or Owner. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `workspace_archived`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "member" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "id", "name", "slug", "role", "status" ], "additionalProperties": false } }, "required": [ "workspace" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### workspace entitlements - Operation ID: `workspace.entitlements.inspect` - Authentication: `oauth_token` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/workspaces/entitlements/inspect` - MCP: `andy_workspace_entitlements_inspect` — Inspect Andy Workspace Entitlements. Inspect current Entitlements, Limits, Usage, Plan, and trial state for the selected Workspace. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "entitlement": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "planName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "active": { "type": "boolean" }, "features": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "usage": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "channels": { "type": "object", "properties": { "allowed": { "type": "array", "items": { "type": "string" } }, "maxActive": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "allowed", "maxActive" ], "additionalProperties": false }, "trialEnd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "periodEnd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "workspaceId", "plan", "planName", "status", "active", "features", "limits", "usage", "channels", "trialEnd", "periodEnd", "cancelAtPeriodEnd" ], "additionalProperties": false } }, "required": [ "entitlement" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### agent list - Operation ID: `agent.list` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/agents/list` - MCP: `andy_agent_list` — List Andy Agents. List active Agents in the selected Workspace. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "pageSize": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "pageSize" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "active" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "configuration": { "type": "object", "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "temperature": { "type": "number" } }, "required": [ "instructions", "temperature" ], "additionalProperties": false } }, "required": [ "id", "workspaceId", "name", "slug", "status", "defaultLanguage", "configuration" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### agent inspect - Operation ID: `agent.inspect` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/agents/inspect` - MCP: `andy_agent_inspect` — Inspect an Andy Agent. Inspect one active Agent by exact ID in the selected Workspace. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "active" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "configuration": { "type": "object", "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "temperature": { "type": "number" } }, "required": [ "instructions", "temperature" ], "additionalProperties": false } }, "required": [ "id", "workspaceId", "name", "slug", "status", "defaultLanguage", "configuration" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### agent create - Operation ID: `agent.create` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/agents/create` - MCP: `andy_agent_create` — Create an Andy Agent. Create an Agent in the selected Workspace under current Entitlements and Limits. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "defaultLanguage": { "default": "en", "type": "string", "enum": [ "en", "es" ] }, "instructions": { "type": "string", "minLength": 1, "maxLength": 20000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "name", "defaultLanguage" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "active" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "configuration": { "type": "object", "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "temperature": { "type": "number" } }, "required": [ "instructions", "temperature" ], "additionalProperties": false } }, "required": [ "id", "workspaceId", "name", "slug", "status", "defaultLanguage", "configuration" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### agent configure - Operation ID: `agent.configure` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/agents/configure` - MCP: `andy_agent_configure` — Configure an Andy Agent. Configure the supported public fields of one Agent by exact ID. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "instructions": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20000 }, { "type": "null" } ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "active" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "configuration": { "type": "object", "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "temperature": { "type": "number" } }, "required": [ "instructions", "temperature" ], "additionalProperties": false } }, "required": [ "id", "workspaceId", "name", "slug", "status", "defaultLanguage", "configuration" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### agent delete - Operation ID: `agent.delete` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/agents/delete` - MCP: `andy_agent_delete` — Soft-delete an Andy Agent. Soft-delete one Agent after exact-ID confirmation. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `resource_not_found`, `workspace_archived`, `confirmation_required`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "confirm": { "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "deleted": { "type": "boolean", "const": true } }, "required": [ "agentId", "deleted" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### api-key list - Operation ID: `api_key.list` - Authentication: `oauth_token` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/api-keys/list` - MCP: `andy_api_key_list` — List Andy Workspace API Keys. List safe metadata for Workspace API Keys as a current Workspace Admin. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "pageSize": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "pageSize" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "keyPrefix": { "type": "string", "minLength": 1 }, "preset": { "anyOf": [ { "type": "string", "enum": [ "read_only", "operator" ] }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspace:read", "agent:read", "agent:write", "knowledge_source:read", "knowledge_source:write", "public_chat:read", "public_chat:write", "widget:read", "widget:write" ] } }, "lastUsedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "revokedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rotatedFromId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "name", "keyPrefix", "preset", "scopes", "lastUsedAt", "createdAt", "revokedAt", "rotatedFromId" ], "additionalProperties": false } } }, "required": [ "apiKeys" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### api-key create - Operation ID: `api_key.create` - Authentication: `oauth_token` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/api-keys/create` - MCP: `andy_api_key_create` — Create an Andy Workspace API Key. Create a least-privilege Workspace API Key and return its secret once. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "preset": { "type": "string", "enum": [ "read_only", "operator" ] }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "workspace:read", "agent:read", "agent:write", "knowledge_source:read", "knowledge_source:write", "public_chat:read", "public_chat:write", "widget:read", "widget:write" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "keyPrefix": { "type": "string", "minLength": 1 }, "preset": { "anyOf": [ { "type": "string", "enum": [ "read_only", "operator" ] }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspace:read", "agent:read", "agent:write", "knowledge_source:read", "knowledge_source:write", "public_chat:read", "public_chat:write", "widget:read", "widget:write" ] } }, "lastUsedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "revokedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rotatedFromId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "name", "keyPrefix", "preset", "scopes", "lastUsedAt", "createdAt", "revokedAt", "rotatedFromId" ], "additionalProperties": false }, "secret": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "secretReturned": { "type": "boolean" } }, "required": [ "apiKey", "secret", "secretReturned" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### api-key rotate - Operation ID: `api_key.rotate` - Authentication: `oauth_token` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/api-keys/rotate` - MCP: `andy_api_key_rotate` — Rotate an Andy Workspace API Key. Create an overlapping replacement credential without revoking the old key. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "apiKeyId": { "type": "string", "minLength": 1 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "apiKeyId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "keyPrefix": { "type": "string", "minLength": 1 }, "preset": { "anyOf": [ { "type": "string", "enum": [ "read_only", "operator" ] }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspace:read", "agent:read", "agent:write", "knowledge_source:read", "knowledge_source:write", "public_chat:read", "public_chat:write", "widget:read", "widget:write" ] } }, "lastUsedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "revokedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rotatedFromId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "name", "keyPrefix", "preset", "scopes", "lastUsedAt", "createdAt", "revokedAt", "rotatedFromId" ], "additionalProperties": false }, "secret": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "secretReturned": { "type": "boolean" } }, "required": [ "apiKey", "secret", "secretReturned" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### api-key revoke - Operation ID: `api_key.revoke` - Authentication: `oauth_token` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/api-keys/revoke` - MCP: `andy_api_key_revoke` — Revoke an Andy Workspace API Key. Revoke one Workspace API Key by exact ID after explicit confirmation. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `confirmation_required`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "apiKeyId": { "type": "string", "minLength": 1 }, "confirm": { "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "apiKeyId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "keyPrefix": { "type": "string", "minLength": 1 }, "preset": { "anyOf": [ { "type": "string", "enum": [ "read_only", "operator" ] }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspace:read", "agent:read", "agent:write", "knowledge_source:read", "knowledge_source:write", "public_chat:read", "public_chat:write", "widget:read", "widget:write" ] } }, "lastUsedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "revokedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rotatedFromId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "name", "keyPrefix", "preset", "scopes", "lastUsedAt", "createdAt", "revokedAt", "rotatedFromId" ], "additionalProperties": false } }, "required": [ "apiKey" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### knowledge-source list - Operation ID: `knowledge_source.list` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/knowledge-sources/list` - MCP: `andy_knowledge_source_list` — List Andy Knowledge Sources. List current Knowledge Sources for one Agent. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "cursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "pageSize": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "agentId", "pageSize" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "type": "boolean" }, "importedAt": { "type": "number" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed", "replacing" ] }, "activeRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] }, "pendingRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "agentId", "key", "title", "provenance", "revision", "digest", "required", "importedAt", "state", "activeRevision", "pendingRevision" ], "additionalProperties": false } } }, "required": [ "knowledgeSources" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### knowledge-source inspect - Operation ID: `knowledge_source.inspect` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/knowledge-sources/inspect` - MCP: `andy_knowledge_source_inspect` — Inspect an Andy Knowledge Source. Inspect one Knowledge Source and its safe active and pending revision state. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "sourceId": { "type": "string", "minLength": 1 } }, "required": [ "agentId", "sourceId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "knowledgeSource": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "type": "boolean" }, "importedAt": { "type": "number" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed", "replacing" ] }, "activeRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] }, "pendingRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "agentId", "key", "title", "provenance", "revision", "digest", "required", "importedAt", "state", "activeRevision", "pendingRevision" ], "additionalProperties": false } }, "required": [ "knowledgeSource" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### knowledge-source add - Operation ID: `knowledge_source.add` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/knowledge-sources/add` - MCP: `andy_knowledge_source_add` — Add an Andy Knowledge Source. Add one reviewed, content-addressed Knowledge Source to an Agent. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1, "maxLength": 200 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "default": true, "type": "boolean" }, "content": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "key", "title", "provenance", "revision", "digest", "required", "content", "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "knowledgeSource": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "type": "boolean" }, "importedAt": { "type": "number" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed", "replacing" ] }, "activeRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] }, "pendingRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "agentId", "key", "title", "provenance", "revision", "digest", "required", "importedAt", "state", "activeRevision", "pendingRevision" ], "additionalProperties": false } }, "required": [ "knowledgeSource" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### knowledge-source wait - Operation ID: `knowledge_source.wait` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/knowledge-sources/wait` - MCP: `andy_knowledge_source_wait` — Observe Andy Knowledge Source processing. Return current processing state and bounded retry guidance without holding the server request open. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed`, `processing_timeout` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "sourceId": { "type": "string", "minLength": 1 } }, "required": [ "agentId", "sourceId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "knowledgeSource": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "type": "boolean" }, "importedAt": { "type": "number" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed", "replacing" ] }, "activeRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] }, "pendingRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "agentId", "key", "title", "provenance", "revision", "digest", "required", "importedAt", "state", "activeRevision", "pendingRevision" ], "additionalProperties": false }, "terminal": { "type": "boolean" }, "retryAfterMs": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "knowledgeSource", "terminal", "retryAfterMs" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### knowledge-source reconcile - Operation ID: `knowledge_source.reconcile` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/knowledge-sources/reconcile` - MCP: `andy_knowledge_source_reconcile` — Reconcile Andy Knowledge Sources. Plan or apply one versioned desired-state Knowledge Source manifest; omission is non-destructive. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `confirmation_required`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "manifest": { "type": "object", "properties": { "version": { "type": "string", "const": "1" }, "sources": { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1, "maxLength": 200 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "default": true, "type": "boolean" }, "content": { "type": "string", "minLength": 1 }, "tombstone": { "type": "boolean", "const": false } }, "required": [ "key", "title", "provenance", "revision", "digest", "required", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 160 }, "tombstone": { "type": "boolean", "const": true }, "confirm": { "type": "string", "minLength": 1 } }, "required": [ "key", "tombstone" ], "additionalProperties": false } ] } } }, "required": [ "version", "sources" ], "additionalProperties": false }, "dryRun": { "default": true, "type": "boolean" }, "prune": { "default": false, "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "agentId", "manifest", "dryRun", "prune" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "runId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "planned", "applying", "completed", "failed" ] }, "dryRun": { "type": "boolean" }, "checkpoint": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorCode": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "plan": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "sourceId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "action": { "type": "string", "enum": [ "add", "noop", "replace", "delete" ] } }, "required": [ "key", "sourceId", "action" ], "additionalProperties": false } }, "knowledgeSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "type": "boolean" }, "importedAt": { "type": "number" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed", "replacing" ] }, "activeRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] }, "pendingRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "agentId", "key", "title", "provenance", "revision", "digest", "required", "importedAt", "state", "activeRevision", "pendingRevision" ], "additionalProperties": false } } }, "required": [ "runId", "status", "dryRun", "checkpoint", "errorCode", "plan", "knowledgeSources" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### knowledge-source replace - Operation ID: `knowledge_source.replace` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/knowledge-sources/replace` - MCP: `andy_knowledge_source_replace` — Replace an Andy Knowledge Source. Privately process a replacement revision while retaining last-good Knowledge. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `limit_exceeded`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 240 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1, "maxLength": 200 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "default": true, "type": "boolean" }, "content": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "sourceId": { "type": "string", "minLength": 1 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "title", "provenance", "revision", "digest", "required", "content", "agentId", "sourceId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "knowledgeSource": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "provenance": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "repository", "url", "manual" ] }, "uri": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "kind", "uri" ], "additionalProperties": false }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "required": { "type": "boolean" }, "importedAt": { "type": "number" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed", "replacing" ] }, "activeRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] }, "pendingRevision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "processing", "active", "failed" ] }, "importedAt": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "revision", "digest", "state", "importedAt", "errorCode" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "agentId", "key", "title", "provenance", "revision", "digest", "required", "importedAt", "state", "activeRevision", "pendingRevision" ], "additionalProperties": false } }, "required": [ "knowledgeSource" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### knowledge-source delete - Operation ID: `knowledge_source.delete` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/knowledge-sources/delete` - MCP: `andy_knowledge_source_delete` — Delete an Andy Knowledge Source. Delete one Knowledge Source only with explicit tombstone and prune intent plus exact-ID confirmation. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `confirmation_required`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "sourceId": { "type": "string", "minLength": 1 }, "tombstone": { "type": "boolean" }, "prune": { "type": "boolean" }, "confirm": { "type": "string", "minLength": 1 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "agentId", "sourceId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "sourceId": { "type": "string", "minLength": 1 }, "deleted": { "type": "boolean", "const": true } }, "required": [ "sourceId", "deleted" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### public-chat inspect - Operation ID: `public_chat.inspect` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/public-chats/inspect` - MCP: `andy_public_chat_inspect` — Inspect Andy Public Chat. Inspect Public Chat state and its stable URL for one Agent. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "publicChat": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "agentId", "enabled", "url", "website" ], "additionalProperties": false } }, "required": [ "publicChat" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### public-chat enable - Operation ID: `public_chat.enable` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/public-chats/enable` - MCP: `andy_public_chat_enable` — Enable Andy Public Chat. Enable Public Chat for one exactly selected Agent. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "publicChat": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "agentId", "enabled", "url", "website" ], "additionalProperties": false } }, "required": [ "publicChat" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### public-chat disable - Operation ID: `public_chat.disable` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/public-chats/disable` - MCP: `andy_public_chat_disable` — Disable Andy Public Chat. Disable Public Chat after exact Agent-ID confirmation. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `confirmation_required`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "confirm": { "type": "string", "minLength": 1 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "publicChat": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "agentId", "enabled", "url", "website" ], "additionalProperties": false } }, "required": [ "publicChat" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### public-chat url - Operation ID: `public_chat.url` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/public-chats/url` - MCP: `andy_public_chat_url` — Resolve Andy Public Chat URL. Return the stable Public Chat URL for one Agent. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" } }, "required": [ "agentId", "url" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### widget inspect - Operation ID: `widget.inspect` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/widgets/inspect` - MCP: `andy_widget_inspect` — Inspect Andy Widget configuration. Inspect the effective canonical Widget configuration for one Agent. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "configuration": { "type": "object", "properties": { "allowedOrigins": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "legacyAllowedDomains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "legacyAllowsAnyOrigin": { "type": "boolean" }, "showBranding": { "type": "boolean" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "appearance": { "type": "object", "properties": { "headline": { "type": "string" }, "description": { "type": "string" }, "welcomeMessage": { "type": "string" }, "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "theme": { "type": "string", "enum": [ "light", "dark", "auto" ] }, "orientation": { "type": "string", "enum": [ "left", "right" ] }, "logoUrl": { "type": "string" }, "bubbleStyle": { "type": "string", "enum": [ "icon", "pill" ] }, "bubbleLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "useBrandColor": { "type": "boolean" } }, "required": [ "headline", "description", "welcomeMessage", "brandColor", "theme", "orientation", "logoUrl", "bubbleStyle", "bubbleLabel", "useBrandColor" ], "additionalProperties": false }, "behavior": { "type": "object", "properties": { "instructions": { "type": "string" }, "conversationTemperature": { "type": "number", "minimum": 0, "maximum": 1 }, "conversationCreativity": { "type": "number", "minimum": 0, "maximum": 1 }, "welcomePopup": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "seconds": { "type": "number", "minimum": 0, "maximum": 30 }, "message": { "type": "string" } }, "required": [ "enabled", "seconds", "message" ], "additionalProperties": false }, "collectUserInfo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "enabled", "message" ], "additionalProperties": false }, "leadCapture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "const": "" } ] }, "calendarLink": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "const": "" } ] }, "phoneNumber": { "type": "string" }, "customMessage": { "type": "string" }, "emailNotificationEnabled": { "type": "boolean" } }, "required": [ "enabled", "contactEmail", "calendarLink", "phoneNumber", "customMessage", "emailNotificationEnabled" ], "additionalProperties": false }, "predefinedQuestions": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "order": { "type": "number" } }, "required": [ "question" ], "additionalProperties": false } } }, "required": [ "instructions", "conversationTemperature", "conversationCreativity", "welcomePopup", "collectUserInfo", "leadCapture", "predefinedQuestions" ], "additionalProperties": false } }, "required": [ "allowedOrigins", "legacyAllowedDomains", "legacyAllowsAnyOrigin", "showBranding", "defaultLanguage", "website", "appearance", "behavior" ], "additionalProperties": false } }, "required": [ "agentId", "configuration" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### widget configure - Operation ID: `widget.configure` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `true` - Idempotency: supported `true`; required `false` - HTTP: `POST /api/public/operations/widgets/configure` - MCP: `andy_widget_configure` — Configure Andy Widget. Configure exact allowed origins and the existing Agent-owned Widget fields. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed`, `confirmation_required`, `idempotency_conflict` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "configuration": { "type": "object", "properties": { "allowedOrigins": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "confirmRemovedOrigins": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "showBranding": { "type": "boolean" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "appearance": { "type": "object", "properties": { "headline": { "type": "string" }, "description": { "type": "string" }, "welcomeMessage": { "type": "string" }, "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "theme": { "type": "string", "enum": [ "light", "dark", "auto" ] }, "orientation": { "type": "string", "enum": [ "left", "right" ] }, "logoUrl": { "type": "string" }, "bubbleStyle": { "type": "string", "enum": [ "icon", "pill" ] }, "bubbleLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "useBrandColor": { "type": "boolean" } }, "additionalProperties": false }, "behavior": { "type": "object", "properties": { "instructions": { "type": "string" }, "conversationTemperature": { "type": "number", "minimum": 0, "maximum": 1 }, "conversationCreativity": { "type": "number", "minimum": 0, "maximum": 1 }, "welcomePopup": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "seconds": { "type": "number", "minimum": 0, "maximum": 30 }, "message": { "type": "string" } }, "additionalProperties": false }, "collectUserInfo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "message": { "type": "string" } }, "additionalProperties": false }, "leadCapture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "const": "" } ] }, "calendarLink": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "const": "" } ] }, "phoneNumber": { "type": "string" }, "customMessage": { "type": "string" }, "emailNotificationEnabled": { "type": "boolean" } }, "additionalProperties": false }, "predefinedQuestions": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "order": { "type": "number" } }, "required": [ "question" ], "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 200 } }, "required": [ "agentId", "configuration" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "configuration": { "type": "object", "properties": { "allowedOrigins": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "legacyAllowedDomains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "legacyAllowsAnyOrigin": { "type": "boolean" }, "showBranding": { "type": "boolean" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "appearance": { "type": "object", "properties": { "headline": { "type": "string" }, "description": { "type": "string" }, "welcomeMessage": { "type": "string" }, "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "theme": { "type": "string", "enum": [ "light", "dark", "auto" ] }, "orientation": { "type": "string", "enum": [ "left", "right" ] }, "logoUrl": { "type": "string" }, "bubbleStyle": { "type": "string", "enum": [ "icon", "pill" ] }, "bubbleLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "useBrandColor": { "type": "boolean" } }, "required": [ "headline", "description", "welcomeMessage", "brandColor", "theme", "orientation", "logoUrl", "bubbleStyle", "bubbleLabel", "useBrandColor" ], "additionalProperties": false }, "behavior": { "type": "object", "properties": { "instructions": { "type": "string" }, "conversationTemperature": { "type": "number", "minimum": 0, "maximum": 1 }, "conversationCreativity": { "type": "number", "minimum": 0, "maximum": 1 }, "welcomePopup": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "seconds": { "type": "number", "minimum": 0, "maximum": 30 }, "message": { "type": "string" } }, "required": [ "enabled", "seconds", "message" ], "additionalProperties": false }, "collectUserInfo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "enabled", "message" ], "additionalProperties": false }, "leadCapture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "const": "" } ] }, "calendarLink": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "const": "" } ] }, "phoneNumber": { "type": "string" }, "customMessage": { "type": "string" }, "emailNotificationEnabled": { "type": "boolean" } }, "required": [ "enabled", "contactEmail", "calendarLink", "phoneNumber", "customMessage", "emailNotificationEnabled" ], "additionalProperties": false }, "predefinedQuestions": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "order": { "type": "number" } }, "required": [ "question" ], "additionalProperties": false } } }, "required": [ "instructions", "conversationTemperature", "conversationCreativity", "welcomePopup", "collectUserInfo", "leadCapture", "predefinedQuestions" ], "additionalProperties": false } }, "required": [ "allowedOrigins", "legacyAllowedDomains", "legacyAllowsAnyOrigin", "showBranding", "defaultLanguage", "website", "appearance", "behavior" ], "additionalProperties": false } }, "required": [ "agentId", "configuration" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### widget manifest - Operation ID: `widget.manifest` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/widgets/manifest` - MCP: `andy_widget_manifest` — Resolve Andy Widget integration manifest. Return the Workspace, Agent, pinned package contract, effective configuration, and Public Chat state without secrets. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 } }, "required": [ "id", "slug" ], "additionalProperties": false }, "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 } }, "required": [ "id", "slug" ], "additionalProperties": false }, "package": { "type": "object", "properties": { "packageName": { "type": "string", "const": "andy-widget-react" }, "version": { "type": "string", "const": "2.0.5" }, "component": { "type": "string", "const": "AndyChat" }, "agentIdProp": { "type": "string", "const": "embedId" } }, "required": [ "packageName", "version", "component", "agentIdProp" ], "additionalProperties": false }, "configuration": { "type": "object", "properties": { "allowedOrigins": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "legacyAllowedDomains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "legacyAllowsAnyOrigin": { "type": "boolean" }, "showBranding": { "type": "boolean" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "appearance": { "type": "object", "properties": { "headline": { "type": "string" }, "description": { "type": "string" }, "welcomeMessage": { "type": "string" }, "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "theme": { "type": "string", "enum": [ "light", "dark", "auto" ] }, "orientation": { "type": "string", "enum": [ "left", "right" ] }, "logoUrl": { "type": "string" }, "bubbleStyle": { "type": "string", "enum": [ "icon", "pill" ] }, "bubbleLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "useBrandColor": { "type": "boolean" } }, "required": [ "headline", "description", "welcomeMessage", "brandColor", "theme", "orientation", "logoUrl", "bubbleStyle", "bubbleLabel", "useBrandColor" ], "additionalProperties": false }, "behavior": { "type": "object", "properties": { "instructions": { "type": "string" }, "conversationTemperature": { "type": "number", "minimum": 0, "maximum": 1 }, "conversationCreativity": { "type": "number", "minimum": 0, "maximum": 1 }, "welcomePopup": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "seconds": { "type": "number", "minimum": 0, "maximum": 30 }, "message": { "type": "string" } }, "required": [ "enabled", "seconds", "message" ], "additionalProperties": false }, "collectUserInfo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "enabled", "message" ], "additionalProperties": false }, "leadCapture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "const": "" } ] }, "calendarLink": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "const": "" } ] }, "phoneNumber": { "type": "string" }, "customMessage": { "type": "string" }, "emailNotificationEnabled": { "type": "boolean" } }, "required": [ "enabled", "contactEmail", "calendarLink", "phoneNumber", "customMessage", "emailNotificationEnabled" ], "additionalProperties": false }, "predefinedQuestions": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "order": { "type": "number" } }, "required": [ "question" ], "additionalProperties": false } } }, "required": [ "instructions", "conversationTemperature", "conversationCreativity", "welcomePopup", "collectUserInfo", "leadCapture", "predefinedQuestions" ], "additionalProperties": false } }, "required": [ "allowedOrigins", "legacyAllowedDomains", "legacyAllowsAnyOrigin", "showBranding", "defaultLanguage", "website", "appearance", "behavior" ], "additionalProperties": false }, "publicChat": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "agentId", "enabled", "url", "website" ], "additionalProperties": false } }, "required": [ "workspace", "agent", "package", "configuration", "publicChat" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ### widget verify - Operation ID: `widget.verify` - Authentication: `oauth_token`, `workspace_api_key` - Workspace selection: `required` - Mutates: `false` - Idempotency: supported `false`; required `false` - HTTP: `POST /api/public/operations/widgets/verify` - MCP: `andy_widget_verify` — Verify an Andy Widget integration. Verify Agent/configuration/origin/Knowledge/Public Chat and execute one real public answer, consuming one conversation and quota unit. - Stable problems: `authentication_required`, `reauthentication_required`, `invalid_request`, `internal_error`, `workspace_selection_required`, `permission_denied`, `resource_not_found`, `workspace_archived`, `entitlement_required`, `processing_failed` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "origin": { "type": "string" }, "question": { "default": "What can you help me with?", "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "agentId", "origin", "question" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "origin": { "type": "string" }, "configuration": { "type": "object", "properties": { "allowedOrigins": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "legacyAllowedDomains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "legacyAllowsAnyOrigin": { "type": "boolean" }, "showBranding": { "type": "boolean" }, "defaultLanguage": { "type": "string", "enum": [ "en", "es" ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "appearance": { "type": "object", "properties": { "headline": { "type": "string" }, "description": { "type": "string" }, "welcomeMessage": { "type": "string" }, "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "theme": { "type": "string", "enum": [ "light", "dark", "auto" ] }, "orientation": { "type": "string", "enum": [ "left", "right" ] }, "logoUrl": { "type": "string" }, "bubbleStyle": { "type": "string", "enum": [ "icon", "pill" ] }, "bubbleLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "useBrandColor": { "type": "boolean" } }, "required": [ "headline", "description", "welcomeMessage", "brandColor", "theme", "orientation", "logoUrl", "bubbleStyle", "bubbleLabel", "useBrandColor" ], "additionalProperties": false }, "behavior": { "type": "object", "properties": { "instructions": { "type": "string" }, "conversationTemperature": { "type": "number", "minimum": 0, "maximum": 1 }, "conversationCreativity": { "type": "number", "minimum": 0, "maximum": 1 }, "welcomePopup": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "seconds": { "type": "number", "minimum": 0, "maximum": 30 }, "message": { "type": "string" } }, "required": [ "enabled", "seconds", "message" ], "additionalProperties": false }, "collectUserInfo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "enabled", "message" ], "additionalProperties": false }, "leadCapture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "const": "" } ] }, "calendarLink": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "const": "" } ] }, "phoneNumber": { "type": "string" }, "customMessage": { "type": "string" }, "emailNotificationEnabled": { "type": "boolean" } }, "required": [ "enabled", "contactEmail", "calendarLink", "phoneNumber", "customMessage", "emailNotificationEnabled" ], "additionalProperties": false }, "predefinedQuestions": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "order": { "type": "number" } }, "required": [ "question" ], "additionalProperties": false } } }, "required": [ "instructions", "conversationTemperature", "conversationCreativity", "welcomePopup", "collectUserInfo", "leadCapture", "predefinedQuestions" ], "additionalProperties": false } }, "required": [ "allowedOrigins", "legacyAllowedDomains", "legacyAllowsAnyOrigin", "showBranding", "defaultLanguage", "website", "appearance", "behavior" ], "additionalProperties": false }, "checks": { "type": "object", "properties": { "agent": { "type": "boolean", "const": true }, "configuration": { "type": "boolean", "const": true }, "origin": { "type": "boolean", "const": true }, "knowledge": { "type": "boolean", "const": true }, "publicChat": { "type": "boolean", "const": true }, "answer": { "type": "boolean", "const": true } }, "required": [ "agent", "configuration", "origin", "knowledge", "publicChat", "answer" ], "additionalProperties": false }, "answer": { "type": "string", "minLength": 1 } }, "required": [ "agentId", "origin", "configuration", "checks", "answer" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "nextCursor": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } ``` ## Machine-readable verification `andy version --json` reports the client, public contract, Node range, and compatibility. The tracked page is current only when `bun --filter @andy/docs generate-reference --check` exits `0`. ## Next step Use [MCP](/mcp) for tool connection or [Troubleshooting and Upgrading](/troubleshooting-and-upgrading) for stable failures and upgrades. --- # Knowledge Source: https://docs.andypartner.com/knowledge ## Outcome Publish a reviewed Knowledge Source and safely reconcile later revisions without losing the last good content. ## Prerequisites - An active Workspace and Agent. - Reviewed UTF-8 text no larger than 750,000 bytes. - Stable source key, provenance URI, caller revision, and SHA-256 digest. ## Add or replace ```sh andy knowledge-source add --workspace --agent --key pricing --title "Pricing" --provenance-kind repository --provenance-uri docs/pricing.md --revision git: --digest sha256: --file ./pricing.md --json andy knowledge-source wait --workspace --agent --source --timeout-ms 120000 --json andy knowledge-source replace --workspace --agent --source --revision git: --digest sha256: --file ./pricing.md --json ``` Replacement creates a private candidate revision. Failed processing leaves the previous active revision available. ## Reconcile a manifest ```sh andy knowledge-source reconcile --workspace --agent --manifest ./knowledge-manifest.json --json andy knowledge-source reconcile --workspace --agent --manifest ./knowledge-manifest.json --apply --idempotency-key --json ``` Unchanged sources no-op. Omitted keys remain untouched. Deletion requires an explicit tombstone, `--prune`, and exact source identity. ## Machine-readable verification ```sh andy knowledge-source inspect --workspace --agent --source --json ``` Require an active current revision with the expected `digest` and `revision`; preserve `meta.requestId` for support. ## Next step Configure one exact public origin in [Widget](/widget). --- # MCP Source: https://docs.andypartner.com/mcp ## Outcome Connect an MCP client to Andy's public tenant operations with the same schemas and stable problems as HTTP and CLI. ## Prerequisites - A supported MCP client. - A User session or narrowly scoped Workspace API Key. - The exact Workspace selected for the connection. ## Configure the connection ```json { "mcpServers": { "andy": { "url": "https://app.andypartner.com/api/mcp", "headers": { "Authorization": "Bearer ${ANDY_API_KEY}" } } } } ``` Each `andy_*` tool is generated from the tenant-operation catalog with matching input/output schemas, stable problems, request IDs, authorization checks, and idempotency rules. Workspace API Keys can call only operations allowed by their scopes and owning Workspace. ## Machine-readable verification Use `andy-partner/operations.json` or the generated [CLI Reference](/cli-reference) to compare every advertised MCP name and schema. Invoke `andy_identity_status` and require `data.status` to be `ready` with a `meta.requestId`. ## Next step Choose an operation from the [CLI Reference](/cli-reference). This documentation site does not expose an Ask AI route or a separate documentation MCP server. --- # Quickstart Source: https://docs.andypartner.com/quickstart ## Outcome Create and configure an Agent, activate reviewed Knowledge, allow one exact Widget origin, and verify a real public answer. ## Prerequisites - Node 20 or newer. - A supported Andy User. Complete first-time account setup in the [Andy App](https://app.andypartner.com) before using the CLI. - A public HTTPS origin where the Widget will run. - A UTF-8 `product.md` file containing visitor-safe facts. ## 1. Install and sign in ```sh bun add --global andy-partner@0.1.2 andy version --json andy auth login andy auth status --json ``` The login command opens Clerk's browser-assisted OAuth Authorization Code flow with S256 PKCE. Andy does not implement a second password, email-code, or MFA system in the CLI. ## 2. Create, select, and configure the tenant ```sh andy workspace create --name "Example Workspace" --json andy workspace list --json andy workspace select --workspace andy agent create --workspace --name "Website Assistant" --language en --json andy agent configure --workspace --agent --instructions "Answer only from reviewed Knowledge." --json andy agent inspect --workspace --agent --json ``` Keep the returned Workspace and Agent IDs. Mutations are idempotent and every response includes a request ID. ## 3. Add reviewed Knowledge Prepare its SHA-256 digest, then add and await the active source: ```sh digest="sha256:$(shasum -a 256 product.md | cut -d ' ' -f 1)" andy knowledge-source add --workspace --agent --key product --title "Product" --provenance-kind repository --provenance-uri docs/product.md --revision git: --digest "$digest" --file ./product.md --json andy knowledge-source wait --workspace --agent --source --timeout-ms 120000 --json ``` ## 4. Configure Public Chat and the Widget Create the Widget JSON explicitly, then apply it and the exact allowed origin: ```sh cat > widget.json <<'JSON' { "allowedOrigins": ["https://example.com"], "position": "bottom-right", "primaryColor": "#6d28d9", "welcomeMessage": "How can I help?" } JSON andy public-chat enable --workspace --agent --website https://example.com --json andy widget configure --workspace --agent --config ./widget.json --json andy widget manifest --workspace --agent --json ``` ## Machine-readable verification ```sh andy auth status --json andy agent inspect --workspace --agent --json andy knowledge-source inspect --workspace --agent --source --json andy widget manifest --workspace --agent --json andy widget verify --workspace --agent --origin https://example.com --json ``` `widget verify` checks Agent identity, effective settings, the exact allowed origin, Knowledge readiness, Public Chat state, and one real answer. It consumes one conversation and quota unit. ## Next step Continue with [Authentication](/authentication), [Knowledge reconciliation](/knowledge), or the [Widget package](/widget). --- # Support Source: https://docs.andypartner.com/support ## Outcome Send enough safe evidence for Andy support to trace a public-contract failure. ## Prerequisites - The `andy-partner` version, operation name, request ID, and stable problem or exit category. - The Workspace or Agent ID only when safe to share. ## Contact support ```text To: andy@andesphere.com Subject: Andy request Client version: Operation: Request ID: Stable problem or exit category: ``` Do not send passwords, User session tokens, Workspace API Keys, private Knowledge, or customer conversations. ## Machine-readable verification Run the failing command with `--json`, remove secrets and private content, and confirm the retained evidence includes `meta.requestId` or the CLI exit category. ## Next step Email [andy@andesphere.com](mailto:andy@andesphere.com) with the completed safe template. --- # Troubleshooting and Upgrading Source: https://docs.andypartner.com/troubleshooting-and-upgrading ## Outcome Classify a stable failure, preserve safe evidence, and upgrade to the current supported client. ## Prerequisites - The failing command's exit code and request ID. - The installed `andy-partner` version and Node version. - No access token, API key, private Knowledge, or customer conversation in collected evidence. ## Interpret the outcome | Exit | Meaning | | ---: | --- | | 0 | Success | | 1 | Internal or transport failure | | 2 | Invalid input, unsupported command, or unsupported Node runtime | | 3 | Authentication, reauthentication, or User setup required | | 4 | Stable business, authorization, Entitlement, resource, or conflict problem | ## Upgrade or migrate ```sh bun add --global andy-partner@0.1.2 andy version --json andy auth status --json ``` The current client requires Node 20 or newer. If migrating from `@jorgemenadev/andy`, remove that deprecated package first and create fresh supported credentials; no retired user-scoped key or raw backend configuration is imported. ## Machine-readable verification Require `andy version --json` to report client `0.1.2`, public contract `1`, supported Node `>=20`, and `compatible: true`. Run `andy auth status --json` and preserve the request ID if recovery is still required. ## Next step Return to [Quickstart](/quickstart), or use [Support](/support) with the safe evidence above. --- # Widget Source: https://docs.andypartner.com/widget ## Outcome Render the released React Widget for one Agent and verify its exact allowed origin. ## Prerequisites - Active reviewed Knowledge and Public Chat. - A manifest from the target Workspace and Agent. - A client-only React boundary on an exact HTTP(S) origin. ## Install and render ```sh andy widget manifest --workspace --agent --json bun add andy-widget-react@2.0.5 ``` Render `AndyChat` and pass the manifest's Agent ID as `embedId`. Pin the exact package version returned by the manifest; do not use `latest`, the retired hosted script, or an iframe. ```tsx "use client"; import { AndyChat } from "andy-widget-react"; export function SupportWidget() { return ; } ``` ## Configure the origin ```sh andy widget configure --workspace --agent --config ./widget.json --json andy widget verify --workspace --agent --origin https://example.com --json ``` Origins are exact `scheme://host[:port]` values. Paths, credentials, query strings, fragments, and wildcards are rejected. ## Machine-readable verification Require `andy widget manifest ... --json` to return the expected Agent, exact package/version, and configuration. Then require `widget verify` to report identity, origin, Knowledge, Public Chat, and answer checks as successful. ## Next step Connect the same catalog to an agent client through [MCP](/mcp). --- # Workspaces and Agents Source: https://docs.andypartner.com/workspaces-and-agents ## Outcome Inspect one Workspace, then create and configure an Agent inside its tenant boundary. ## Prerequisites - A ready User session or allowed Workspace API Key. - The exact Workspace ID or slug. ## Copy-paste workflow ```sh andy workspace list --json andy workspace inspect --workspace --json andy workspace entitlements --workspace --json andy agent create --workspace --name "Support Agent" --language en --json andy agent configure --workspace --agent --instructions "Answer only from reviewed Knowledge." --json ``` A Workspace owns membership, roles, Entitlements, Limits, API Keys, Agents, and Usage. An Agent owns reviewed Knowledge, Public Chat, and Widget configuration. Agent deletion is soft and requires its exact ID plus confirmation: ```sh andy agent delete --workspace --agent --yes --json ``` ## Machine-readable verification ```sh andy workspace inspect --workspace --json andy agent inspect --workspace --agent --json ``` Confirm the returned `workspace.id`, `agent.workspaceId`, `agent.status`, and `meta.requestId`. All reads and writes recheck identity, role, scope, Entitlement, ownership, and Limits. ## Next step Add reviewed sources through [Knowledge](/knowledge).