Introducing XY MCP. Connect Claude Code or any MCP client to XY agents, Knowledge Bases and integrations.

Discover
XY.AI LabsThe AI native company
for Healthcare
Get Started
Developer hub

Model Context Protocol

Bring XY tools into your AI client.

Connect a Streamable HTTP MCP client to catalog agents, custom requests, workflow authoring, browser development, Knowledge Bases, schedules, and governed operations through one scoped endpoint.

Quick start

Choose interactive sign-in or an API key.

Human-operated OAuth-capable clients can connect without copying a long-lived key. Service automation and clients without browser authorization can use an organization-scoped API key at the same endpoint.

Interactive OAuth

Recommended for people using an MCP client

  1. Add the production MCP URL without an Authorization header.
  2. Your client discovers XY authorization and opens a secure browser page.
  3. Sign in to XY, confirm the selected organization, review the effective access, and approve or deny it.
  4. Return to the client. It completes the connection and refreshes access as needed without exposing an API key to you.

Interactive sign-in and user access must be enabled for your organization. Contact XY if an OAuth-capable client cannot begin authorization.

Claude Code
claude mcp add --transport http --scope user xy 'https://mcp.xy.ai/mcp'
OAuth-capable client configuration
{
  "mcpServers": {
    "xy": {
      "type": "http",
      "url": "https://mcp.xy.ai/mcp"
    }
  }
}

Personal or service API key

For services and noninteractive clients

Create a key under Organization settings → API Keys, grant only the scopes this job needs, and resolve the complete value from a private process environment.

Choose a Personal key when a person is operating the client. Calls remain bound to that user's current membership and workflow permissions.

Choose a Service key for unattended automation. Calls identify the service credential and organization rather than a human user.

API-key client configuration
{
  "mcpServers": {
    "xy": {
      "type": "http",
      "url": "https://mcp.xy.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${XY_API_KEY}"
      }
    }
  }
}

When using the API-key path, do not place the key in a shared configuration file. Resolve XY_API_KEY from an OS keychain, secret manager, or private process environment.

Do not paste portal passwords, TOTP seeds, or PINs into an AI conversation. An authorized person can add them directly in Password Vault, or a trusted backend can provision an API-managed entry through REST with organization-service access. Grant MCP credentials:read to discover only safe visible metadata, then use the exact returned credential ID. If zero or multiple entries match, the client must ask instead of guessing. See the Credentials and MFA guide.

Capabilities

Tools are discovered from the live server.

Your client negotiates the current tool catalog and input schemas through MCP tools/list on connection. That live response includes only tools whose required scopes are present on the current OAuth grant or API key, so the model does not spend context on operations it cannot call.

Catalog agents

Discover and install catalog agents, start hosted authorization handoffs, inspect installation readiness, and execute agents.

Knowledge Base

Add, inspect, complete, and delete indexed sources, then run evidence-backed questions.

Integration Factory

Extend an organization-owned integration, inspect durable runs, explicitly test generated read or write capabilities, and advance validation and organization-only promotion. Brand-new creation and private uploads start through REST.

Planner agent

Build, review, test, export, and explicitly promote reusable workflows.

Browser Studio

Develop browser steps in retained authoring sessions with scoped controls.

Queue UI Designer

Release preview: not yet generally available. Once the required routes and tools are deployed, design eligible workflow queues and publish saved versions after human review or explicitly scoped system approval. Check the live contract before use.

Analytics

Query existing analytics with dashboards:read. Release preview: dashboards:propose separately enables exact-workflow dashboard proposals using registered governed query refs, stopping at PREVIEW_READY for human review in XY. No MCP approval or publication.

Schedules

Inspect and operate recurring compiled-workflow schedules.

Run observability

Read safe execution phases. Shared planner progress release preview adds ordered durable phase, tool, artifact, and approval events. Save each cursor with its run identity; bounded polling works even when a host does not display progress notifications.

Runtime credentials

Discover safe metadata for visible Password Vault references and bind exact IDs without returning stored values. Add secrets in the UI or through trusted REST, not an AI conversation.

Common workflows

Connect tools in resource order.

MCP exposes primitives, not an invisible second lifecycle. These sequences show which resource must exist before the next tool can run; inspect every returned state and schema instead of assuming the happy path.

For queue previews, human review or system approval, publication, and rollback, follow the Queue UI Designer guide. This workflow is a release preview, not yet generally available. Verify the required routes and tools in the live references before attempting it. Automated system approval is recorded separately from human review. Use a system API key, not personal OAuth, for approval automation.

For the shared progress release preview, long-running starts return run_id immediately. Use bounded event polling from the live catalog; notifications are optional. Reconstruct snapshot, replay, then tail in sequence order, discard duplicates, and save the last applied cursor with its exact run/stream identity. A disconnected client does not cancel the worker. Read existing state after ambiguous output instead of repeating a mutation. See durable Planner progress.

dashboard_proposal_start and dashboard_proposal_get are a release preview for proposals bound to one active workflow and, for edits, both the base dashboard and immutable base version. dashboards:propose is an explicit opt-in, separate from dashboards:read; retired dashboards:write grants nothing. Personal keys and OAuth use the current human's analytics seat, both dashboard capability grants, exact workflow configure permission, and edit-time dashboard view permission. System keys act as managed organization service principals and are bounded by organization feature flags plus their explicitly selected scope, not human grants. Neither can approve or publish an analytics dashboard through public MCP proposal tools.

Compose only registered governed query refs. Missing metrics return GOVERNED_QUERY_REQUIRED, not permission to author arbitrary queries. Proposals stop at PREVIEW_READY; use the returned review_version_id to open the exact version for human approval and publication in XY. Queue UI has a separate lifecycle; its system approval tool cannot approve analytics dashboards. See REST examples and governance requirements.

Match tasks and continue into configuration

catalog_discover_agents → catalog_match_tasks → custom_agent_request_create → custom_agent_request_get

Send one to eight work descriptions without choosing agent IDs first. Feasibility and catalog fit are separate. Customer labor inputs describe current labor value, not XY pricing. Comparable history can provide a daily cost reference at observed workload; optional expected run or item volume can provide a compatible monthly operating-cost estimate. Read basis and coverage; null means unavailable, not free. These estimates are not selling prices or guaranteed savings. Ask which suggestions to pursue, then retain the original description and selected IDs in the request. Customer-specific requirements still need configuration before XY builds.

Run a catalog agent

catalog_list_agents → catalog_get_agent → agent_install → installation_get → agent_execution_start → agent_execution_get

If installation_get returns an authorization action, complete that hosted handoff before execution.

Create a Knowledge Base from a URL

catalog_get_agent → agent_install → knowledge_source_add_url → knowledge_sources_list → installation_get → agent_execution_start → agent_execution_get

Add a public HTTPS source, wait for indexing to finish, then execute a question.

Create a Knowledge Base from a file

catalog_get_agent → agent_install → knowledge_source_create_file_upload → knowledge_source_complete_upload → knowledge_sources_list → installation_get → agent_execution_start → agent_execution_get

Upload the file bytes to the signed URL directly, complete the upload, then wait for indexing before execution.

Build a workflow with the Planner agent

planner_workspace_list / planner_workspace_create → planner_workspace_get → planner_workspace_send → planner_workspace_wait / planner_workspace_events → planner_workspace_publish

MCP clients work in a native Planner session that owns planning, files, tests, and conversation history. Relay the user's messages with planner_workspace_send and the Planner's replies from planner_workspace_wait without rewriting its plan or decisions; do not run a second planning loop in the host chat. List sessions before creating one, because a lost create response is ambiguous. Read the session for its state_version and send it as expected_version with a unique run_id; after a lost response resend the exact run_id, message, and expected_version, and re-read after a conflict. Attach files as planner_workflow_files_create bundles, never as message text. Call planner_workspace_allow_internet or planner_workspace_allow_read_tests only after the user approves that access. A completed turn is not publication: show the saved version and its test result, then call planner_workspace_publish only when the user explicitly approves. The earlier build-based Planner MCP tools are retired; REST /planner/builds is covered in the Workflows guide.

Resume a Planner session

planner_workspace_list → planner_workspace_get → planner_workspace_events / planner_workspace_wait

Let the user pick an existing session; any authorized member of its organization can resume it, and listing starts no VM. Read it again for the current state_version before the next send. After an interrupted turn, replay planner_workspace_events for that run from the saved after cursor, or keep calling planner_workspace_wait while the turn is queued, claimed, or started. Keep session IDs and cursors internal. Do not create another session or send a new message to reconnect. planner_workspace_live_view returns a five-minute, view-only link to the session's browser; a paused or archived VM is not viewable.

Propose a governed analytics dashboard

dashboard_proposal_start → dashboard_proposal_get

Release preview: dashboards:propose is sensitive and opt-in, separate from dashboards:read; retired dashboards:write grants nothing. Bind the exact active workflow and one immutable base_dashboard_version_id for an edit; the service derives and validates its dashboard. Personal/OAuth callers need an analytics seat, both dashboard capability grants, exact workflow configure permission, and edit-time dashboard view permission. System keys act as managed organization service principals and are bounded by organization feature flags plus their selected scope, not human grants. Start returns run_id immediately. Use bounded event polling from the shared progress catalog, preserving each run's cursor; never repeat a mutation after ambiguous output without operation-specific replay proof. Only registered governed query refs are allowed; missing metrics stop with GOVERNED_QUERY_REQUIRED. Proposals stop at PREVIEW_READY and return review_version_id. A human must review, approve, and publish the exact version in the XY web app. No API/MCP approval or publication is exposed; Queue UI tools do not apply.

Render metrics for one production workflow

workflow_metric_dashboards_list → workflow_metric_dashboard_get

XY must first grant the API identity analytics-only view access to that exact workflow definition. The returned tile data and visualization metadata are for rendering in your own UI.

Design an existing workflow queue

queue_ui_list_targets → queue_ui_start_design → queue_ui_get_design → queue_ui_get_events → queue_ui_list_versions → queue_ui_get_version → queue_ui_send_message → queue_ui_publish

Use personal Queue UI access with explicit workflow permissions or a system key with organization authorization. For human review, a person approves the exact design version and hash in the web app. Publish takes that DESIGN version ID and compares expected_live_version_id with the PUBLICATION receipt in session.publication.live_version_id. Publish cannot approve. Send a message only when another revision is needed.

Approve and publish a queue with a system key

queue_ui_get_design → queue_ui_get_version → queue_ui_approve → queue_ui_publish

System API-key access only: explicitly grant queue_ui:read, queue_ui:approve, and queue_ui:publish. Inspect the version and validation, then approve its exact design ID and returned resolved_yaml_hash with the observed live publication receipt. Publish separately with that receipt. Approval is audited as a system decision, never human review; stop on a conflict. Personal OAuth cannot use the approval stage.

Ask XY to deliver an agent

custom_agent_request_create → custom_agent_request_get → custom_agent_request_message

Create a request and retain its ID/form URL. The customer can complete the hosted form, or XY can gather the remaining requirements with them. Submission is not workflow execution.

Submit approved tasks as partially completed requests

custom_agent_request_submit_bulk → custom_agent_request_get → custom_agent_request_deployments → custom_agent_request_usage

Submit 1–50 names and descriptions with a stable batch idempotency key. Preserve each returned task_id, request_id and form_url. These requests are partially configured; nothing is built or executed automatically. Keep the same request ID through review and delivery. Usage returns recorded period totals, not complete billing.

Receive daily results and workflow alerts

webhook_configuration → webhook_subscription_create → webhook_subscription_test → webhook_deliveries_list

Use a public HTTPS receiver and explicit webhooks:read/write grants, or configure the same receiver in XY Settings. Save the one-time signing secret securely; it is not an API key. Select workflow IDs for run completion/failure or daily results, and declared review states for human-review alerts. Daily reports use local timezone/send time. New-item counts are not successful-processing counts; current queues are backlog at report time. Verify signatures and deduplicate event IDs. Request usage updates replace totals for their period; never add corrections together.

Live reference

Current MCP tools and input schemas.

This catalog is read from the production MCP registry at request time and refreshed every minute. Tool additions and schema changes appear here after the MCP deployment without a website release.

This public reference shows every available tool contract. An authenticated tools/list response is narrower: it omits tools the current OAuth grant or API key cannot call.

MCP covers catalog discovery, installations, starting and inspecting hosted authorization handoffs, Knowledge Base sources, agent executions, custom-agent requests, the Planner agent, Browser Studio, credentials, on-demand promoted workflow executions, schedules, run phases, usage, and read-only analytics. Dashboard proposals and shared durable Planner progress are release previews; confirm their tools in the live catalog. Analytics dashboard approval and publication remain human web actions. Review-item decisions and approved agent or installation metrics remain direct REST operations. Explicitly granted workflow definitions also expose approved metric views through workflow_metric_dashboards_list and workflow_metric_dashboard_get.

174 live tools

Showing 174 of 174 tools

agent_execution_getPoll one catalog-agent execution for status and its stable result.
Input schema
{
  "properties": {
    "execution_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Execution Id",
      "type": "string"
    }
  },
  "required": [
    "execution_id"
  ],
  "title": "agent_execution_getArguments",
  "type": "object",
  "additionalProperties": false
}
agent_execution_startStart an asynchronous run of an installed catalog agent.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "input": {
      "additionalProperties": true,
      "title": "Input",
      "type": "object"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Metadata"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "installation_id",
    "input"
  ],
  "title": "agent_execution_startArguments",
  "type": "object",
  "additionalProperties": false
}
agent_executions_listList organization-scoped catalog-agent executions.
Input schema
{
  "properties": {
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "agent_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    },
    "installation_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Installation Id"
    },
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "agent_executions_listArguments",
  "type": "object",
  "additionalProperties": false
}
agent_installInstall an entitled catalog agent using its returned setup schema.
Input schema
{
  "properties": {
    "agent_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Agent Id",
      "type": "string"
    },
    "configuration": {
      "additionalProperties": true,
      "title": "Configuration",
      "type": "object"
    },
    "agent_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Version"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "agent_id",
    "configuration"
  ],
  "title": "agent_installArguments",
  "type": "object",
  "additionalProperties": false
}
agent_uninstallRetire an installation and free the name it holds for reuse. Use this to clear a failed or superseded installation. Without it a Knowledge Base name stays claimed by the definition the install created, and every later install under that name fails with KNOWLEDGE_BASE_NAME_CONFLICT. Idempotent.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id"
  ],
  "title": "agent_uninstallArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_acceptExplicitly accept exact draft receipts after user review. Include at least one workflow-spec receipt returned by authoring_drafts; acceptance never publishes or starts a Planner build.
Input schema
{
  "$defs": {
    "AuthoringArtifactReference": {
      "additionalProperties": false,
      "properties": {
        "artifact_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Id",
          "type": "string"
        },
        "artifact_version_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Version Id",
          "type": "string"
        },
        "version": {
          "minimum": 1,
          "title": "Version",
          "type": "integer"
        },
        "kind": {
          "enum": [
            "discovery-spec",
            "workflow-spec",
            "dashboard-spec",
            "testing-agreement"
          ],
          "title": "Kind",
          "type": "string"
        },
        "content_hash": {
          "maxLength": 128,
          "minLength": 32,
          "title": "Content Hash",
          "type": "string"
        },
        "review_status": {
          "enum": [
            "DRAFT",
            "FINALIZED"
          ],
          "title": "Review Status",
          "type": "string"
        }
      },
      "required": [
        "artifact_id",
        "artifact_version_id",
        "version",
        "kind",
        "content_hash",
        "review_status"
      ],
      "title": "AuthoringArtifactReference",
      "type": "object"
    }
  },
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    },
    "artifact_versions": {
      "items": {
        "$ref": "#/$defs/AuthoringArtifactReference"
      },
      "maxItems": 20,
      "minItems": 1,
      "title": "Artifact Versions",
      "type": "array"
    },
    "resource_version": {
      "exclusiveMinimum": 0,
      "title": "Resource Version",
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "authoring_id",
    "artifact_versions",
    "resource_version",
    "idempotency_key"
  ],
  "title": "authoring_acceptArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_cancelRequest cooperative cancellation of active authoring work while retaining its conversation and immutable drafts. Use the latest resource_version and keep the same idempotency key when retrying an ambiguous response.
Input schema
{
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    },
    "resource_version": {
      "exclusiveMinimum": 0,
      "title": "Resource Version",
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "authoring_id",
    "resource_version",
    "idempotency_key"
  ],
  "title": "authoring_cancelArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_discardExplicitly discard exact draft receipts while retaining the conversation and audit history. This cannot be inferred from a revision request.
Input schema
{
  "$defs": {
    "AuthoringArtifactReference": {
      "additionalProperties": false,
      "properties": {
        "artifact_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Id",
          "type": "string"
        },
        "artifact_version_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Version Id",
          "type": "string"
        },
        "version": {
          "minimum": 1,
          "title": "Version",
          "type": "integer"
        },
        "kind": {
          "enum": [
            "discovery-spec",
            "workflow-spec",
            "dashboard-spec",
            "testing-agreement"
          ],
          "title": "Kind",
          "type": "string"
        },
        "content_hash": {
          "maxLength": 128,
          "minLength": 32,
          "title": "Content Hash",
          "type": "string"
        },
        "review_status": {
          "enum": [
            "DRAFT",
            "FINALIZED"
          ],
          "title": "Review Status",
          "type": "string"
        }
      },
      "required": [
        "artifact_id",
        "artifact_version_id",
        "version",
        "kind",
        "content_hash",
        "review_status"
      ],
      "title": "AuthoringArtifactReference",
      "type": "object"
    }
  },
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    },
    "artifact_versions": {
      "items": {
        "$ref": "#/$defs/AuthoringArtifactReference"
      },
      "maxItems": 20,
      "minItems": 1,
      "title": "Artifact Versions",
      "type": "array"
    },
    "resource_version": {
      "exclusiveMinimum": 0,
      "title": "Resource Version",
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "authoring_id",
    "artifact_versions",
    "resource_version",
    "idempotency_key"
  ],
  "title": "authoring_discardArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_draftsList exact immutable draft receipts available for review. Present their business meaning to the user and retain the complete receipt for a later accept or discard decision.
Input schema
{
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    }
  },
  "required": [
    "authoring_id"
  ],
  "title": "authoring_draftsArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_eventsRead durable, user-safe progress after an optional opaque cursor. Summarize meaningful progress near the user's request and continue until a terminal or input-required state; do not dump raw event names.
Input schema
{
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    },
    "after": {
      "anyOf": [
        {
          "maxLength": 2000,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "After"
    },
    "limit": {
      "default": 100,
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "authoring_id"
  ],
  "title": "authoring_eventsArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_getReconnect to one durable workflow-design conversation. Use the returned plain-language status, questions, drafts, handoff, and resource_version; do not expose implementation fields unless the user asks for debugging details.
Input schema
{
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    }
  },
  "required": [
    "authoring_id"
  ],
  "title": "authoring_getArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_messagesReplay the retained user and assistant conversation after an optional opaque cursor. Preserve next_cursor across reconnects; message history is not a model transcript or reasoning log.
Input schema
{
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    },
    "after": {
      "anyOf": [
        {
          "maxLength": 2000,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "After"
    },
    "limit": {
      "default": 100,
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "authoring_id"
  ],
  "title": "authoring_messagesArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_sendAnswer a business question or request a revision in ordinary language. Reuse the exact authoring_id and latest resource_version returned by the server. Source references are appended by default; replacement is explicit.
Input schema
{
  "$defs": {
    "CredentialReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "credential",
          "title": "Type",
          "type": "string"
        },
        "credential_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Credential Id",
          "type": "string"
        },
        "domain": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Domain"
        },
        "display_name": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        }
      },
      "required": [
        "type",
        "credential_id"
      ],
      "title": "CredentialReference",
      "type": "object"
    },
    "ExistingWorkflowReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "workflow_version",
          "title": "Type",
          "type": "string"
        },
        "workflow_definition_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Workflow Definition Id",
          "type": "string"
        },
        "workflow_version_id": {
          "description": "Exact immutable version; a mutable workflow name is insufficient.",
          "maxLength": 500,
          "minLength": 1,
          "title": "Workflow Version Id",
          "type": "string"
        }
      },
      "required": [
        "type",
        "workflow_definition_id",
        "workflow_version_id"
      ],
      "title": "ExistingWorkflowReference",
      "type": "object"
    },
    "InputArtifactReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "artifact_version",
          "title": "Type",
          "type": "string"
        },
        "artifact_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Id",
          "type": "string"
        },
        "artifact_version_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Version Id",
          "type": "string"
        },
        "content_hash": {
          "maxLength": 128,
          "minLength": 32,
          "title": "Content Hash",
          "type": "string"
        }
      },
      "required": [
        "type",
        "artifact_id",
        "artifact_version_id",
        "content_hash"
      ],
      "title": "InputArtifactReference",
      "type": "object"
    },
    "RecordedTaskReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "recorded_task",
          "title": "Type",
          "type": "string"
        },
        "recorded_task_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Recorded Task Id",
          "type": "string"
        },
        "display_name": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        }
      },
      "required": [
        "type",
        "recorded_task_id"
      ],
      "title": "RecordedTaskReference",
      "type": "object"
    },
    "UploadedFileReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "uploaded_file",
          "title": "Type",
          "type": "string"
        },
        "file_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "File Id",
          "type": "string"
        },
        "file_name": {
          "maxLength": 500,
          "minLength": 1,
          "title": "File Name",
          "type": "string"
        },
        "content_type": {
          "maxLength": 200,
          "minLength": 1,
          "title": "Content Type",
          "type": "string"
        },
        "content_hash": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 32,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Digest only; file bytes remain in the owned object store.",
          "title": "Content Hash"
        }
      },
      "required": [
        "type",
        "file_id",
        "file_name",
        "content_type"
      ],
      "title": "UploadedFileReference",
      "type": "object"
    },
    "WorkflowLogicChangeReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "workflow_logic_change",
          "title": "Type",
          "type": "string"
        },
        "change_id": {
          "maxLength": 160,
          "minLength": 1,
          "title": "Change Id",
          "type": "string"
        }
      },
      "required": [
        "type",
        "change_id"
      ],
      "title": "WorkflowLogicChangeReference",
      "type": "object"
    }
  },
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    },
    "message": {
      "maxLength": 200000,
      "minLength": 1,
      "title": "Message",
      "type": "string"
    },
    "resource_version": {
      "exclusiveMinimum": 0,
      "title": "Resource Version",
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    },
    "source_references": {
      "anyOf": [
        {
          "items": {
            "discriminator": {
              "mapping": {
                "artifact_version": "#/$defs/InputArtifactReference",
                "credential": "#/$defs/CredentialReference",
                "recorded_task": "#/$defs/RecordedTaskReference",
                "uploaded_file": "#/$defs/UploadedFileReference",
                "workflow_logic_change": "#/$defs/WorkflowLogicChangeReference",
                "workflow_version": "#/$defs/ExistingWorkflowReference"
              },
              "propertyName": "type"
            },
            "oneOf": [
              {
                "$ref": "#/$defs/UploadedFileReference"
              },
              {
                "$ref": "#/$defs/RecordedTaskReference"
              },
              {
                "$ref": "#/$defs/ExistingWorkflowReference"
              },
              {
                "$ref": "#/$defs/CredentialReference"
              },
              {
                "$ref": "#/$defs/WorkflowLogicChangeReference"
              },
              {
                "$ref": "#/$defs/InputArtifactReference"
              }
            ]
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source References"
    },
    "source_reference_mode": {
      "default": "append",
      "enum": [
        "append",
        "replace"
      ],
      "title": "Source Reference Mode",
      "type": "string"
    }
  },
  "required": [
    "authoring_id",
    "message",
    "resource_version",
    "idempotency_key"
  ],
  "title": "authoring_sendArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_startStart generic Marketplace authoring in the API key's organization. This is not the STAFF cross-organization CIE Planner entry point. For customer meetings, evidence, specifications, changelogs, or CIE skills, use internal_cie_authoring_start with an explicit organization instead. Attach exact recording, file, credential, workflow-version, or artifact references only when already known. Save the returned session_id (pass it as authoring_id) and resource_version, then follow authoring_events or authoring_get while work is running.
Input schema
{
  "$defs": {
    "CredentialReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "credential",
          "title": "Type",
          "type": "string"
        },
        "credential_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Credential Id",
          "type": "string"
        },
        "domain": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Domain"
        },
        "display_name": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        }
      },
      "required": [
        "type",
        "credential_id"
      ],
      "title": "CredentialReference",
      "type": "object"
    },
    "ExistingWorkflowReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "workflow_version",
          "title": "Type",
          "type": "string"
        },
        "workflow_definition_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Workflow Definition Id",
          "type": "string"
        },
        "workflow_version_id": {
          "description": "Exact immutable version; a mutable workflow name is insufficient.",
          "maxLength": 500,
          "minLength": 1,
          "title": "Workflow Version Id",
          "type": "string"
        }
      },
      "required": [
        "type",
        "workflow_definition_id",
        "workflow_version_id"
      ],
      "title": "ExistingWorkflowReference",
      "type": "object"
    },
    "InputArtifactReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "artifact_version",
          "title": "Type",
          "type": "string"
        },
        "artifact_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Id",
          "type": "string"
        },
        "artifact_version_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Artifact Version Id",
          "type": "string"
        },
        "content_hash": {
          "maxLength": 128,
          "minLength": 32,
          "title": "Content Hash",
          "type": "string"
        }
      },
      "required": [
        "type",
        "artifact_id",
        "artifact_version_id",
        "content_hash"
      ],
      "title": "InputArtifactReference",
      "type": "object"
    },
    "RecordedTaskReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "recorded_task",
          "title": "Type",
          "type": "string"
        },
        "recorded_task_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "Recorded Task Id",
          "type": "string"
        },
        "display_name": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Display Name"
        }
      },
      "required": [
        "type",
        "recorded_task_id"
      ],
      "title": "RecordedTaskReference",
      "type": "object"
    },
    "UploadedFileReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "uploaded_file",
          "title": "Type",
          "type": "string"
        },
        "file_id": {
          "maxLength": 500,
          "minLength": 1,
          "title": "File Id",
          "type": "string"
        },
        "file_name": {
          "maxLength": 500,
          "minLength": 1,
          "title": "File Name",
          "type": "string"
        },
        "content_type": {
          "maxLength": 200,
          "minLength": 1,
          "title": "Content Type",
          "type": "string"
        },
        "content_hash": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 32,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Digest only; file bytes remain in the owned object store.",
          "title": "Content Hash"
        }
      },
      "required": [
        "type",
        "file_id",
        "file_name",
        "content_type"
      ],
      "title": "UploadedFileReference",
      "type": "object"
    },
    "WorkflowLogicChangeReference": {
      "additionalProperties": false,
      "properties": {
        "type": {
          "const": "workflow_logic_change",
          "title": "Type",
          "type": "string"
        },
        "change_id": {
          "maxLength": 160,
          "minLength": 1,
          "title": "Change Id",
          "type": "string"
        }
      },
      "required": [
        "type",
        "change_id"
      ],
      "title": "WorkflowLogicChangeReference",
      "type": "object"
    }
  },
  "properties": {
    "message": {
      "maxLength": 200000,
      "minLength": 1,
      "title": "Message",
      "type": "string"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    },
    "name": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "source_references": {
      "anyOf": [
        {
          "items": {
            "discriminator": {
              "mapping": {
                "artifact_version": "#/$defs/InputArtifactReference",
                "credential": "#/$defs/CredentialReference",
                "recorded_task": "#/$defs/RecordedTaskReference",
                "uploaded_file": "#/$defs/UploadedFileReference",
                "workflow_logic_change": "#/$defs/WorkflowLogicChangeReference",
                "workflow_version": "#/$defs/ExistingWorkflowReference"
              },
              "propertyName": "type"
            },
            "oneOf": [
              {
                "$ref": "#/$defs/UploadedFileReference"
              },
              {
                "$ref": "#/$defs/RecordedTaskReference"
              },
              {
                "$ref": "#/$defs/ExistingWorkflowReference"
              },
              {
                "$ref": "#/$defs/CredentialReference"
              },
              {
                "$ref": "#/$defs/WorkflowLogicChangeReference"
              },
              {
                "$ref": "#/$defs/InputArtifactReference"
              }
            ]
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source References"
    }
  },
  "required": [
    "message",
    "idempotency_key"
  ],
  "title": "authoring_startArguments",
  "type": "object",
  "additionalProperties": false
}
authoring_submitHand one explicitly accepted immutable Workflow Spec to the governed request lifecycle. target=workflow_request creates a reviewable request; target=planner_build additionally requires agent_requests:approve and starts exactly one Planner build. Retry an ambiguous response with the same idempotency key and resource version.
Input schema
{
  "properties": {
    "authoring_id": {
      "description": "The authoring session's id (starts with sess_auth_).",
      "maxLength": 200,
      "minLength": 16,
      "pattern": "^sess_auth_[A-Za-z0-9_-]+$",
      "title": "Authoring Id",
      "type": "string"
    },
    "workflow_spec_version_id": {
      "maxLength": 500,
      "minLength": 1,
      "title": "Workflow Spec Version Id",
      "type": "string"
    },
    "target": {
      "enum": [
        "workflow_request",
        "planner_build"
      ],
      "title": "Target",
      "type": "string"
    },
    "resource_version": {
      "exclusiveMinimum": 0,
      "title": "Resource Version",
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "authoring_id",
    "workflow_spec_version_id",
    "target",
    "resource_version",
    "idempotency_key"
  ],
  "title": "authoring_submitArguments",
  "type": "object",
  "additionalProperties": false
}
browser_api_map_buildBuild or update this organization's OpenAPI-style map from captured calls.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "host": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Host"
    },
    "url_contains": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url Contains"
    },
    "method": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Method"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_api_map_buildArguments",
  "type": "object",
  "additionalProperties": false
}
browser_api_map_getRead this organization's saved endpoint map as a tree, OpenAPI, or both.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "host": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Host"
    },
    "format": {
      "default": "both",
      "enum": [
        "tree",
        "openapi",
        "both"
      ],
      "title": "Format",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_api_map_getArguments",
  "type": "object",
  "additionalProperties": false
}
browser_apply_draftSend the Browser Studio draft through the existing Planner step test path. Returns the step test's outcome: status (passed, failed or incomplete), step_number, final_message, result_preview of the test output, error_summary when it failed, and draft {changed, summary, lines}. XY STAFF may pass debug=true to also get the raw event stream.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "edited_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Edited Code"
    },
    "debug": {
      "default": false,
      "description": "XY STAFF only. Include sanitized trace detail (logs, token counts, tool timings). Off by default: events are user-facing progress summaries. Never relay debug detail to a customer.",
      "title": "Debug",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_apply_draftArguments",
  "type": "object",
  "additionalProperties": false
}
browser_cancel_promptCancel the current Browser Copilot authoring turn.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_cancel_promptArguments",
  "type": "object",
  "additionalProperties": false
}
browser_cdp_commandRun raw page-target CDP; it may expose cookies or page secrets.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "method": {
      "title": "Method",
      "type": "string"
    },
    "params": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Params"
    },
    "tab_id": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tab Id"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id",
    "method"
  ],
  "title": "browser_cdp_commandArguments",
  "type": "object",
  "additionalProperties": false
}
browser_close_sessionClose a retained browser session and release its capacity allocation.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_close_sessionArguments",
  "type": "object",
  "additionalProperties": false
}
browser_create_sessionStart a Browser Studio session for one step of a Planner build. build_id and step_number are required: Browser Studio and Browser Copilot work only inside an existing Planner build (start one with planner_start_build); there is no standalone session. Returns vnc_url, the user's live view of the build: the same link for every session and browser step of this build, so show it once ('Watch the browser live: <url>') and do not hand out a new link per command. When can_control is true the page has a Take control button the user presses themselves; share watch_url only if they ask to show the browser to someone else. Pass the returned session_id as browser_id to the other browser tools.
Input schema
{
  "properties": {
    "build_id": {
      "maxLength": 200,
      "minLength": 6,
      "pattern": "^pbld_[A-Za-z0-9_-]+$",
      "title": "Build Id",
      "type": "string"
    },
    "step_number": {
      "exclusiveMinimum": 0,
      "title": "Step Number",
      "type": "integer"
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url"
    },
    "credential_id": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credential Id"
    },
    "recorded_task_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Recorded Task Id"
    },
    "existing_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Existing Code"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "build_id",
    "step_number"
  ],
  "title": "browser_create_sessionArguments",
  "type": "object",
  "additionalProperties": false
}
browser_endpoint_observer_setStart or stop capturing API requests made by this browser session.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "enabled": {
      "default": true,
      "title": "Enabled",
      "type": "boolean"
    },
    "tab_id": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tab Id"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_endpoint_observer_setArguments",
  "type": "object",
  "additionalProperties": false
}
browser_get_draftRead the reusable browser activity draft from a retained session.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_get_draftArguments",
  "type": "object",
  "additionalProperties": false
}
browser_get_sessionRead session state, including the build's live view link (vnc_url). The link is the same one the user already has for this build; show it again only if they have not seen it or it changed after expiring.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_get_sessionArguments",
  "type": "object",
  "additionalProperties": false
}
browser_list_toolsList safe Browser Studio authoring commands.
Input schema
{
  "properties": {
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "browser_list_toolsArguments",
  "type": "object",
  "additionalProperties": false
}
browser_observed_endpoint_getRead one captured request and response after secret-field redaction.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "storage_path": {
      "maxLength": 200,
      "minLength": 35,
      "pattern": "^local://observed-endpoint/ep_[A-Za-z0-9_-]+$",
      "title": "Storage Path",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id",
    "storage_path"
  ],
  "title": "browser_observed_endpoint_getArguments",
  "type": "object",
  "additionalProperties": false
}
browser_observed_endpoints_listList a compact, redacted index of API requests captured in this session.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "url_contains": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url Contains"
    },
    "method": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Method"
    },
    "status_code": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status Code"
    },
    "start_time": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Start Time"
    },
    "end_time": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "End Time"
    },
    "limit": {
      "default": 25,
      "maximum": 25,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id"
  ],
  "title": "browser_observed_endpoints_listArguments",
  "type": "object",
  "additionalProperties": false
}
browser_promptAsk Browser Studio to author or revise reusable browser activity code. Returns the turn's outcome once it finishes: status, final_message (the Copilot's answer), draft {changed, lines, summary}, tool_calls and usage_total. Read the code itself with browser_get_draft. XY STAFF may pass debug=true to also get the raw event stream.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "prompt": {
      "title": "Prompt",
      "type": "string"
    },
    "debug": {
      "default": false,
      "description": "XY STAFF only. Include sanitized trace detail (logs, token counts, tool timings). Off by default: events are user-facing progress summaries. Never relay debug detail to a customer.",
      "title": "Debug",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id",
    "prompt"
  ],
  "title": "browser_promptArguments",
  "type": "object",
  "additionalProperties": false
}
browser_recorded_tasks_listFind browser recordings for an FDE implementation build. Search by the name a person sees, recorded-task ID, or domain. Pass the exact recorded_task_id from one unambiguous match to planner_start_build as context.recorded_task_id. Ask the user when zero or multiple entries match; never guess. The response never contains code, transcripts, screenshots, recordings, secrets, owner IDs, or Firestore document IDs. Do not use this for CIE meeting evidence or artifact work. CIE reads organization-scoped recordings with internal_recorded_tasks_* and attaches them to internal_cie_authoring_start or internal_cie_authoring_send.
Input schema
{
  "properties": {
    "query": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "limit": {
      "default": 50,
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "browser_recorded_tasks_listArguments",
  "type": "object",
  "additionalProperties": false
}
browser_run_commandRun one safe Browser Studio command in a retained session.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "tool": {
      "title": "Tool",
      "type": "string"
    },
    "input": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Input"
    },
    "tab_id": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tab Id"
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id",
    "tool"
  ],
  "title": "browser_run_commandArguments",
  "type": "object",
  "additionalProperties": false
}
browser_set_controlSwitch a browser session between human and shared control. The user takes control themselves with the Take control button on the live view page; do not call this to hand them control.
Input schema
{
  "properties": {
    "browser_id": {
      "description": "The browser's id (starts with bas_), returned by browser_create_session.",
      "maxLength": 128,
      "minLength": 5,
      "pattern": "^bas_[A-Za-z0-9_-]+$",
      "title": "Browser Id",
      "type": "string"
    },
    "mode": {
      "enum": [
        "human",
        "shared"
      ],
      "title": "Mode",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "browser_id",
    "mode"
  ],
  "title": "browser_set_controlArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_clipboard_pastePaste user-provided text into the focused remote browser field. Prefer the human controller's clipboard UI for passwords and MFA codes; do not ask the user to disclose those secrets in the conversation.
Input schema
{
  "properties": {
    "trust_id": {
      "pattern": "^bts_[a-f0-9]{32}$",
      "title": "Trust Id",
      "type": "string"
    },
    "text": {
      "maxLength": 20000,
      "title": "Text",
      "type": "string"
    }
  },
  "required": [
    "trust_id",
    "text"
  ],
  "title": "browser_trust_clipboard_pasteArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_clipboard_readRead the remote clipboard only when explicitly requested by the user. Clipboard text can be sensitive. This operation exposes at most 20,000 characters and is not a background polling or automatic inspection tool.
Input schema
{
  "properties": {
    "trust_id": {
      "pattern": "^bts_[a-f0-9]{32}$",
      "title": "Trust Id",
      "type": "string"
    }
  },
  "required": [
    "trust_id"
  ],
  "title": "browser_trust_clipboard_readArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_profiles_listList this organization's safe trusted-portal profile metadata. Requires explicit organization-wide browser:trust approval. No cookies, stored passwords, proxy configuration or internal profile paths are returned.
Input schema
{
  "properties": {
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    }
  },
  "title": "browser_trust_profiles_listArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_session_cancelClose an unfinished human sign-in without activating its profile.
Input schema
{
  "properties": {
    "trust_id": {
      "pattern": "^bts_[a-f0-9]{32}$",
      "title": "Trust Id",
      "type": "string"
    }
  },
  "required": [
    "trust_id"
  ],
  "title": "browser_trust_session_cancelArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_session_finalizeSave a human sign-in only after the person confirms they finished. Saving may let waiting workflows retry; they still validate portal authentication. Do not finalize an unfinished or timed-out sign-in.
Input schema
{
  "properties": {
    "trust_id": {
      "pattern": "^bts_[a-f0-9]{32}$",
      "title": "Trust Id",
      "type": "string"
    }
  },
  "required": [
    "trust_id"
  ],
  "title": "browser_trust_session_finalizeArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_session_getRead an active trust session and its expiring controller capability.
Input schema
{
  "properties": {
    "trust_id": {
      "pattern": "^bts_[a-f0-9]{32}$",
      "title": "Trust Id",
      "type": "string"
    }
  },
  "required": [
    "trust_id"
  ],
  "title": "browser_trust_session_getArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_session_startOpen the existing human trust ceremony for an approved portal profile. Show controller_url to the authorized person so they can sign in and complete MFA. This is independent of Planner authoring. Reuses the active partner session for this profile. Never ask the person to send passwords in chat.
Input schema
{
  "properties": {
    "profile_id": {
      "maxLength": 128,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
      "title": "Profile Id",
      "type": "string"
    }
  },
  "required": [
    "profile_id"
  ],
  "title": "browser_trust_session_startArguments",
  "type": "object",
  "additionalProperties": false
}
browser_trust_sign_ins_listList workflows waiting for a human portal sign-in. The same waits produce workflow.sign_in_required and workflow.sign_in_resolved webhook notifications when the organization subscribes to those events.
Input schema
{
  "properties": {
    "workflow_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workflow Id"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "browser_trust_sign_ins_listArguments",
  "type": "object",
  "additionalProperties": false
}
catalog_discover_agentsBrowse XY use cases and a bounded page of third-party software. These are broad agent categories, not installed or immediately executable agents. Use each card's short_description and capabilities to explain the work it performs. An expected item means the primary business record handled by that work, not an hour or a model token. The correct business unit depends on the customer's process; do not invent a unit from a job title. Cost evidence and workflow implementation details are not part of the catalog. XY cards may include icon_url: a monochrome SVG for your UI to recolor as a CSS mask. Use a fallback when null; no color argument is needed. external_listings separately contains cached public Microsoft/AWS software metadata with provider/source links and optional logo_url for display. A logo is a product/publisher image, not an XY avatar; null needs a fallback. Check external_catalogs for freshness and unavailable providers; missing feeds do not mean no such product exists. XY cards are returned together; external listings default to 25 per page (maximum 100). Follow external_pagination.next_offset using external_offset, optionally filter by external_provider. If catalog_version changes between pages, restart paging. Matching searches the full cache, not only this page.
Input schema
{
  "properties": {
    "external_provider": {
      "anyOf": [
        {
          "enum": [
            "microsoft",
            "aws"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "External Provider"
    },
    "external_limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "External Limit",
      "type": "integer"
    },
    "external_offset": {
      "default": 0,
      "maximum": 12000,
      "minimum": 0,
      "title": "External Offset",
      "type": "integer"
    }
  },
  "title": "catalog_discover_agentsArguments",
  "type": "object",
  "additionalProperties": false
}
catalog_get_agentInspect one catalog agent, including exact setup and input schemas.
Input schema
{
  "properties": {
    "agent_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Agent Id",
      "type": "string"
    }
  },
  "required": [
    "agent_id"
  ],
  "title": "catalog_get_agentArguments",
  "type": "object",
  "additionalProperties": false
}
catalog_list_agentsList published agent versions entitled to this organization.
Input schema
{
  "properties": {},
  "title": "catalog_list_agentsArguments",
  "type": "object",
  "additionalProperties": false
}
catalog_match_tasksAssess 1-8 plain-language tasks and suggest current Discover use cases. max_external_matches defaults to 4; request up to 10 external alternatives per task for a wider comparison. Fewer may qualify; XY matches stay at 4. Wider results may take longer. Where enabled, concurrency limits count active requests across all of an organization's keys and pods, not tasks. On a concurrency 429 or busy 503, honor Retry-After before retrying. Rejected work does not invoke a matching model; neither error means that the task has no matching agent. Do not choose an agent first: describe the work, inputs, systems, constraints, and desired outcome. A task name is optional, echoed for display, and ignored for matching. Task IDs are optional caller-owned correlation handles and never influence matching. Each result separates agentizability (whether XY can automate the work) from zero to four scored catalog matches (which current cards fit); the two scores are not interchangeable and neither is a share of human hours saved. Matches can be many-to-many and cross-industry. Optionally include monthly customer labor inputs. The returned labor_value is deterministic human-cost context, not an XY price, quote, or guaranteed savings, and it does not affect model scores. Supplying labor_baseline.remaining_human_hours_per_month also yields labor_value.estimated_human_effort_reduction, a 0-1 fraction: current human hours minus remaining human hours, divided by current human hours. 0.8 means 80% fewer human hours under the caller's estimate, not 80% agent runtime. Its basis is caller_supplied_remaining_hours, not measured evidence. Include all remaining work, review, corrections, and oversight for the same workload and quality standard. If remaining hours are unknown, omit them: reduction and its basis are null, without blocking cost estimates. Never infer a numerical split from the task description, feasibility score, or fit score. A result can be agentizable with no current match. After the user chooses suggested cards—or chooses to proceed without one—use custom_agent_request_create to capture the customer-specific configuration required before build and execution. With no workload estimate, a match with recent XY cost history returns a reference daily operating cost at a comparable deployment's observed workload. When reference_items_per_day is present, it is the average recorded business records per workflow-day, using the same sample as the reference daily cost. Null means no comparable item-volume evidence; never infer a record count from human hours or workflow runs. It is not a customer-specific amount. Optionally provide expected_items_per_month for primary work items (e.g. claims or payments), or expected_runs_per_month for workflow invocations. These are separate from labor work units. When comparable XY history is sufficient, volume yields one indicative monthly operating_cost_estimate; item-volume evidence takes precedence when both inputs are supplied. Missing evidence yields null, never an invented zero. Raw cost evidence is not exposed. Neither estimate is a quote or guaranteed savings. XY cost fields require separate organization approval (useOperatingCostReports). Without it all four operating_cost_* fields are null; matching and public vendor prices remain available. Reported XY dollars include estimated logging costs allocated to the workflow; raw evidence and vendor prices are unchanged. For an entire project, supply expected_items instead of monthly volume. Optionally add project_duration_months for monthly averages. The result has period project, estimated_project_operating_cost_usd, average_items_per_month, and estimated_average_monthly_operating_cost_usd. Project cost uses comparable per-item history; monthly averages divide by duration and assume evenly spread workload. Without duration, the project total is available but project_duration_months and both monthly averages are null, not zero. Fractional months are allowed. Duration requires expected_items. Do not combine project inputs with expected_items_per_month or expected_runs_per_month. Missing item evidence still yields null; neither a daily reference nor monthly run history substitutes for project item cost. labor_baseline remains optional monthly human-cost comparison data, independent of operating cost. Alongside XY matches, external_matches may suggest relevant cached public Microsoft/AWS listings. These remain separate from XY matches and never include an XY operating-cost estimate or deployment capability. Follow their source links; do not pass external listing IDs as XY selections when creating a workflow request. Discovery does not purchase, configure, or deploy third-party software. Check external_catalogs for feed coverage. AWS and Microsoft listings can include vendor_pricing with public USD rates, original billing dimensions, normalized explicit units, conditions and checked_at. Use the same expected_items_per_month or expected_items for all providers. Add expected_item_unit (e.g. page, document or ticket). Optional workload_units_per_item contains known business relationships such as {"page": 5} per document. The server resolves the priced operation from the description, validates published IDs, converts units and calculates charges. No provider-specific request or caller-selected rate ID is needed. Unknown ratios, ambiguous operations or billing conditions yield specific needs_more_information reasons, not an invented total. Each component shows billed quantity, units_per_item and conversion_basis. Fixed plans and contract fees remain metadata, not linear per-item rates. Conditional overage prices remain visible but require subscription/allowance scoping before an estimate; annual commitments are not plain monthly fees. Legacy external_pricing_inputs is deprecated but still supported; do not combine it with shared workload units. Never equate pages with documents/runs. Operation resolution is model-assisted; dollar math and conversion ratios are not. Existing XY inputs are unchanged and still require comparable history; a supplied unit does not establish compatibility. The result uses the same operating_cost_estimate/status fields with basis published_vendor_rates and partial coverage. Other fees are excluded. Monthly/contract prices are displayed but not multiplied by item volume. Missing, stale, expired or unknown rates yield no estimate, never $0. An explicitly zero published rate means that vendor charge only is zero.
Input schema
{
  "$defs": {
    "DiscoveryLaborBaseline": {
      "additionalProperties": false,
      "description": "Customer-supplied human effort for one task, normalized to one month.",
      "properties": {
        "human_hours_per_month": {
          "description": "Current human hours spent on this task in a typical month.",
          "exclusiveMinimum": 0,
          "maximum": 1000000,
          "title": "Human Hours Per Month",
          "type": "number"
        },
        "fully_loaded_hourly_cost_usd": {
          "description": "Current fully loaded hourly labor cost in USD, including salary, benefits, and employer overhead.",
          "exclusiveMinimum": 0,
          "maximum": 1000000,
          "title": "Fully Loaded Hourly Cost Usd",
          "type": "number"
        },
        "remaining_human_hours_per_month": {
          "anyOf": [
            {
              "maximum": 1000000,
              "minimum": 0,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Estimated total monthly human effort remaining after automation, including unautomated work, review, escalations, corrections, and ongoing oversight. Compare the same workload and quality standard as human_hours_per_month. Omit when unknown; zero explicitly assumes no remaining human effort. Cannot exceed current human hours.",
          "title": "Remaining Human Hours Per Month"
        },
        "work_units_per_month": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 1000000000,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional current monthly task volume, used only to express the human labor value per work unit.",
          "title": "Work Units Per Month"
        }
      },
      "required": [
        "human_hours_per_month",
        "fully_loaded_hourly_cost_usd"
      ],
      "title": "DiscoveryLaborBaseline",
      "type": "object"
    },
    "DiscoveryTask": {
      "additionalProperties": false,
      "properties": {
        "id": {
          "anyOf": [
            {
              "maxLength": 100,
              "minLength": 1,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional caller-owned correlation handle. Omit it to receive task-1, task-2, and so on. It is never shown to the matching model.",
          "title": "Id"
        },
        "name": {
          "anyOf": [
            {
              "maxLength": 200,
              "minLength": 1,
              "pattern": "\\S",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional human-readable task title, echoed in the result for display. Matching uses the description, not this title.",
          "title": "Name"
        },
        "description": {
          "description": "Plain-language work description including useful inputs, actions, systems, constraints, and desired outcome. Do not name a catalog agent.",
          "maxLength": 2000,
          "minLength": 1,
          "pattern": "\\S",
          "title": "Description",
          "type": "string"
        },
        "labor_baseline": {
          "anyOf": [
            {
              "$ref": "#/$defs/DiscoveryLaborBaseline"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional customer labor inputs for deterministic human labor-value math. These values do not affect LLM scores and are not XY pricing."
        },
        "external_pricing_inputs": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/ExternalPricingInput"
              },
              "maxItems": 20,
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "deprecated": true,
          "description": "Legacy explicit vendor-rate quantities, retained for existing clients. Prefer the shared expected_items_per_month or expected_items with expected_item_unit. Cannot be combined with the shared unit/conversions.",
          "title": "External Pricing Inputs"
        },
        "expected_item_unit": {
          "anyOf": [
            {
              "maxLength": 80,
              "minLength": 1,
              "pattern": "^[a-z][a-z0-9_]*$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Meaning of one expected item, e.g. page, document, ticket or claim. Used with the same item count and period for XY and vendor matches. Required for automatic vendor estimates; does not establish XY history compatibility.",
          "title": "Expected Item Unit"
        },
        "workload_units_per_item": {
          "anyOf": [
            {
              "maxProperties": 10,
              "patternProperties": {
                "^[a-z][a-z0-9_]*$": {
                  "exclusiveMinimum": 0,
                  "maximum": 1000000,
                  "type": "number"
                }
              },
              "propertyNames": {
                "maxLength": 80,
                "minLength": 1
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional workload conversion assumptions shared across providers: for document items, {page: 5} means five processed pages per document. Keys are singular units, not vendor rate IDs. Requires an item count and expected_item_unit; unknown conversion ratios are never inferred.",
          "title": "Workload Units Per Item"
        },
        "expected_runs_per_month": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 1000000,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional expected monthly workflow executions for an indicative XY operating-cost projection. A customer work item is not necessarily one workflow run.",
          "title": "Expected Runs Per Month"
        },
        "expected_items_per_month": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 100000000,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional expected monthly primary work items (such as claims or payments), not workflow runs. Item-normalized estimates are returned only when XY has comparable governed item-volume and cost history for the matched use case.",
          "title": "Expected Items Per Month"
        },
        "expected_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 100000000,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Total primary work items across the entire project, not per month or workflow executions. Optionally supply project_duration_months for monthly averages. Cannot be combined with expected_items_per_month or expected_runs_per_month.",
          "title": "Expected Items"
        },
        "project_duration_months": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 1200,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional project duration in months, up to 1200; fractional months are allowed. Requires expected_items. Used to express average monthly volume and operating cost, assuming the workload is spread evenly.",
          "title": "Project Duration Months"
        }
      },
      "required": [
        "description"
      ],
      "title": "DiscoveryTask",
      "type": "object"
    },
    "ExternalPricingInput": {
      "additionalProperties": false,
      "description": "An explicit vendor billing dimension; never an inferred XY item count.",
      "properties": {
        "listing_id": {
          "maxLength": 300,
          "pattern": "^(?:aws|microsoft):[A-Za-z0-9][A-Za-z0-9._-]*$",
          "title": "Listing Id",
          "type": "string"
        },
        "rate_id": {
          "description": "Exact rate_id returned in the listing's vendor_pricing.rates.",
          "pattern": "^[0-9a-f]{16}$",
          "title": "Rate Id",
          "type": "string"
        },
        "quantity": {
          "description": "Count of the selected rate's billed units, for the supplied period. Read its unit, description and conditions: pages are not PDFs or workflow invocations. This does not set XY work-item volume.",
          "exclusiveMinimum": 0,
          "maximum": 1000000000,
          "title": "Quantity",
          "type": "number"
        },
        "period": {
          "default": "month",
          "enum": [
            "month",
            "project"
          ],
          "title": "Period",
          "type": "string"
        },
        "project_duration_months": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 1200,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Project Duration Months"
        }
      },
      "required": [
        "listing_id",
        "rate_id",
        "quantity"
      ],
      "title": "ExternalPricingInput",
      "type": "object"
    }
  },
  "properties": {
    "tasks": {
      "items": {
        "$ref": "#/$defs/DiscoveryTask"
      },
      "maxItems": 8,
      "minItems": 1,
      "title": "Tasks",
      "type": "array"
    },
    "max_external_matches": {
      "default": 4,
      "maximum": 10,
      "minimum": 1,
      "title": "Max External Matches",
      "type": "integer"
    }
  },
  "required": [
    "tasks"
  ],
  "title": "catalog_match_tasksArguments",
  "type": "object",
  "additionalProperties": false
}
credentials_createCreate a secure credential reference without echoing secrets. It is created in this key's organization. For a Workflow Request's portal login, send the person workflow_request_get's credential_url instead.
Input schema
{
  "properties": {
    "domain": {
      "title": "Domain",
      "type": "string"
    },
    "site_name": {
      "title": "Site Name",
      "type": "string"
    },
    "username": {
      "title": "Username",
      "type": "string"
    },
    "password": {
      "title": "Password",
      "type": "string"
    },
    "login_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Login Url"
    },
    "totp": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Totp"
    },
    "pin": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pin"
    },
    "sms_phone_type": {
      "default": "voip",
      "enum": [
        "voip",
        "real_sim"
      ],
      "title": "Sms Phone Type",
      "type": "string"
    },
    "notes": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Notes"
    }
  },
  "required": [
    "domain",
    "site_name",
    "username",
    "password"
  ],
  "title": "credentials_createArguments",
  "type": "object",
  "additionalProperties": false
}
credentials_getRead a Password Vault reference without secrets. Other users receive only its site name, domain, type, active state, and ID. STAFF and the creator also receive private metadata. Organization boundaries still apply; listing an entry does not grant access to its secrets. Pass an exact org ID, slug, or name for STAFF reference-only lookup, with internal_credentials:read on the key and the target org grant. The selected credential must belong to that org. Omit organization_id for home-org metadata. This tool never grants credential use or write permission.
Input schema
{
  "properties": {
    "credential_id": {
      "maxLength": 128,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Credential Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "credential_id"
  ],
  "title": "credentials_getArguments",
  "type": "object",
  "additionalProperties": false
}
credentials_listList visible Password Vault references without secrets. Everyone in the organization sees site_name, domain, and credential_type. Private metadata, including username, is visible only to STAFF or the creator. Match on the visible fields, then pass the exact credential_id to Planner. Integration Factory still requires an API-managed reference created through credentials_create. Ask the user when zero or multiple entries match; never guess a credential. To discover a customer org's references, pass its exact ID, slug, or name. Explicit org lookup requires current STAFF membership and internal_credentials:read on the key and the target org grant. It returns only reference IDs, site names, domains, types, and active status. Omitting organization_id keeps the existing home-org metadata lookup. Create and edit human credentials through Password Vault; never request secrets in chat.
Input schema
{
  "properties": {
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "credentials_listArguments",
  "type": "object",
  "additionalProperties": false
}
credentials_revokeRevoke a credential, delete its vault secret, and invalidate sessions.
Input schema
{
  "properties": {
    "credential_id": {
      "maxLength": 128,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Credential Id",
      "type": "string"
    }
  },
  "required": [
    "credential_id"
  ],
  "title": "credentials_revokeArguments",
  "type": "object",
  "additionalProperties": false
}
credentials_rotateReplace a stored secret and revoke sessions using the old version.
Input schema
{
  "properties": {
    "credential_id": {
      "maxLength": 128,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Credential Id",
      "type": "string"
    },
    "password": {
      "title": "Password",
      "type": "string"
    },
    "site_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Site Name"
    },
    "username": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Username"
    },
    "login_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Login Url"
    },
    "totp": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Totp"
    },
    "pin": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pin"
    },
    "sms_phone_type": {
      "anyOf": [
        {
          "enum": [
            "voip",
            "real_sim"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sms Phone Type"
    },
    "notes": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Notes"
    }
  },
  "required": [
    "credential_id",
    "password"
  ],
  "title": "credentials_rotateArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_closeWithdraw a custom request; a closed request no longer changes. Confirm with the user first. The note tells XY why. Emits custom_request.closed. This withdraws the request, not a running build or deployed workflow; it does not cancel execution or billing.
Input schema
{
  "properties": {
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "version": {
      "minimum": 1,
      "title": "Version",
      "type": "integer"
    },
    "note": {
      "anyOf": [
        {
          "maxLength": 2000,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "required": [
    "request_id",
    "version"
  ],
  "title": "custom_agent_request_closeArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_createMake a workflow request: ask XY to build a workflow, and get its form. Use this for a customer's or partner's workflow request; staff use workflow_request_* instead. specification is what the workflow should achieve in plain words; it prefills the form's desired outcome. After catalog_match_tasks, pass each matched task with its optional name and chosen cards as discovery_selections; for a task with no current match, pass its description as specification instead. Fill in the rest with custom_agent_request_update, then publish it with custom_agent_request_publish. Use the returned id as request_id for every custom request tool; form_url opens the same form in the XY app, where individual Workflow Requests app permission is required. This does not change the API/MCP scopes required by these tools.
Input schema
{
  "$defs": {
    "AgentRequestDiscoverySelection": {
      "additionalProperties": false,
      "description": "Original customer task and the Discover cards chosen for that task.",
      "properties": {
        "id": {
          "maxLength": 100,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
          "title": "Id",
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "maxLength": 200,
              "minLength": 1,
              "pattern": "\\S",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Name"
        },
        "description": {
          "maxLength": 2000,
          "minLength": 1,
          "pattern": "\\S",
          "title": "Description",
          "type": "string"
        },
        "selected_agent_ids": {
          "items": {
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "type": "string"
          },
          "maxItems": 4,
          "minItems": 1,
          "title": "Selected Agent Ids",
          "type": "array"
        }
      },
      "required": [
        "id",
        "description",
        "selected_agent_ids"
      ],
      "title": "AgentRequestDiscoverySelection",
      "type": "object"
    },
    "AgentRequestFormAccessMethodAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "website_portal",
                "api",
                "file_transfer",
                "email",
                "other"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormAccessMethodAnswer",
      "type": "object"
    },
    "AgentRequestFormAvailabilityAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "available",
                "being_arranged",
                "third_party_dependency",
                "not_needed"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormAvailabilityAnswer",
      "type": "object"
    },
    "AgentRequestFormBrowserPortal": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        },
        "domain": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Domain"
        },
        "system": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "System"
        },
        "steps": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormPortalStep"
          },
          "maxItems": 200,
          "title": "Steps",
          "type": "array"
        }
      },
      "title": "AgentRequestFormBrowserPortal",
      "type": "object"
    },
    "AgentRequestFormCredentialsAndAccess": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "credentials_needed": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormYesNoAnswer"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Credentials Needed"
        },
        "vault_reference": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormVaultReferenceAnswer"
            },
            {
              "pattern": "^c[a-z0-9]{24}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Vault Reference"
        },
        "outstanding_requirements": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Outstanding Requirements"
        }
      },
      "title": "AgentRequestFormCredentialsAndAccess",
      "type": "object"
    },
    "AgentRequestFormCurrentProcess": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "documentation_status": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormDocumentationStatusAnswer"
            },
            {
              "enum": [
                "complete",
                "partial_informal",
                "mainly_undocumented"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Documentation Status"
        },
        "sop_links": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sop Links"
        }
      },
      "title": "AgentRequestFormCurrentProcess",
      "type": "object"
    },
    "AgentRequestFormDocumentationStatusAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "complete",
                "partial_informal",
                "mainly_undocumented"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormDocumentationStatusAnswer",
      "type": "object"
    },
    "AgentRequestFormExpectedOutput": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "description": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        },
        "examples": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Examples"
        }
      },
      "title": "AgentRequestFormExpectedOutput",
      "type": "object"
    },
    "AgentRequestFormGoalAndScope": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "desired_outcome": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Desired Outcome"
        },
        "why_it_matters": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Why It Matters"
        },
        "in_scope": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "In Scope"
        },
        "out_of_scope": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Out Of Scope"
        },
        "success_criteria": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Success Criteria"
        }
      },
      "title": "AgentRequestFormGoalAndScope",
      "type": "object"
    },
    "AgentRequestFormInput": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        },
        "description": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        },
        "example": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Example"
        }
      },
      "title": "AgentRequestFormInput",
      "type": "object"
    },
    "AgentRequestFormJudgmentTypeAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "rules_based",
                "human_judgment",
                "ai_judgment"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormJudgmentTypeAnswer",
      "type": "object"
    },
    "AgentRequestFormListMark": {
      "additionalProperties": false,
      "description": "A repeating section marked Not applicable, with the reason it has no items.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "default": null,
          "title": "Value",
          "type": "null"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormListMark",
      "type": "object"
    },
    "AgentRequestFormNotApplicableSections": {
      "additionalProperties": false,
      "description": "Repeating sections that can be empty, if marked Not applicable with a reason.",
      "properties": {
        "browser_portals": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormListMark"
            },
            {
              "type": "null"
            }
          ],
          "title": "Browser Portals"
        },
        "inputs": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormListMark"
            },
            {
              "type": "null"
            }
          ],
          "title": "Inputs"
        }
      },
      "title": "AgentRequestFormNotApplicableSections",
      "type": "object"
    },
    "AgentRequestFormPortalStep": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "instruction": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Instruction"
        }
      },
      "title": "AgentRequestFormPortalStep",
      "type": "object"
    },
    "AgentRequestFormRequestContext": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "customer_name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Customer Name"
        },
        "workflow_name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Workflow Name"
        }
      },
      "title": "AgentRequestFormRequestContext",
      "type": "object"
    },
    "AgentRequestFormRulesAndJudgment": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "rules": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rules"
        },
        "judgment_type": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormJudgmentTypeAnswer"
            },
            {
              "enum": [
                "rules_based",
                "human_judgment",
                "ai_judgment"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Judgment Type"
        }
      },
      "title": "AgentRequestFormRulesAndJudgment",
      "type": "object"
    },
    "AgentRequestFormSandboxAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "yes",
                "no",
                "partial"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormSandboxAnswer",
      "type": "object"
    },
    "AgentRequestFormSpec": {
      "additionalProperties": false,
      "description": "The request form: the Spec sections a customer fills in. Send only the sections to change; a list of items replaces the list.",
      "properties": {
        "request_context": {
          "$ref": "#/$defs/AgentRequestFormRequestContext",
          "title": "Request Context"
        },
        "goal_and_scope": {
          "$ref": "#/$defs/AgentRequestFormGoalAndScope",
          "title": "Goal And Scope"
        },
        "systems": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormSystem"
          },
          "maxItems": 50,
          "title": "Systems",
          "type": "array"
        },
        "browser_portals": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormBrowserPortal"
          },
          "maxItems": 50,
          "title": "Browser Portals",
          "type": "array"
        },
        "credentials_and_access": {
          "$ref": "#/$defs/AgentRequestFormCredentialsAndAccess",
          "title": "Credentials And Access"
        },
        "current_process": {
          "$ref": "#/$defs/AgentRequestFormCurrentProcess",
          "title": "Current Process"
        },
        "inputs": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormInput"
          },
          "maxItems": 100,
          "title": "Inputs",
          "type": "array"
        },
        "expected_output": {
          "$ref": "#/$defs/AgentRequestFormExpectedOutput",
          "title": "Expected Output"
        },
        "testing": {
          "$ref": "#/$defs/AgentRequestFormTesting",
          "title": "Testing"
        },
        "rules_and_judgment": {
          "$ref": "#/$defs/AgentRequestFormRulesAndJudgment",
          "title": "Rules And Judgment"
        },
        "variations": {
          "$ref": "#/$defs/AgentRequestFormVariations",
          "title": "Variations"
        },
        "not_applicable": {
          "$ref": "#/$defs/AgentRequestFormNotApplicableSections",
          "title": "Not Applicable"
        }
      },
      "title": "AgentRequestFormSpec",
      "type": "object"
    },
    "AgentRequestFormSystem": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        },
        "use": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Use"
        },
        "access_method": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormAccessMethodAnswer"
            },
            {
              "enum": [
                "website_portal",
                "api",
                "file_transfer",
                "email",
                "other"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Access Method"
        },
        "availability": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormAvailabilityAnswer"
            },
            {
              "enum": [
                "available",
                "being_arranged",
                "third_party_dependency",
                "not_needed"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Availability"
        }
      },
      "title": "AgentRequestFormSystem",
      "type": "object"
    },
    "AgentRequestFormTestDataSourcesAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "items": {
                "enum": [
                  "customer_samples",
                  "live_production",
                  "synthetic",
                  "other"
                ],
                "type": "string"
              },
              "maxItems": 4,
              "minItems": 1,
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormTestDataSourcesAnswer",
      "type": "object"
    },
    "AgentRequestFormTesting": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "sandbox": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormSandboxAnswer"
            },
            {
              "enum": [
                "yes",
                "no",
                "partial"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sandbox or test environment"
        },
        "sandbox_details": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sandbox details"
        },
        "test_data_sources": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTestDataSourcesAnswer"
            },
            {
              "items": {
                "enum": [
                  "customer_samples",
                  "live_production",
                  "synthetic",
                  "other"
                ],
                "type": "string"
              },
              "maxItems": 4,
              "minItems": 1,
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "title": "Test data source"
        },
        "test_data_details": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Test data details"
        },
        "cadence_and_volume": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cadence and volume"
        },
        "test_data_provider": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Provided by"
        }
      },
      "title": "AgentRequestFormTesting",
      "type": "object"
    },
    "AgentRequestFormTextAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormTextAnswer",
      "type": "object"
    },
    "AgentRequestFormVariationTypeAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "one_path",
                "two_or_three",
                "category_based",
                "changing_conditions"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormVariationTypeAnswer",
      "type": "object"
    },
    "AgentRequestFormVariations": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "variation_type": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormVariationTypeAnswer"
            },
            {
              "enum": [
                "one_path",
                "two_or_three",
                "category_based",
                "changing_conditions"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Variation Type"
        },
        "description": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        }
      },
      "title": "AgentRequestFormVariations",
      "type": "object"
    },
    "AgentRequestFormVaultReferenceAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "pattern": "^c[a-z0-9]{24}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormVaultReferenceAnswer",
      "type": "object"
    },
    "AgentRequestFormYesNoAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormYesNoAnswer",
      "type": "object"
    }
  },
  "properties": {
    "name": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Name",
      "type": "string"
    },
    "specification": {
      "anyOf": [
        {
          "maxLength": 20000,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Specification"
    },
    "discovery_selections": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/AgentRequestDiscoverySelection"
          },
          "maxItems": 8,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discovery Selections"
    },
    "systems": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Systems"
    },
    "workflow_spec": {
      "anyOf": [
        {
          "$ref": "#/$defs/AgentRequestFormSpec"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "name"
  ],
  "title": "custom_agent_request_createArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_deploymentsRead the published workflows delivered for an XY request. Keep the same request_id returned by creation or bulk submission. This reads deployment provenance, not Discover matches or build success. Empty data means no delivered workflow has been registered yet. Returns IDs, versions and availability only, never YAML or payloads.
Input schema
{
  "properties": {
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "request_id"
  ],
  "title": "custom_agent_request_deploymentsArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_getRead a custom request: its state, messages, and form. A request made with custom_agent_request_create includes its form's Spec (workflow_spec), what it still needs (open_fields), and form_url. Includes the review, clarification, and delivery fields. Use the returned version to change it or for planner approval. Staff Workflow Requests use workflow_request_* tools.
Input schema
{
  "properties": {
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "request_id"
  ],
  "title": "custom_agent_request_getArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_listList my workflow requests to XY: the requests I asked XY to build. A person sees their own requests, made through this connection or in the XY app; XY staff pass organization_id to list one organization's. Filter by state, such as submitted or needs_information. Show each request's form_url as a link to its form in the XY app. Read one with custom_agent_request_get for its form and XY's messages. Pass next_cursor back as cursor for the next page.
Input schema
{
  "properties": {
    "state": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "State"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 2000,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "custom_agent_request_listArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_messageAnswer an XY clarification or add context to a submitted request.
Input schema
{
  "properties": {
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "message": {
      "title": "Message",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "request_id",
    "message"
  ],
  "title": "custom_agent_request_messageArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_publishShare a custom request's saved form with XY as its next version. Confirm with the user first. The first publish, and the first after XY asks for more information, moves the request to submitted. XY may reply through the request's messages.
Input schema
{
  "properties": {
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "version": {
      "minimum": 1,
      "title": "Version",
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "request_id",
    "version",
    "idempotency_key"
  ],
  "title": "custom_agent_request_publishArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_submit_bulkSubmit approved tasks to XY as separate partially completed requests. Use only after the customer approves sending these tasks to XY. Each task needs name and description; its optional id is the caller's task ID, not an agent ID. selected_agent_ids may contain chosen XY Discover cards; never third-party listing IDs. For a third-party selection, use selected_external_listing_id instead, with the ID from external_matches or external_listings. Never combine it with selected_agent_ids. XY saves the catalog metadata and returns state pending plus external_selection; this is a consultation hold, not an XY build, purchase, licensing or third-party deployment. The form link opens the read-only tracked request. This shares each request with XY immediately, unlike custom_agent_request_create, which makes a draft. No detailed form, build, deployment, or execution is required or started here. XY gathers missing requirements before building XY/custom tasks; third-party selections remain pending until separately scoped follow-up. Returns task_id, request_id, form_url and state for every task. Retain request_id for tracking and messaging. Retry the exact same batch with the same idempotency_key; caller task IDs also deduplicate identical submissions across keys. Reusing an ID for changed content is refused. Accepts 1–50 tasks atomically; discovery's eight-task limit is separate. Supports personal and managed organization service credentials.
Input schema
{
  "$defs": {
    "AgentRequestBulkTask": {
      "additionalProperties": false,
      "properties": {
        "name": {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "\\S",
          "title": "Name",
          "type": "string"
        },
        "description": {
          "maxLength": 2000,
          "minLength": 1,
          "pattern": "\\S",
          "title": "Description",
          "type": "string"
        },
        "id": {
          "description": "Optional caller task ID, unique within the organization. Reuse it only for the same task submission.",
          "maxLength": 100,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
          "title": "Id",
          "type": "string"
        },
        "selected_agent_ids": {
          "description": "Optional chosen XY Discover cards, not executable or third-party listing IDs.",
          "items": {
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "type": "string"
          },
          "maxItems": 4,
          "title": "Selected Agent Ids",
          "type": "array"
        },
        "selected_external_listing_id": {
          "description": "An ID returned in external_matches or external_listings. Records a pending\nthird-party consultation request, never an XY build. Cannot be combined with\nselected_agent_ids. XY saves the original provider metadata from its catalog.",
          "maxLength": 300,
          "pattern": "^(aws|microsoft):[A-Za-z0-9][A-Za-z0-9._-]*$",
          "title": "Selected External Listing Id",
          "type": "string"
        }
      },
      "required": [
        "name",
        "description"
      ],
      "title": "AgentRequestBulkTask",
      "type": "object"
    }
  },
  "properties": {
    "tasks": {
      "items": {
        "$ref": "#/$defs/AgentRequestBulkTask"
      },
      "maxItems": 50,
      "minItems": 1,
      "title": "Tasks",
      "type": "array"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "tasks",
    "idempotency_key"
  ],
  "title": "custom_agent_request_submit_bulkArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_updateSave changes to a custom request's form without sharing them with XY. workflow_spec holds only the Spec sections to change, in the shape custom_agent_request_get returns. A section's fields change one by one; a list of items (systems, browser_portals, inputs, and a portal's steps) replaces the list, and an item without an id is new. Give an answer as its value, null to clear it, or {"state": "not_applicable", "reason": "..."} when it does not apply. open_fields in the result lists what XY still needs. Credentials are only ever a Password Vault credential ID in credentials_and_access.vault_reference, never a password or key. testing follows Expected output. testing.sandbox is yes|no|partial; testing.test_data_sources is a non-empty list of unique choices from customer_samples|live_production|synthetic|other. The remaining fields sandbox_details, test_data_details, cadence_and_volume, and test_data_provider take text answers. Testing does not yet affect submission readiness. Customers cannot choose Not sure. Pass the request's current version; each change returns the next one. Retry an unchanged call with the same idempotency_key and version.
Input schema
{
  "$defs": {
    "AgentRequestFormAccessMethodAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "website_portal",
                "api",
                "file_transfer",
                "email",
                "other"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormAccessMethodAnswer",
      "type": "object"
    },
    "AgentRequestFormAvailabilityAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "available",
                "being_arranged",
                "third_party_dependency",
                "not_needed"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormAvailabilityAnswer",
      "type": "object"
    },
    "AgentRequestFormBrowserPortal": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        },
        "domain": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Domain"
        },
        "system": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "System"
        },
        "steps": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormPortalStep"
          },
          "maxItems": 200,
          "title": "Steps",
          "type": "array"
        }
      },
      "title": "AgentRequestFormBrowserPortal",
      "type": "object"
    },
    "AgentRequestFormCredentialsAndAccess": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "credentials_needed": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormYesNoAnswer"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Credentials Needed"
        },
        "vault_reference": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormVaultReferenceAnswer"
            },
            {
              "pattern": "^c[a-z0-9]{24}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Vault Reference"
        },
        "outstanding_requirements": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Outstanding Requirements"
        }
      },
      "title": "AgentRequestFormCredentialsAndAccess",
      "type": "object"
    },
    "AgentRequestFormCurrentProcess": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "documentation_status": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormDocumentationStatusAnswer"
            },
            {
              "enum": [
                "complete",
                "partial_informal",
                "mainly_undocumented"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Documentation Status"
        },
        "sop_links": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sop Links"
        }
      },
      "title": "AgentRequestFormCurrentProcess",
      "type": "object"
    },
    "AgentRequestFormDocumentationStatusAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "complete",
                "partial_informal",
                "mainly_undocumented"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormDocumentationStatusAnswer",
      "type": "object"
    },
    "AgentRequestFormExpectedOutput": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "description": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        },
        "examples": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Examples"
        }
      },
      "title": "AgentRequestFormExpectedOutput",
      "type": "object"
    },
    "AgentRequestFormGoalAndScope": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "desired_outcome": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Desired Outcome"
        },
        "why_it_matters": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Why It Matters"
        },
        "in_scope": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "In Scope"
        },
        "out_of_scope": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Out Of Scope"
        },
        "success_criteria": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Success Criteria"
        }
      },
      "title": "AgentRequestFormGoalAndScope",
      "type": "object"
    },
    "AgentRequestFormInput": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        },
        "description": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        },
        "example": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Example"
        }
      },
      "title": "AgentRequestFormInput",
      "type": "object"
    },
    "AgentRequestFormJudgmentTypeAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "rules_based",
                "human_judgment",
                "ai_judgment"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormJudgmentTypeAnswer",
      "type": "object"
    },
    "AgentRequestFormListMark": {
      "additionalProperties": false,
      "description": "A repeating section marked Not applicable, with the reason it has no items.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "default": null,
          "title": "Value",
          "type": "null"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormListMark",
      "type": "object"
    },
    "AgentRequestFormNotApplicableSections": {
      "additionalProperties": false,
      "description": "Repeating sections that can be empty, if marked Not applicable with a reason.",
      "properties": {
        "browser_portals": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormListMark"
            },
            {
              "type": "null"
            }
          ],
          "title": "Browser Portals"
        },
        "inputs": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormListMark"
            },
            {
              "type": "null"
            }
          ],
          "title": "Inputs"
        }
      },
      "title": "AgentRequestFormNotApplicableSections",
      "type": "object"
    },
    "AgentRequestFormPortalStep": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "instruction": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Instruction"
        }
      },
      "title": "AgentRequestFormPortalStep",
      "type": "object"
    },
    "AgentRequestFormRequestContext": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "customer_name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Customer Name"
        },
        "workflow_name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Workflow Name"
        }
      },
      "title": "AgentRequestFormRequestContext",
      "type": "object"
    },
    "AgentRequestFormRulesAndJudgment": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "rules": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rules"
        },
        "judgment_type": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormJudgmentTypeAnswer"
            },
            {
              "enum": [
                "rules_based",
                "human_judgment",
                "ai_judgment"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Judgment Type"
        }
      },
      "title": "AgentRequestFormRulesAndJudgment",
      "type": "object"
    },
    "AgentRequestFormSandboxAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "yes",
                "no",
                "partial"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormSandboxAnswer",
      "type": "object"
    },
    "AgentRequestFormSpec": {
      "additionalProperties": false,
      "description": "The request form: the Spec sections a customer fills in. Send only the sections to change; a list of items replaces the list.",
      "properties": {
        "request_context": {
          "$ref": "#/$defs/AgentRequestFormRequestContext",
          "title": "Request Context"
        },
        "goal_and_scope": {
          "$ref": "#/$defs/AgentRequestFormGoalAndScope",
          "title": "Goal And Scope"
        },
        "systems": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormSystem"
          },
          "maxItems": 50,
          "title": "Systems",
          "type": "array"
        },
        "browser_portals": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormBrowserPortal"
          },
          "maxItems": 50,
          "title": "Browser Portals",
          "type": "array"
        },
        "credentials_and_access": {
          "$ref": "#/$defs/AgentRequestFormCredentialsAndAccess",
          "title": "Credentials And Access"
        },
        "current_process": {
          "$ref": "#/$defs/AgentRequestFormCurrentProcess",
          "title": "Current Process"
        },
        "inputs": {
          "items": {
            "$ref": "#/$defs/AgentRequestFormInput"
          },
          "maxItems": 100,
          "title": "Inputs",
          "type": "array"
        },
        "expected_output": {
          "$ref": "#/$defs/AgentRequestFormExpectedOutput",
          "title": "Expected Output"
        },
        "testing": {
          "$ref": "#/$defs/AgentRequestFormTesting",
          "title": "Testing"
        },
        "rules_and_judgment": {
          "$ref": "#/$defs/AgentRequestFormRulesAndJudgment",
          "title": "Rules And Judgment"
        },
        "variations": {
          "$ref": "#/$defs/AgentRequestFormVariations",
          "title": "Variations"
        },
        "not_applicable": {
          "$ref": "#/$defs/AgentRequestFormNotApplicableSections",
          "title": "Not Applicable"
        }
      },
      "title": "AgentRequestFormSpec",
      "type": "object"
    },
    "AgentRequestFormSystem": {
      "additionalProperties": false,
      "description": "One item; send it without an id to add it.",
      "properties": {
        "id": {
          "title": "Id",
          "type": "string"
        },
        "name": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name"
        },
        "use": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Use"
        },
        "access_method": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormAccessMethodAnswer"
            },
            {
              "enum": [
                "website_portal",
                "api",
                "file_transfer",
                "email",
                "other"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Access Method"
        },
        "availability": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormAvailabilityAnswer"
            },
            {
              "enum": [
                "available",
                "being_arranged",
                "third_party_dependency",
                "not_needed"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Availability"
        }
      },
      "title": "AgentRequestFormSystem",
      "type": "object"
    },
    "AgentRequestFormTestDataSourcesAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "items": {
                "enum": [
                  "customer_samples",
                  "live_production",
                  "synthetic",
                  "other"
                ],
                "type": "string"
              },
              "maxItems": 4,
              "minItems": 1,
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormTestDataSourcesAnswer",
      "type": "object"
    },
    "AgentRequestFormTesting": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "sandbox": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormSandboxAnswer"
            },
            {
              "enum": [
                "yes",
                "no",
                "partial"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sandbox or test environment"
        },
        "sandbox_details": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sandbox details"
        },
        "test_data_sources": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTestDataSourcesAnswer"
            },
            {
              "items": {
                "enum": [
                  "customer_samples",
                  "live_production",
                  "synthetic",
                  "other"
                ],
                "type": "string"
              },
              "maxItems": 4,
              "minItems": 1,
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "title": "Test data source"
        },
        "test_data_details": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Test data details"
        },
        "cadence_and_volume": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cadence and volume"
        },
        "test_data_provider": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Provided by"
        }
      },
      "title": "AgentRequestFormTesting",
      "type": "object"
    },
    "AgentRequestFormTextAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormTextAnswer",
      "type": "object"
    },
    "AgentRequestFormVariationTypeAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "enum": [
                "one_path",
                "two_or_three",
                "category_based",
                "changing_conditions"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormVariationTypeAnswer",
      "type": "object"
    },
    "AgentRequestFormVariations": {
      "additionalProperties": false,
      "description": "One section of the form.",
      "properties": {
        "variation_type": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormVariationTypeAnswer"
            },
            {
              "enum": [
                "one_path",
                "two_or_three",
                "category_based",
                "changing_conditions"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Variation Type"
        },
        "description": {
          "anyOf": [
            {
              "$ref": "#/$defs/AgentRequestFormTextAnswer"
            },
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description"
        }
      },
      "title": "AgentRequestFormVariations",
      "type": "object"
    },
    "AgentRequestFormVaultReferenceAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "pattern": "^c[a-z0-9]{24}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormVaultReferenceAnswer",
      "type": "object"
    },
    "AgentRequestFormYesNoAnswer": {
      "additionalProperties": false,
      "description": "One answer: its state, its value when answered, and a reason when Not applicable.",
      "properties": {
        "state": {
          "default": "unanswered",
          "enum": [
            "unanswered",
            "answered",
            "not_applicable"
          ],
          "title": "State",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        },
        "reason": {
          "anyOf": [
            {
              "maxLength": 10000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Reason"
        }
      },
      "title": "AgentRequestFormYesNoAnswer",
      "type": "object"
    }
  },
  "properties": {
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "version": {
      "minimum": 1,
      "title": "Version",
      "type": "integer"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    },
    "workflow_spec": {
      "$ref": "#/$defs/AgentRequestFormSpec"
    }
  },
  "required": [
    "request_id",
    "version",
    "idempotency_key",
    "workflow_spec"
  ],
  "title": "custom_agent_request_updateArguments",
  "type": "object",
  "additionalProperties": false
}
custom_agent_request_usageRead runs, tokens and observed operating cost for a delivered XY request. ISO-8601 timestamps require timezones: from_time is inclusive and to_time exclusive. Defaults to 30 days, maximum 400 days. Test runs and usage before deployment are excluded. Run counts use run creation time; token counts use call recording time. These are observed totals, not billing or guaranteed complete metering. operating_cost uses this request's own workflows, not a Discovery match: recorded model charges plus allocated runtime costs on completed UTC days after daily collection. Partial is an observed subtotal; unavailable is null, not zero. Averages require complete coverage and, for items, compatible primary-item counts. Cost reporting requires separate organization approval (useOperatingCostReports); otherwise operating_cost is null while runs and tokens remain available. Reported XY cost includes estimated logging costs allocated to the workflow, not measured logging charges. Other shared services, support and margin are excluded. No raw bills, provider details, customer records, prompts or workflow code return. Subscribe to custom_request.operating_cost_updated for corrected rolling 30-day cost snapshots; custom_request.usage_updated includes daily costs.
Input schema
{
  "properties": {
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "from_time": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From Time"
    },
    "to_time": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To Time"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "request_id"
  ],
  "title": "custom_agent_request_usageArguments",
  "type": "object",
  "additionalProperties": false
}
dashboard_agent_queryAsk a read-only analytics question in ordinary business language. A long analysis answers with status "running" and a conversation_id instead of timing out. Then call this tool again with that conversation_id and NO prompt (and the same organization_id) to collect the answer; repeat while it still says "running". A finished answer has status "completed". Personal keys and OAuth must scope the question to one workflow. A workflow_name that resolves to exactly one workflow you can open selects it and the call continues. With no workflow_definition_id and no workflow_name that resolves to exactly one workflow, the call fails with a 400 that lists workflows you can query as "<id> (<name>)" (up to 20, or the granted matches when the name is ambiguous); retry with one of those ids as workflow_definition_id. A WORKFLOW_CONTROL_NOT_FOUND names what could not be reached (for example the workflow definition) without saying whether it is missing or hidden. XY staff may query another organization where they are STAFF by passing organization_id; it needs internal_dashboards:read there.
Input schema
{
  "properties": {
    "prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Prompt"
    },
    "workflow_definition_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workflow Definition Id"
    },
    "workflow_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workflow Name"
    },
    "conversation_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Conversation Id"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "title": "dashboard_agent_queryArguments",
  "type": "object",
  "additionalProperties": false
}
dashboard_proposal_cancelRequest cancellation without approving or deleting any created version.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "dashboard_proposal_cancelArguments",
  "type": "object",
  "additionalProperties": false
}
dashboard_proposal_getRead durable proposal status and its exact human-review version.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "dashboard_proposal_getArguments",
  "type": "object",
  "additionalProperties": false
}
dashboard_proposal_resolve_approvalThe admitted human resolves a pending operation; publication is separate.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "operation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Operation Id",
      "type": "string"
    },
    "request_hash": {
      "title": "Request Hash",
      "type": "string"
    },
    "version": {
      "title": "Version",
      "type": "integer"
    },
    "approved": {
      "title": "Approved",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "run_id",
    "operation_id",
    "request_hash",
    "version",
    "approved"
  ],
  "title": "dashboard_proposal_resolve_approvalArguments",
  "type": "object",
  "additionalProperties": false
}
dashboard_proposal_startDescribe a new or revised dashboard in ordinary business language. State the questions people need answered, useful measures or comparisons, and a time range when relevant. Do not ask the user for query references, analytics schemas, entity fields, or a dashboard specification; the agent infers them from the selected workflow. Omit base_dashboard_version_id to create a dashboard. Supply the exact current live version to propose an edit. Generation stops with a preview for human web review; this tool cannot approve or publish the result. Access: an explicit configure grant on the workflow, or (personal keys and OAuth) being able to open a dashboard in the organization. XY staff may pass organization_id for another organization where they are STAFF; it needs internal_dashboards:write there, and the same organization_id on the get, wait and cancel calls. A dashboard that has never been published has no live version; revise that preview with the staff analytics apply path (PreviewDashboardVersion, edit true, base version = the current preview) rather than this proposal tool.
Input schema
{
  "properties": {
    "prompt": {
      "title": "Prompt",
      "type": "string"
    },
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    },
    "base_dashboard_version_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Base Dashboard Version Id"
    },
    "conversation_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Conversation Id"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "prompt",
    "workflow_definition_id",
    "idempotency_key"
  ],
  "title": "dashboard_proposal_startArguments",
  "type": "object",
  "additionalProperties": false
}
dashboard_proposal_wait_for_eventsReplay normalized safe progress and wait briefly for the next event.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "after": {
      "default": 0,
      "minimum": 0,
      "title": "After",
      "type": "integer"
    },
    "timeout_seconds": {
      "default": 20,
      "exclusiveMinimum": 0,
      "title": "Timeout Seconds",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "dashboard_proposal_wait_for_eventsArguments",
  "type": "object",
  "additionalProperties": false
}
dashboard_viewShow any dashboard you can open in the XY analytics app, with all its tiles. Omit both dates for the shared inclusive 30-day UTC window ending today (or that zone's today when timezone is set). Tiles that do not accept dates retain their own window and are marked. XY staff may pass organization_id for another organization where they are STAFF. A filter the dashboard marks required (for example a workflow) that has no default, or whose default is accepted by none of the tiles it applies to, is not applied here: its tiles then cover every workflow you can see (the whole organization for STAFF and admins), and the result carries a warning and unapplied_required_filters. Never report those numbers as the dashboard's answer; say it needs that selection.
Input schema
{
  "properties": {
    "dashboard": {
      "description": "Dashboard id, slug, or an app.xy.ai/analytics/<id> URL.",
      "maxLength": 500,
      "minLength": 1,
      "title": "Dashboard",
      "type": "string"
    },
    "from_date": {
      "anyOf": [
        {
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From Date"
    },
    "to_date": {
      "anyOf": [
        {
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To Date"
    },
    "timezone": {
      "anyOf": [
        {
          "maxLength": 64,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional IANA zone (e.g. America/New_York) for the window and day buckets; default UTC.",
      "title": "Timezone"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "dashboard"
  ],
  "title": "dashboard_viewArguments",
  "type": "object",
  "additionalProperties": false
}
dashboards_listList every live dashboard you can open in the XY analytics app. Same access as the app. XY staff may pass organization_id for another organization where they are STAFF; it needs internal_dashboards:read there. Open one with dashboard_view. At most 200 come back; pagination.has_more is true (total null) past that. An empty list carries a hint naming the organization that was read.
Input schema
{
  "properties": {
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "title": "dashboards_listArguments",
  "type": "object",
  "additionalProperties": false
}
execution_get_phasesRead safe phases for a catalog-agent execution. STAFF may pass organization_id with internal_schedules:read in that org; executions:read is also required.
Input schema
{
  "properties": {
    "execution_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Execution Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "execution_id"
  ],
  "title": "execution_get_phasesArguments",
  "type": "object",
  "additionalProperties": false
}
installation_getRead provisioning, connection, source, and readiness state.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id"
  ],
  "title": "installation_getArguments",
  "type": "object",
  "additionalProperties": false
}
installation_list_authorizationsList authorization actions and their current states.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id"
  ],
  "title": "installation_list_authorizationsArguments",
  "type": "object",
  "additionalProperties": false
}
installation_start_authorizationCreate a short-lived hosted authorization link for a required connection.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "connection": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Connection"
    }
  },
  "required": [
    "installation_id"
  ],
  "title": "installation_start_authorizationArguments",
  "type": "object",
  "additionalProperties": false
}
integration_connection_authorizeStart a provider sign-in (OAuth) for an integration. Returns authorization_url: a short-lived hosted page the user opens in a browser to sign in. Show the complete URL. The connection appears in integration_connections_list once the sign-in completes; no token passes through this tool.
Input schema
{
  "properties": {
    "type_key": {
      "maxLength": 80,
      "minLength": 1,
      "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
      "title": "Type Key",
      "type": "string"
    }
  },
  "required": [
    "type_key"
  ],
  "title": "integration_connection_authorizeArguments",
  "type": "object",
  "additionalProperties": false
}
integration_connection_createConnect an integration for the organization with a Password Vault credential (credentials_create returns its credential_id; integrations with auth_type NONE need none). The credential's domain must match the integration's API domain. The secret itself never passes through this tool.
Input schema
{
  "properties": {
    "type_key": {
      "maxLength": 80,
      "minLength": 1,
      "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
      "title": "Type Key",
      "type": "string"
    },
    "credential_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credential Id"
    },
    "label": {
      "anyOf": [
        {
          "maxLength": 120,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Label"
    }
  },
  "required": [
    "type_key"
  ],
  "title": "integration_connection_createArguments",
  "type": "object",
  "additionalProperties": false
}
integration_connections_listList the organization's active integration connections. No secrets are returned.
Input schema
{
  "properties": {},
  "title": "integration_connections_listArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_capability_test_getRead one durable generated-capability test and its redacted result.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 128,
      "minLength": 8,
      "pattern": "^ifrun_[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "test_id": {
      "title": "Test Id",
      "type": "string"
    }
  },
  "required": [
    "run_id",
    "test_id"
  ],
  "title": "integration_factory_capability_test_getArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_createStart discovery for a NEW organization-only integration. This is the first step when XY has no connector for an API yet; use integration_factory_extend only to add capabilities to an integration this organization already promoted. Provide exactly one documentation source: a public HTTPS documentation_url, pasted documentation, or an upload_id from integration_factory_upload_prepare and integration_factory_upload_complete. key is a lowercase kebab-case identifier. api_key_header is only valid for API_KEY authentication and carries no secret; store the key with credentials_create. Returns a run_id and state_version; follow the run with integration_factory_run_get until it is awaiting_generation. Repeating the call with the same arguments (or the same idempotency_key) within 24 hours returns the same run; pass a new idempotency_key to start a deliberate fresh run with identical arguments. Factory stages reserve model capacity after the durable run is queued. If the run reports MODEL_CAPACITY_EXCEEDED, do not retry it automatically; ask an XY staff member to increase the organization's model-capacity limit before submitting more work.
Input schema
{
  "properties": {
    "api_name": {
      "maxLength": 120,
      "minLength": 1,
      "title": "Api Name",
      "type": "string"
    },
    "key": {
      "maxLength": 80,
      "minLength": 1,
      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
      "title": "Key",
      "type": "string"
    },
    "auth_type": {
      "enum": [
        "NONE",
        "API_KEY",
        "BASIC_AUTH",
        "BEARER_TOKEN",
        "CLIENT_CREDENTIALS"
      ],
      "title": "Auth Type",
      "type": "string"
    },
    "documentation_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documentation Url"
    },
    "documentation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documentation"
    },
    "upload_id": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 8,
          "pattern": "^ifupl_[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Upload Id"
    },
    "api_key_header": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Api Key Header"
    },
    "category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Category"
    },
    "base_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Base Url"
    },
    "base_path": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Base Path"
    },
    "custom_instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Custom Instructions"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "api_name",
    "key",
    "auth_type"
  ],
  "title": "integration_factory_createArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_extendDiscover capabilities to add to an org-owned factory integration. Factory stages reserve model capacity after the durable run is queued. If the run reports MODEL_CAPACITY_EXCEEDED, do not retry it automatically; ask an XY staff member to increase the organization's model-capacity limit before submitting more work.
Input schema
{
  "properties": {
    "type_key": {
      "maxLength": 80,
      "minLength": 1,
      "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
      "title": "Type Key",
      "type": "string"
    },
    "documentation_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documentation Url"
    },
    "documentation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documentation"
    },
    "upload_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Upload Id"
    },
    "custom_instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Custom Instructions"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "type_key"
  ],
  "title": "integration_factory_extendArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_generateGenerate selected discovered endpoints into a new integration draft.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 128,
      "minLength": 8,
      "pattern": "^ifrun_[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "endpoints": {
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "minItems": 1,
      "title": "Endpoints",
      "type": "array"
    },
    "state_version": {
      "exclusiveMinimum": 0,
      "title": "State Version",
      "type": "integer"
    },
    "base_path": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Base Path"
    },
    "auth_type": {
      "anyOf": [
        {
          "enum": [
            "NONE",
            "API_KEY",
            "BASIC_AUTH",
            "BEARER_TOKEN",
            "CLIENT_CREDENTIALS"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Auth Type"
    }
  },
  "required": [
    "run_id",
    "endpoints",
    "state_version"
  ],
  "title": "integration_factory_generateArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_promoteMake a validated, explicitly tested draft live only for this organization.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 128,
      "minLength": 8,
      "pattern": "^ifrun_[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "state_version": {
      "exclusiveMinimum": 0,
      "title": "State Version",
      "type": "integer"
    }
  },
  "required": [
    "run_id",
    "state_version"
  ],
  "title": "integration_factory_promoteArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_run_getRead discovery, generation, validation, or promotion state for a run.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 128,
      "minLength": 8,
      "pattern": "^ifrun_[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ],
  "title": "integration_factory_run_getArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_test_capabilityDurably test one generated capability before organization promotion. Set confirm_side_effects=true only after accepting that the upstream API call may create, update, trigger, or delete real external data.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 128,
      "minLength": 8,
      "pattern": "^ifrun_[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "capability_key": {
      "title": "Capability Key",
      "type": "string"
    },
    "state_version": {
      "exclusiveMinimum": 0,
      "title": "State Version",
      "type": "integer"
    },
    "params": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Params"
    },
    "credential_id": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credential Id"
    },
    "confirm_side_effects": {
      "default": false,
      "title": "Confirm Side Effects",
      "type": "boolean"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "run_id",
    "capability_key",
    "state_version"
  ],
  "title": "integration_factory_test_capabilityArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_upload_completeVerify an uploaded documentation file so discovery can use it.
Input schema
{
  "properties": {
    "upload_id": {
      "maxLength": 128,
      "minLength": 8,
      "pattern": "^ifupl_[A-Za-z0-9_-]+$",
      "title": "Upload Id",
      "type": "string"
    }
  },
  "required": [
    "upload_id"
  ],
  "title": "integration_factory_upload_completeArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_upload_prepareReserve a private API-documentation upload for the Integration Factory. Never send file bytes through this tool. PUT the file to the returned upload.url with every returned header, then call integration_factory_upload_complete, and pass the upload id as upload_id to integration_factory_create or integration_factory_extend. The reservation expires after about 20 minutes and is limited to max_bytes. Supported types are PDF, JSON, YAML, DOCX, Markdown and plain text, and the file extension must match content_type.
Input schema
{
  "properties": {
    "file_name": {
      "maxLength": 200,
      "minLength": 1,
      "title": "File Name",
      "type": "string"
    },
    "content_type": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Content Type",
      "type": "string"
    }
  },
  "required": [
    "file_name",
    "content_type"
  ],
  "title": "integration_factory_upload_prepareArguments",
  "type": "object",
  "additionalProperties": false
}
integration_factory_validateValidate a generated draft with an org-owned encrypted credential.
Input schema
{
  "properties": {
    "run_id": {
      "maxLength": 128,
      "minLength": 8,
      "pattern": "^ifrun_[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "state_version": {
      "exclusiveMinimum": 0,
      "title": "State Version",
      "type": "integer"
    },
    "credential_id": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credential Id"
    }
  },
  "required": [
    "run_id",
    "state_version"
  ],
  "title": "integration_factory_validateArguments",
  "type": "object",
  "additionalProperties": false
}
integration_getRead one live integration and its current executable capabilities.
Input schema
{
  "properties": {
    "type_key": {
      "maxLength": 80,
      "minLength": 1,
      "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
      "title": "Type Key",
      "type": "string"
    }
  },
  "required": [
    "type_key"
  ],
  "title": "integration_getArguments",
  "type": "object",
  "additionalProperties": false
}
integrations_listList the integrations this organization can connect: key, name, category, auth_type and capabilities. Pair with integration_connections_list to see which are already connected. The full catalog is large: to check for one system, pass query (for example "google drive" or "slack"). An integration matches when every word appears in its key, name, category or description; when none does, those matching any word are returned. Matches are compact (capability names, not their definitions; integration_get has those), at most 20.
Input schema
{
  "properties": {
    "query": {
      "anyOf": [
        {
          "maxLength": 120,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    }
  },
  "title": "integrations_listArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_add_urlAttach and index a public website in a Knowledge Base installation.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "url": {
      "title": "Url",
      "type": "string"
    },
    "crawl_limit": {
      "default": 50,
      "maximum": 500,
      "minimum": 1,
      "title": "Crawl Limit",
      "type": "integer"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "installation_id",
    "url"
  ],
  "title": "knowledge_source_add_urlArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_batch_cancelCancel queued creation work for a Knowledge Base source batch.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "batch_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Batch Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id",
    "batch_id"
  ],
  "title": "knowledge_source_batch_cancelArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_batch_completeQueue completion checks for uploaded file items in a source batch.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "batch_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Batch Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id",
    "batch_id"
  ],
  "title": "knowledge_source_batch_completeArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_batch_createQueue bulk creation of Knowledge Base file and URL sources.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "sources": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Sources",
      "type": "array"
    },
    "max_concurrency": {
      "default": 5,
      "maximum": 10,
      "minimum": 1,
      "title": "Max Concurrency",
      "type": "integer"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "installation_id",
    "sources"
  ],
  "title": "knowledge_source_batch_createArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_batch_getRead item-level state for a Knowledge Base source batch.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "batch_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Batch Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id",
    "batch_id"
  ],
  "title": "knowledge_source_batch_getArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_batch_upload_actionsCreate fresh signed upload actions for pending file items in a batch.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "batch_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Batch Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id",
    "batch_id"
  ],
  "title": "knowledge_source_batch_upload_actionsArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_complete_uploadConfirm a signed file upload and start ingestion and indexing.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "source_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Source Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id",
    "source_id"
  ],
  "title": "knowledge_source_complete_uploadArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_create_file_uploadCreate a signed upload target for a Knowledge Base file source.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "file_name": {
      "title": "File Name",
      "type": "string"
    },
    "content_type": {
      "title": "Content Type",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "installation_id",
    "file_name",
    "content_type"
  ],
  "title": "knowledge_source_create_file_uploadArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_deleteDelete a Knowledge Base source and its indexed content.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "source_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Source Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id",
    "source_id"
  ],
  "title": "knowledge_source_deleteArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_source_getRead upload or indexing state for one Knowledge Base source.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    },
    "source_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Source Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id",
    "source_id"
  ],
  "title": "knowledge_source_getArguments",
  "type": "object",
  "additionalProperties": false
}
knowledge_sources_listList every source and indexing state for a Knowledge Base installation.
Input schema
{
  "properties": {
    "installation_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Installation Id",
      "type": "string"
    }
  },
  "required": [
    "installation_id"
  ],
  "title": "knowledge_sources_listArguments",
  "type": "object",
  "additionalProperties": false
}
operations_connection_getRead the linked credential's environment, actor, home organization and granted scopes; no secrets. Verify home_organization_name is the organization the user means before any call that omits organization_id. server gives the deployed build {version, git_sha}; plugin gives the current XY plugin release {version, released}: when the installed skills carry an older version, tell the user to reinstall the plugin.
Input schema
{
  "properties": {},
  "title": "operations_connection_getArguments",
  "type": "object",
  "additionalProperties": false
}
operations_executions_listList permitted catalog-agent run IDs and statuses, excluding payloads and partner references.
Input schema
{
  "properties": {
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "operations_executions_listArguments",
  "type": "object",
  "additionalProperties": false
}
organization_log_summarySummarize this organization's own log records over a time range. Returns counts by severity, the most frequent exception types and span names, a time histogram, and a bounded sample — not every line. Raw log lines are deliberately not exposed here: a full page is thousands of records, which is far more than is useful to read into a conversation. Use the REST endpoint when the individual records are genuinely needed. `start` and `end` are absolute UTC timestamps; omitting them reads the last ten minutes. `min_level` is one of info, warn, error. Without `run_id` this needs logs:read. With `run_id` the run's workflow decides: executions:read and permission to view that workflow. STAFF may pass organization_id with run_id only, with internal_schedules:read in that org.
Input schema
{
  "properties": {
    "start": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Start"
    },
    "end": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "End"
    },
    "min_level": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Min Level"
    },
    "q": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Q"
    },
    "run_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Run Id"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "organization_log_summaryArguments",
  "type": "object",
  "additionalProperties": false
}
organization_logs_listRead this organization's own log records, newest first; the same page as GET /logs. For one run pass run_id with start/end set to its started_at and finished_at (from workflow_runs_list). start and end are absolute UTC timestamps; omitting them reads the last ten minutes. A page stops at the row cap or a six-hour span: continue with next_cursor (same start) while has_more. min_level is one of info, warn, error. Without run_id this needs logs:read. With run_id the run's workflow decides, as for workflow_get_phases: executions:read and permission to view that workflow, not logs:read; a run you cannot view is not found. STAFF may pass organization_id with run_id only, with internal_schedules:read in that org.
Input schema
{
  "properties": {
    "start": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Start"
    },
    "end": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "End"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 512,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "min_level": {
      "anyOf": [
        {
          "enum": [
            "info",
            "warn",
            "error"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Min Level"
    },
    "q": {
      "anyOf": [
        {
          "maxLength": 512,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Q"
    },
    "run_id": {
      "anyOf": [
        {
          "maxLength": 128,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Run Id"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "organization_logs_listArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workflow_files_createReserve uploads for files the user attaches to a Planner message. Returns a bundle id and, per file, a signed upload target valid for 20 minutes: PUT the bytes to its url with exactly its headers (at most 50 MB each; PDF, DOCX, XLSX, CSV, Markdown, text or JSON). Then pass the bundle id in planner_workspace_send files. Use purpose spec for a document that describes the process and data for a file the workflow reads. Never put file contents in the message itself.
Input schema
{
  "$defs": {
    "PlannerWorkflowFileRequestItem": {
      "additionalProperties": false,
      "properties": {
        "file_name": {
          "maxLength": 200,
          "minLength": 1,
          "title": "File Name",
          "type": "string"
        },
        "content_type": {
          "enum": [
            "text/csv",
            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            "application/pdf",
            "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "text/markdown",
            "text/plain",
            "application/json"
          ],
          "title": "Content Type",
          "type": "string"
        },
        "purpose": {
          "default": "data",
          "description": "What the file is for, independent of what it is. `data` is read by the\ngenerated workflow on every run; `spec` is a document read once, at build\ntime, to write the workflow spec. Any accepted content type may be uploaded\nfor either purpose, and the purpose is never inferred from the file\nextension.",
          "enum": [
            "data",
            "spec"
          ],
          "title": "Purpose",
          "type": "string"
        }
      },
      "required": [
        "file_name",
        "content_type"
      ],
      "title": "PlannerWorkflowFileRequestItem",
      "type": "object"
    }
  },
  "properties": {
    "files": {
      "items": {
        "$ref": "#/$defs/PlannerWorkflowFileRequestItem"
      },
      "maxItems": 10,
      "minItems": 1,
      "title": "Files",
      "type": "array"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "files"
  ],
  "title": "planner_workflow_files_createArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_allow_internetAllow the workspace VM to reach public websites and APIs after the user approves. Ask first, naming the org and the reason the Planner gave. Private networks and cloud metadata stay blocked; access ends after minutes (default 30). Then ask the Planner to rerun its test.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "approved": {
      "const": true,
      "title": "Approved",
      "type": "boolean"
    },
    "minutes": {
      "default": 30,
      "maximum": 60,
      "minimum": 5,
      "title": "Minutes",
      "type": "integer"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id",
    "approved"
  ],
  "title": "planner_workspace_allow_internetArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_allow_read_testsApprove read-only integration tests after the user selects the connections. Show the org, exact saved version and connection IDs first. The grant permits 20 calls and expires in 15 minutes. It cannot authorize writes. A changed actor, version or capability requires a new approval.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "version_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Version Id",
      "type": "string"
    },
    "connection_ids": {
      "items": {
        "maxLength": 200,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 10,
      "minItems": 1,
      "title": "Connection Ids",
      "type": "array"
    },
    "expected_version": {
      "exclusiveMinimum": 0,
      "title": "Expected Version",
      "type": "integer"
    },
    "approved": {
      "const": true,
      "title": "Approved",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id",
    "version_id",
    "connection_ids",
    "expected_version",
    "approved"
  ],
  "title": "planner_workspace_allow_read_testsArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_controlPause or archive an idle native E2B session through the trusted controller. Pause retains the VM for resume. Archive deletes the VM and retains its last durable checkpoint. Require the user's intent to archive. Keep the same run_id, action, and expected_version on retry. Follow the returned turn with planner_workspace_wait; queued does not mean the action finished. restore_checkpoint requires explicit user consent to discard an unsaved turn. It only works after the controller confirmed that VM stopped. It restores the last complete checkpoint (or the initial org source if no turn was saved). It does not repeat uncertain external operations. An unknown VM/create outcome stays blocked for operator recovery.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "run_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "expected_version": {
      "exclusiveMinimum": 0,
      "title": "Expected Version",
      "type": "integer"
    },
    "action": {
      "enum": [
        "pause",
        "archive",
        "restore_checkpoint"
      ],
      "title": "Action",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id",
    "run_id",
    "expected_version",
    "action"
  ],
  "title": "planner_workspace_controlArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_createCreate a native E2B Planner session in the selected org. The E2B agent owns planning, files, execution, and conversation history. Relay the user's messages through planner_workspace_send. Do not run a second planning loop in the host chat. Keep session IDs internal. A lost create response is ambiguous; list sessions before creating another.
Input schema
{
  "properties": {
    "title": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Title",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "title"
  ],
  "title": "planner_workspace_createArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_eventsReplay durable progress from a native E2B Planner turn. Relay assistant text faithfully and keep event cursors internal. A completed model turn does not mean a workflow is published. Use the session's saved field to report a durable file checkpoint. Keep after for reconnect after a loss.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "run_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "after": {
      "default": 0,
      "minimum": 0,
      "title": "After",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id",
    "run_id"
  ],
  "title": "planner_workspace_eventsArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_getSelect a native Planner session and read its current state_version. Use this version on the next send. The session belongs to one org; any authorized member in that org may resume it. Do not expose internal IDs.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id"
  ],
  "title": "planner_workspace_getArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_listList native E2B Planner sessions in the selected org. Let the user select an existing session to resume its conversation and private drafts. Multiple workflows may share one session. No VM is started by this read.
Input schema
{
  "properties": {
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "planner_workspace_listArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_live_viewOpen a private view-only noVNC link to the browser executing inside E2B. Give the exact returned URL to the user as a clickable link. Keep its fragment intact. It expires in five minutes; obtain a new view after expiry or disconnect. Do not share or persist the capability URL. The viewer cannot take control or enter passwords. A paused or archived VM is not viewable. No E2B traffic token or model key is returned.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id"
  ],
  "title": "planner_workspace_live_viewArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_publishPublish the exact saved and tested workflow version after human approval. Show the version and test result before asking for approval. Call only when the user explicitly approves publication. A successful model turn is not approval. The session must be idle. Keep every argument unchanged when retrying a lost response. A stale base requires a fresh draft and test. After success, return frontend_url to the user as a clickable Markdown link.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "version_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Version Id",
      "type": "string"
    },
    "expected_base_version_id": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Expected Base Version Id"
    },
    "request_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Request Id",
      "type": "string"
    },
    "approved": {
      "const": true,
      "title": "Approved",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id",
    "version_id",
    "expected_base_version_id",
    "request_id",
    "approved"
  ],
  "title": "planner_workspace_publishArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_sendSend the user's message to the native Planner inside E2B. Forward the message faithfully. Keep a unique run_id before sending and reuse the exact run_id, message, and expected_version after a lost response. Read the session again after a conflict. This queues one native SDK turn; it does not publish workflows or grant access to real external services. Follow with planner_workspace_wait and relay the agent's responses without rewriting its plan or decisions. Do not use legacy planner_start_build. test_timeout_seconds (optional, at most 900) is how long each workflow test of this turn may run unless the Planner sets a bound itself; keep it unchanged on a retry. internet_approved=true only when the user approved public internet for this turn (private networks stay blocked). worker_class: only when the app asks for it (Dev, XY STAFF developer controller); never choose one yourself. files: bundle IDs from planner_workflow_files_create whose files the user attached to this message, after every upload finished. The Planner reads them in /workspace/session/inputs/ (at most 10 files, 50 MB).
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "run_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "expected_version": {
      "exclusiveMinimum": 0,
      "title": "Expected Version",
      "type": "integer"
    },
    "message": {
      "maxLength": 131072,
      "minLength": 1,
      "title": "Message",
      "type": "string"
    },
    "test_timeout_seconds": {
      "anyOf": [
        {
          "maximum": 900,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Test Timeout Seconds"
    },
    "internet_approved": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Internet Approved"
    },
    "worker_class": {
      "anyOf": [
        {
          "pattern": "^workspace-local-[a-z0-9-]{1,40}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Worker Class"
    },
    "files": {
      "anyOf": [
        {
          "items": {
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          },
          "maxItems": 5,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Files"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id",
    "run_id",
    "expected_version",
    "message"
  ],
  "title": "planner_workspace_sendArguments",
  "type": "object",
  "additionalProperties": false
}
planner_workspace_waitWait up to 20 seconds for native Planner progress or a terminal turn. Return on the first event page or terminal status. Continue from after while queued/claimed/started, including after a timeout. Relay the E2B assistant's text faithfully. Do not create your own workflow plan.
Input schema
{
  "properties": {
    "workspace_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workspace Id",
      "type": "string"
    },
    "run_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Run Id",
      "type": "string"
    },
    "after": {
      "default": 0,
      "minimum": 0,
      "title": "After",
      "type": "integer"
    },
    "timeout_seconds": {
      "default": 20,
      "maximum": 20,
      "minimum": 1,
      "title": "Timeout Seconds",
      "type": "integer"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workspace_id",
    "run_id"
  ],
  "title": "planner_workspace_waitArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_approveApprove this exact design version and its returned 16-character resolved_yaml_hash using a system API key with explicit approval authority. When the version exposes release_digest, supply that exact 64-character digest. Supply the current publication.live_version_id receipt, or explicit null before first publication, as expected_live_version_id; stale approval is rejected. This records system approval, not human review or approval by the key creator. It does not publish; personal keys and user-bound OAuth cannot use this operation.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "version_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Version Id",
      "type": "string"
    },
    "resolved_yaml_hash": {
      "maxLength": 16,
      "minLength": 16,
      "pattern": "^[0-9a-f]{16}$",
      "title": "Resolved Yaml Hash",
      "type": "string"
    },
    "expected_live_version_id": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Expected Live Version Id"
    },
    "release_digest": {
      "anyOf": [
        {
          "maxLength": 64,
          "minLength": 64,
          "pattern": "^[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Release Digest"
    }
  },
  "required": [
    "design_id",
    "version_id",
    "resolved_yaml_hash",
    "expected_live_version_id"
  ],
  "title": "queue_ui_approveArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_cancel_runStop the selected or current generation run. Saved versions and previews remain available.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "run_id": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Run Id"
    }
  },
  "required": [
    "design_id"
  ],
  "title": "queue_ui_cancel_runArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_cleanup_previewsFinish this design session and clean up its temporary previews. This closes the session before cleanup: no further messages or publishing are allowed. Start a fresh session to design again. Versions, publication history, and the live queue remain intact; cleanup retries and rollback still work.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    }
  },
  "required": [
    "design_id"
  ],
  "title": "queue_ui_cleanup_previewsArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_get_designCheck a design's progress, current version, review link, and live publication.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    }
  },
  "required": [
    "design_id"
  ],
  "title": "queue_ui_get_designArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_get_eventsRead saved generation progress and summarize it in ordinary language. Keep run_id and after_seq together; start at zero for a new run. After a connection failure, inspect state and events instead of blindly sending another mutation. Generation is not approval or publication. Do not show raw event names or IDs unless the user requests debugging details.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "run_id": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Run Id"
    },
    "after_seq": {
      "default": 0,
      "minimum": 0,
      "title": "After Seq",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "design_id"
  ],
  "title": "queue_ui_get_eventsArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_get_versionInspect one exact saved version and open its preview for human review.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "version_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Version Id",
      "type": "string"
    }
  },
  "required": [
    "design_id",
    "version_id"
  ],
  "title": "queue_ui_get_versionArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_list_designsFind your saved queue designs and their generation or review status.
Input schema
{
  "properties": {
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    }
  },
  "title": "queue_ui_list_designsArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_list_targetsFind workflows whose operator screens your personal or system credential may design.
Input schema
{
  "properties": {
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    }
  },
  "title": "queue_ui_list_targetsArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_list_versionsCompare saved design versions, validation results, and preview links.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    }
  },
  "required": [
    "design_id"
  ],
  "title": "queue_ui_list_versionsArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_publishPublish an exact approved design version_id with authorized personal or system access. Personal publication also requires an ADMIN, PARTNER, or STAFF organization role plus explicit workflow configure permission; a scope alone is not enough. expected_live_version_id is the publication.live_version_id receipt, or null before first publication, not a design version. Approval and target publication permission are checked separately. Cannot approve a design or publish from a closed session.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "version_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Version Id",
      "type": "string"
    },
    "expected_live_version_id": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Expected Live Version Id"
    }
  },
  "required": [
    "design_id",
    "version_id",
    "expected_live_version_id"
  ],
  "title": "queue_ui_publishArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_rollbackRestore an earlier operator screen without changing business data. to_version_id is a receipt from publication.history or publication.baseline_version_id, not a design version. expected_live_version_id is the current publication.live_version_id receipt. Requires authorized personal or system publication access; works after session cleanup.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "to_version_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "To Version Id",
      "type": "string"
    },
    "expected_live_version_id": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Expected Live Version Id"
    }
  },
  "required": [
    "design_id",
    "to_version_id",
    "expected_live_version_id"
  ],
  "title": "queue_ui_rollbackArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_send_messageDescribe screen changes in business language to create a new version. Translate requests such as changing what operators see, filter, decide, or do into the UI contract internally. Reuse the request key when retrying.
Input schema
{
  "properties": {
    "design_id": {
      "description": "The queue design's `id` (starts with qds_).",
      "maxLength": 200,
      "pattern": "^qds_[A-Za-z0-9_-]+$",
      "title": "Design Id",
      "type": "string"
    },
    "prompt": {
      "maxLength": 20000,
      "minLength": 1,
      "pattern": "\\S",
      "title": "Prompt",
      "type": "string"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "design_id",
    "prompt",
    "idempotency_key"
  ],
  "title": "queue_ui_send_messageArguments",
  "type": "object",
  "additionalProperties": false
}
queue_ui_start_designDescribe an operator screen in ordinary business language. Explain what work people should see, which details help them decide, and what actions they need. Do not ask the user for entities, status enums, fields, or a UI schema; the designer infers those from the workflow. Keep the request key for retries, follow progress events, then open the returned review link.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 200,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "prompt": {
      "maxLength": 20000,
      "minLength": 1,
      "pattern": "\\S",
      "title": "Prompt",
      "type": "string"
    },
    "idempotency_key": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Idempotency Key",
      "type": "string"
    }
  },
  "required": [
    "workflow_definition_id",
    "prompt",
    "idempotency_key"
  ],
  "title": "queue_ui_start_designArguments",
  "type": "object",
  "additionalProperties": false
}
review_items_decideApply a supported decision to exact review IDs using the shared REST contract. This can wake downstream workflows. Respect each item's available_decisions and report each result: a 200 response can contain conflicts or refusals. Code-backed writes also require the exact workflow's canReview grant. No idempotency key is needed; writes compare the row version and status. After a timeout, an already committed decision may report not_found on retry. Check review_items_list(state="resolved") before retrying. Reopening requires review_items:revise plus the source run and revision token. Custom backend commands are not implied by a matching status label.
Input schema
{
  "$defs": {
    "AgentReviewRevision": {
      "additionalProperties": false,
      "properties": {
        "execution_id": {
          "description": "The execution that produced this item. Required so a revision is resolved within one run instead of the organization's whole decided history.",
          "title": "Execution Id",
          "type": "string"
        },
        "workflow_instance_id": {
          "description": "The workflow run that produced this item. Use this instead of execution_id for planner_workflow or code_workflow items.",
          "title": "Workflow Instance Id",
          "type": "string"
        },
        "revision_token": {
          "description": "The revision_token returned when the state being reversed was written. If the item has moved on since - including moving away and back - the result is conflict and nothing is written.",
          "title": "Revision Token",
          "type": "string"
        }
      },
      "required": [
        "execution_id",
        "revision_token"
      ],
      "title": "AgentReviewRevision",
      "type": "object"
    },
    "PlannerReviewRevision": {
      "additionalProperties": false,
      "properties": {
        "execution_id": {
          "description": "The execution that produced this item. Required so a revision is resolved within one run instead of the organization's whole decided history.",
          "title": "Execution Id",
          "type": "string"
        },
        "workflow_instance_id": {
          "description": "The workflow run that produced this item. Use this instead of execution_id for planner_workflow or code_workflow items.",
          "title": "Workflow Instance Id",
          "type": "string"
        },
        "revision_token": {
          "description": "The revision_token returned when the state being reversed was written. If the item has moved on since - including moving away and back - the result is conflict and nothing is written.",
          "title": "Revision Token",
          "type": "string"
        }
      },
      "required": [
        "workflow_instance_id",
        "revision_token"
      ],
      "title": "PlannerReviewRevision",
      "type": "object"
    }
  },
  "properties": {
    "item_ids": {
      "items": {
        "type": "string"
      },
      "maxItems": 200,
      "minItems": 1,
      "title": "Item Ids",
      "type": "array"
    },
    "decision": {
      "enum": [
        "approve",
        "reject",
        "defer"
      ],
      "title": "Decision",
      "type": "string"
    },
    "note": {
      "anyOf": [
        {
          "maxLength": 2000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "revise": {
      "anyOf": [
        {
          "$ref": "#/$defs/AgentReviewRevision"
        },
        {
          "$ref": "#/$defs/PlannerReviewRevision"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Revise"
    }
  },
  "required": [
    "item_ids",
    "decision"
  ],
  "title": "review_items_decideArguments",
  "type": "object",
  "additionalProperties": false
}
review_items_listList permitted review records from catalog, Planner or code-backed workflows. Use available_decisions as authority; an empty list means read-only. Code-backed workflows need explicit handover and canonical queue opt-in. Resolved listings require one source run ID and return revision tokens. This returns safe summaries, not raw record attributes or attachments.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workflow Definition Id"
    },
    "workflow_instance_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[^/\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workflow Instance Id"
    },
    "execution_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Execution Id"
    },
    "agent_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    },
    "state": {
      "default": "open",
      "enum": [
        "open",
        "resolved"
      ],
      "title": "State",
      "type": "string"
    },
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "review_items_listArguments",
  "type": "object",
  "additionalProperties": false
}
schedule_createSet up a recurring schedule for a workflow. Tell the user their workflow will run automatically on the specified schedule. Never expose overlap policies, cron syntax details, or definition IDs.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "cron_expression": {
      "title": "Cron Expression",
      "type": "string"
    },
    "input": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Input"
    },
    "overlap_policy": {
      "default": "BUFFER_ALL",
      "title": "Overlap Policy",
      "type": "string"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "required": [
    "workflow_definition_id",
    "cron_expression"
  ],
  "title": "schedule_createArguments",
  "type": "object",
  "additionalProperties": false
}
schedule_deleteDelete a schedule; the workflow definition remains intact.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "schedule_deleteArguments",
  "type": "object",
  "additionalProperties": false
}
schedule_getRead one workflow definition’s recurring schedule.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "schedule_getArguments",
  "type": "object",
  "additionalProperties": false
}
schedule_pausePause future actions for one workflow schedule.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "schedule_pauseArguments",
  "type": "object",
  "additionalProperties": false
}
schedule_resumeResume future actions for one paused workflow schedule.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "schedule_resumeArguments",
  "type": "object",
  "additionalProperties": false
}
schedule_triggerTrigger now; reuse idempotency_key for every retry of one attempt.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "overlap_policy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Overlap Policy"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "schedule_triggerArguments",
  "type": "object",
  "additionalProperties": false
}
schedule_updateUpdate supplied fields on an existing workflow schedule.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "cron_expression": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cron Expression"
    },
    "input": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Input"
    },
    "overlap_policy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Overlap Policy"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "schedule_updateArguments",
  "type": "object",
  "additionalProperties": false
}
schedules_listList schedules and recent runs, including phase availability. STAFF may pass organization_id with internal_schedules:read in that org. Phase availability also requires executions:read and a recorded run.
Input schema
{
  "properties": {
    "limit": {
      "default": 25,
      "exclusiveMinimum": 0,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "paused_only": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Paused Only"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "title": "schedules_listArguments",
  "type": "object",
  "additionalProperties": false
}
session_getRead state and capabilities for Planner, Browser, or queue design sessions. Queue designs also require queue_ui:read.
Input schema
{
  "properties": {
    "target_id": {
      "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
      "maxLength": 200,
      "minLength": 5,
      "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id"
  ],
  "title": "session_getArguments",
  "type": "object",
  "additionalProperties": false
}
session_get_eventsReplay durable events when the session advertises replay_events=true. Events are user-facing progress summaries; events with nothing to show are left out, and next_cursor still moves past them. next_cursor is an event cursor, not a state_version: use the returned state_version for decisions. XY STAFF may pass debug=true for the raw detail.
Input schema
{
  "properties": {
    "target_id": {
      "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
      "maxLength": 200,
      "minLength": 5,
      "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "after": {
      "default": 0,
      "minimum": 0,
      "title": "After",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "debug": {
      "default": false,
      "description": "XY STAFF only. Include sanitized trace detail (logs, token counts, tool timings). Off by default: events are user-facing progress summaries. Never relay debug detail to a customer.",
      "title": "Debug",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id"
  ],
  "title": "session_get_eventsArguments",
  "type": "object",
  "additionalProperties": false
}
session_live_screenshotTake a current screenshot of a build's or Browser Studio session's live browser. Returns the image (JPEG, at most 1024 px wide) with the session state, step and summary. Live overlay status is provided in widget-only metadata. Use it to see what the browser shows right now, or when the user asks; for watching along use session_live_view. When no browser is running, it returns no image and the reason. Needs planner:view for builds and browser:read for Browser Studio sessions; the image may show portal data, so describe it only to people allowed to see that session. The same frame is available over plain HTTP at GET /api/v1/sessions/{target_id}/live-frame.
Input schema
{
  "properties": {
    "target_id": {
      "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
      "maxLength": 200,
      "minLength": 5,
      "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id"
  ],
  "title": "session_live_screenshotArguments",
  "type": "object",
  "additionalProperties": false
}
session_live_viewShow the user the live browser of a Planner build or Browser Studio session. In apps that display views this renders a live browser view: the browser as near-live video where available (else a screenshot every few seconds) with the live view's status (step, phase, sign-in request, who is in control, the agent's current action), a button that opens the view-only live browser, and refresh. Elsewhere, relay summary and give the user live_view.url as a clickable link; never show the token on its own. live_view is null when no browser is running for the session right now (reason says why). The link expires at live_view.expires_at; call again to refresh it. Needs planner:view for builds and browser:read for Browser Studio sessions. Leave stream at its default; the view sets it.
Input schema
{
  "properties": {
    "target_id": {
      "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
      "maxLength": 200,
      "minLength": 5,
      "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "stream": {
      "default": true,
      "title": "Stream",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id"
  ],
  "title": "session_live_viewArguments",
  "type": "object",
  "additionalProperties": false
}
session_reviewFor the session status view: what a waiting build needs from the user. Returns the open review (plan, step, or spec questions) in plain words, the current state_version, and which decisions the view may offer. The decisions themselves go through the Planner decision tools.
Input schema
{
  "properties": {
    "target_id": {
      "maxLength": 200,
      "minLength": 6,
      "pattern": "^pbld_[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id"
  ],
  "title": "session_reviewArguments",
  "type": "object",
  "additionalProperties": false
}
session_sendSend feedback to Planner, Browser, or a queue design. Queue designs also require queue_ui:write; follow their events_path for progress.
Input schema
{
  "properties": {
    "target_id": {
      "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
      "maxLength": 200,
      "minLength": 5,
      "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "message": {
      "maxLength": 200000,
      "minLength": 1,
      "title": "Message",
      "type": "string"
    },
    "source_session_id": {
      "anyOf": [
        {
          "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
          "maxLength": 200,
          "minLength": 5,
          "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source Session Id"
    },
    "step_number": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Step Number"
    },
    "expected_state_version": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected State Version"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id",
    "message"
  ],
  "title": "session_sendArguments",
  "type": "object",
  "additionalProperties": false
}
session_waitWait for a Planner, Browser, or queue design session without losing the cursor. Prefer until=['blocked', 'done', 'failed', 'cancelled']: the call then returns only when the session needs the user or has stopped (or on timeout), with state, reached, a plain-language summary to relay, the events since after, and next_cursor. If resync is true the cursor did not belong to this session: continue from the returned next_cursor. Without until, it returns on the first new user-facing event (Planner builds only); events with nothing to show are skipped and next_cursor moves past them. XY STAFF may pass debug=true for raw event detail.
Input schema
{
  "properties": {
    "target_id": {
      "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
      "maxLength": 200,
      "minLength": 5,
      "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "after": {
      "minimum": 0,
      "title": "After",
      "type": "integer"
    },
    "timeout_seconds": {
      "default": 20,
      "exclusiveMinimum": 0,
      "title": "Timeout Seconds",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "until": {
      "anyOf": [
        {
          "description": "Return as soon as the session is in one of these states. ['blocked', 'done', 'failed', 'cancelled'] waits until it needs the user or has stopped.",
          "items": {
            "enum": [
              "queued",
              "working",
              "blocked",
              "done",
              "failed",
              "cancelled",
              "idle",
              "unknown"
            ],
            "type": "string"
          },
          "maxItems": 8,
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Until"
    },
    "debug": {
      "default": false,
      "description": "XY STAFF only. Include sanitized trace detail (logs, token counts, tool timings). Off by default: events are user-facing progress summaries. Never relay debug detail to a customer.",
      "title": "Debug",
      "type": "boolean"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id",
    "after"
  ],
  "title": "session_waitArguments",
  "type": "object",
  "additionalProperties": false
}
session_watchShow the user a live status view of a Planner, Browser, or queue design session. Returns the current state and a plain-language summary right away. In apps that display the view, it keeps following the session and posts a message into the conversation once the session needs the user or has stopped. Call it once per session, then keep following with session_wait as usual; treat a message from the view like a session_wait result.
Input schema
{
  "properties": {
    "target_id": {
      "description": "A build (pbld_), browser (bas_) or queue design (qds_) id.",
      "maxLength": 200,
      "minLength": 5,
      "pattern": "^(?:pbld_|bas_|qds_)[A-Za-z0-9_-]+$",
      "title": "Target Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "anyOf": [
            {
              "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
              "maxLength": 200,
              "minLength": 1,
              "pattern": "^[^\\\\?#]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization."
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "target_id"
  ],
  "title": "session_watchArguments",
  "type": "object",
  "additionalProperties": false
}
sms_inbox_messagesRead messages received by this organization's dedicated VoIP inbox.
Input schema
{
  "properties": {
    "after_ms": {
      "default": 0,
      "minimum": 0,
      "title": "After Ms",
      "type": "integer"
    },
    "limit": {
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "sms_inbox_messagesArguments",
  "type": "object",
  "additionalProperties": false
}
sms_inbox_provisionProvision or retrieve this organization's dedicated VoIP SMS number.
Input schema
{
  "properties": {
    "country_code": {
      "const": "US",
      "default": "US",
      "title": "Country Code",
      "type": "string"
    },
    "area_code": {
      "anyOf": [
        {
          "pattern": "^[0-9]{3}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Area Code"
    }
  },
  "title": "sms_inbox_provisionArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_configurationGet supported events and organization workflow/queue-state setup choices. Use these workflow IDs and declared queue states to configure actual run outcomes, daily results, and review-required notifications. No raw workflow definitions, item data, or signing secrets are exposed.
Input schema
{
  "properties": {},
  "title": "webhook_configurationArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_deliveries_listInspect delivery, retry, and dead-letter state without response bodies.
Input schema
{
  "properties": {
    "subscription_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Subscription Id"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "webhook_deliveries_listArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_delivery_getRead one webhook delivery status without receiver response bodies.
Input schema
{
  "properties": {
    "delivery_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Delivery Id",
      "type": "string"
    }
  },
  "required": [
    "delivery_id"
  ],
  "title": "webhook_delivery_getArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_delivery_redeliverExplicitly retry a dead-lettered event with its original event ID.
Input schema
{
  "properties": {
    "delivery_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Delivery Id",
      "type": "string"
    }
  },
  "required": [
    "delivery_id"
  ],
  "title": "webhook_delivery_redeliverArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_subscription_createCreate an organization HTTPS receiver; save its one-time signing secret. For workflow run, review, daily-results, or portal sign-in events, supply workflow_notifications selecting organization workflow IDs. Review alerts need explicit queue review_statuses; daily reports use timezone and daily_send_time (defaults UTC, 09:00). Signing secrets verify outbound events; they are not API authorization keys.
Input schema
{
  "$defs": {
    "WorkflowWebhookRule": {
      "additionalProperties": false,
      "properties": {
        "workflow_id": {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "title": "Workflow Id",
          "type": "string"
        },
        "review_statuses": {
          "items": {
            "type": "string"
          },
          "maxItems": 25,
          "title": "Review Statuses",
          "type": "array"
        }
      },
      "required": [
        "workflow_id"
      ],
      "title": "WorkflowWebhookRule",
      "type": "object"
    },
    "WorkflowWebhookSettings": {
      "additionalProperties": false,
      "properties": {
        "workflows": {
          "description": "Explicit workflows owned by this organization; never a cross-org wildcard.",
          "items": {
            "$ref": "#/$defs/WorkflowWebhookRule"
          },
          "maxItems": 25,
          "minItems": 1,
          "title": "Workflows",
          "type": "array"
        },
        "timezone": {
          "default": "UTC",
          "maxLength": 100,
          "minLength": 1,
          "title": "Timezone",
          "type": "string"
        },
        "daily_send_time": {
          "default": "09:00",
          "description": "Local send time for the previous calendar day's daily results.",
          "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$",
          "title": "Daily Send Time",
          "type": "string"
        }
      },
      "required": [
        "workflows"
      ],
      "title": "WorkflowWebhookSettings",
      "type": "object"
    }
  },
  "properties": {
    "url": {
      "title": "Url",
      "type": "string"
    },
    "event_types": {
      "items": {
        "type": "string"
      },
      "title": "Event Types",
      "type": "array"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Description"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    },
    "workflow_notifications": {
      "anyOf": [
        {
          "$ref": "#/$defs/WorkflowWebhookSettings"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "url",
    "event_types"
  ],
  "title": "webhook_subscription_createArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_subscription_deleteIrreversibly disable and hide a webhook; delivery history remains.
Input schema
{
  "properties": {
    "subscription_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Subscription Id",
      "type": "string"
    },
    "version": {
      "minimum": 1,
      "title": "Version",
      "type": "integer"
    }
  },
  "required": [
    "subscription_id",
    "version"
  ],
  "title": "webhook_subscription_deleteArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_subscription_getRead one webhook subscription without its signing secret.
Input schema
{
  "properties": {
    "subscription_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Subscription Id",
      "type": "string"
    }
  },
  "required": [
    "subscription_id"
  ],
  "title": "webhook_subscription_getArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_subscription_rotate_secretRotate a signing secret and save the one-time replacement returned.
Input schema
{
  "properties": {
    "subscription_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Subscription Id",
      "type": "string"
    },
    "version": {
      "minimum": 1,
      "title": "Version",
      "type": "integer"
    }
  },
  "required": [
    "subscription_id",
    "version"
  ],
  "title": "webhook_subscription_rotate_secretArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_subscription_testQueue one signed test event for an active webhook subscription.
Input schema
{
  "properties": {
    "subscription_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Subscription Id",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "subscription_id"
  ],
  "title": "webhook_subscription_testArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_subscription_updateConditionally update an organization webhook subscription.
Input schema
{
  "$defs": {
    "WorkflowWebhookRule": {
      "additionalProperties": false,
      "properties": {
        "workflow_id": {
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "title": "Workflow Id",
          "type": "string"
        },
        "review_statuses": {
          "items": {
            "type": "string"
          },
          "maxItems": 25,
          "title": "Review Statuses",
          "type": "array"
        }
      },
      "required": [
        "workflow_id"
      ],
      "title": "WorkflowWebhookRule",
      "type": "object"
    },
    "WorkflowWebhookSettings": {
      "additionalProperties": false,
      "properties": {
        "workflows": {
          "description": "Explicit workflows owned by this organization; never a cross-org wildcard.",
          "items": {
            "$ref": "#/$defs/WorkflowWebhookRule"
          },
          "maxItems": 25,
          "minItems": 1,
          "title": "Workflows",
          "type": "array"
        },
        "timezone": {
          "default": "UTC",
          "maxLength": 100,
          "minLength": 1,
          "title": "Timezone",
          "type": "string"
        },
        "daily_send_time": {
          "default": "09:00",
          "description": "Local send time for the previous calendar day's daily results.",
          "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$",
          "title": "Daily Send Time",
          "type": "string"
        }
      },
      "required": [
        "workflows"
      ],
      "title": "WorkflowWebhookSettings",
      "type": "object"
    }
  },
  "properties": {
    "subscription_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Subscription Id",
      "type": "string"
    },
    "version": {
      "minimum": 1,
      "title": "Version",
      "type": "integer"
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url"
    },
    "event_types": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Event Types"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Description"
    },
    "status": {
      "anyOf": [
        {
          "enum": [
            "active",
            "disabled"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "workflow_notifications": {
      "anyOf": [
        {
          "$ref": "#/$defs/WorkflowWebhookSettings"
        },
        {
          "type": "null"
        }
      ],
      "title": "Workflow Notifications"
    }
  },
  "required": [
    "subscription_id",
    "version"
  ],
  "title": "webhook_subscription_updateArguments",
  "type": "object",
  "additionalProperties": false
}
webhook_subscriptions_listList organization webhook subscriptions without signing secrets.
Input schema
{
  "properties": {},
  "title": "webhook_subscriptions_listArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_archiveArchive one workflow (the app's Delete): it leaves workflow lists and stops running. Only for workflows built in the Planner or app (UI-versioned); a code-backed workflow answers WORKFLOW_CODE_BACKED and is retired through Engineering. Its schedule is paused first (schedule_paused), its versions and run history stay, and it is renamed "<name> (deleted <UTC minute>)" so the name is free for a new workflow. Confirm with the user before archiving. Repeating it returns the same result. Needs planner:promote and permission to configure the workflow.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_archiveArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_cancel_runStop one workflow run, preserving its schedule and sibling runs. Applies to permitted code-backed and Planner workflows. This requests cancellation; use workflow_get_phases to confirm the final state. It does not undo external work already completed. Retain the key on retries.
Input schema
{
  "properties": {
    "workflow_instance_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[^/\\\\?#]+$",
      "title": "Workflow Instance Id",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "workflow_instance_id"
  ],
  "title": "workflow_cancel_runArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_change_getFollow an exact workflow change through review. Ticket completion is separate from verified publication of that change to the live workflow.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "change_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Change Id",
      "type": "string"
    }
  },
  "required": [
    "workflow_definition_id",
    "change_id"
  ],
  "title": "workflow_change_getArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_change_requestPropose a workflow change after reading its published Logic. Requires configure permission. Describe the desired behavior in body; retain scope_id and revision_id from workflow_logic_get. Code-backed changes go to Engineering/FDE review, never the Planner editor. This records intent; it does not change the live flow or start a build. Retain the same idempotency key and body when retrying.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "scope_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Scope Id",
      "type": "string"
    },
    "revision_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Revision Id",
      "type": "string"
    },
    "body": {
      "maxLength": 12000,
      "minLength": 1,
      "title": "Body",
      "type": "string"
    },
    "stage_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Stage Id"
    },
    "acknowledge_stale_base": {
      "default": false,
      "title": "Acknowledge Stale Base",
      "type": "boolean"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "workflow_definition_id",
    "scope_id",
    "revision_id",
    "body"
  ],
  "title": "workflow_change_requestArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_executeRun a permitted Planner or code-backed workflow once now. Inspect its approved runtime inputs with workflow_get first. Defaults to a **test** run (`is_test` true), matching in-app WebMCP. For a real production run set `is_test` false and `confirm` true only after the user explicitly asked. Test mode labels runs and data; it can still act on external systems. Tell them it is running and share the returned `trace_path` (XY-Mind Trace tab). Queues still show items; Trace is the run timeline. Never invent a Trace link from a catalog-agent execution_id. Never expose the definition ID or workflow_instance_id unless they ask for debugging details.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "input": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Input"
    },
    "is_test": {
      "default": true,
      "title": "Is Test",
      "type": "boolean"
    },
    "confirm": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Confirm"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_executeArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_getRead workflow metadata, runtime input contract and current permissions. Use the same operation for Planner and code-backed workflows. Inputs not declared in the code-backed workflow's approved schema are rejected; omitted input uses its saved defaults. This never returns source code, credentials or stored input values. Return frontend_url as a clickable Markdown link when the user asks to open the workflow. It points to this environment's application.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_getArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_get_phasesRead safe phases for an exact workflow run. include_data adds each phase's recorded input and output, the keys and values each step received and returned: bounded and credential-redacted values for a test run; for a production run only their top-level keys (input_keys, output_keys) with data_withheld: production. data_environment says which applied. include_trace adds trace, the run as the Trace tab shows it. With trace.structure_available, nodes are the workflow definition's statements (kind, parent_id, arm, order; branches never taken are not_reached) carrying state, attempts, timing, waits and error_type, and edges have role step, enter or exit. Loops report progress, total and item flags; a page of loop items arrives as kind loop_item nodes with their own steps (iteration_index, child_workflow_id), and a loop's items_next_cursor passed as trace_cursor returns its next page. Without a structure, nodes are the recorded steps with edges inferred from timing. To poll, pass trace.cursor back as trace_cursor; an unchanged run answers trace.unchanged: true. The trace carries no inputs, outputs, conditions, expressions or error text. Needs executions:read and permission to view the run's workflow, the same check as workflow_get; a run you cannot view is not found. STAFF may pass organization_id with internal_schedules:read for org-wide runs. Planner step-test runs retain internal_agent_requests:read access when the caller can see their build.
Input schema
{
  "properties": {
    "workflow_instance_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[^/\\\\?#]+$",
      "title": "Workflow Instance Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    },
    "include_trace": {
      "default": false,
      "title": "Include Trace",
      "type": "boolean"
    },
    "trace_cursor": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Trace Cursor"
    },
    "include_data": {
      "default": false,
      "title": "Include Data",
      "type": "boolean"
    }
  },
  "required": [
    "workflow_instance_id"
  ],
  "title": "workflow_get_phasesArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_logic_getRead the published business Logic of a permitted workflow. Works for Planner and developer-built workflows. Follow next_offset with the returned revision_id as expected_revision_id. Unavailable means no published description yet. This never retrieves implementation code.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "scope_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scope Id"
    },
    "offset": {
      "default": 0,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    },
    "expected_revision_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[A-Za-z0-9_.:-]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Revision Id"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_logic_getArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_metric_dashboard_getRender one approved metric view for a workflow (same access as the list). Omit both dates for the shared inclusive 30-day UTC window ending today (or that zone's today when timezone is set). Tiles that do not accept dates retain their own window and are marked. XY staff may pass organization_id for another organization where they are STAFF; it needs internal_dashboards:read there.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "dashboard_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Dashboard Id",
      "type": "string"
    },
    "from_date": {
      "anyOf": [
        {
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From Date"
    },
    "to_date": {
      "anyOf": [
        {
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To Date"
    },
    "timezone": {
      "anyOf": [
        {
          "maxLength": 64,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional IANA zone (e.g. America/New_York) for the window and day buckets; default UTC.",
      "title": "Timezone"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "workflow_definition_id",
    "dashboard_id"
  ],
  "title": "workflow_metric_dashboard_getArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_metric_dashboards_listList approved metric views for one workflow you or your dashboards can see. Access is an explicit workflow view grant, or a grant on the dashboard itself (STAFF see every dashboard). XY staff may read another organization where they are STAFF by passing organization_id; it needs internal_dashboards:read there.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID, slug, or exact name where you are STAFF. Omit to use the credential's own organization.",
      "title": "Organization Id"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_metric_dashboards_listArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_operating_costRead this permitted workflow's own collected operating cost. Requires separate organization cost approval (useOperatingCostReports), usage:read and permission to view the workflow; otherwise returns 403. Works for Planner and code-backed workflows without an original order. Optional from_time/to_time are timezone-aware ISO timestamps (default last 30 days). Only completed UTC days are costed, after daily collection. Cost combines recorded model charges and allocated worker/orchestration costs, including estimated logging costs allocated to the workflow. Original evidence is unchanged; logging is allocated, not metered. Partial is a subtotal and unavailable is null, never free. Per-item averages require complete item coverage. This is not a price or invoice.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "from_time": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From Time"
    },
    "to_time": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To Time"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_operating_costArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_records_listList the queue records one workflow's runs wrote, newest first, with their types. record_types gives each type's count and declared attributes (key, data_type, label, required, pii_level). Test records are returned whole. A production record returns its attribute values only to XY STAFF holding records:read_values; otherwise its keys are listed in withheld. Only this organization's records are returned. Pass workflow_instance_id for the records of one run. Follow next_cursor while has_more. Needs permission to view the workflow.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 512,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "environment": {
      "default": "prod",
      "enum": [
        "prod",
        "test",
        "all"
      ],
      "title": "Environment",
      "type": "string"
    },
    "workflow_instance_id": {
      "anyOf": [
        {
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[^/\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workflow Instance Id"
    },
    "entity_type_key": {
      "anyOf": [
        {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Entity Type Key"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_records_listArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_renameRename one workflow built in the Planner or app, and replace its description when given. No other active workflow in the organization may have the name (WORKFLOW_NAME_TAKEN). A code-backed workflow answers WORKFLOW_CODE_BACKED: it is renamed through Engineering. Returns the workflow as workflow_get reads it. Needs planner:promote and permission to view and configure the workflow.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "name": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Name",
      "type": "string"
    },
    "description": {
      "anyOf": [
        {
          "maxLength": 2000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Description"
    }
  },
  "required": [
    "workflow_definition_id",
    "name"
  ],
  "title": "workflow_renameArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_rollbackMake an earlier version of one workflow live again (roll back, or forward again). version_id must have been live before (workflow_versions_list: publication_count > 0); a version that never went live answers WORKFLOW_VERSION_NEVER_PUBLISHED and is published through the Planner's tested publish. expected_published_version_id is the version you saw live; if another went live since, nothing changes (WORKFLOW_VERSION_CHANGED: read the versions again). Schedules follow the new live version; with a schedule only an organization manager may do this (WORKFLOW_SCHEDULE_PERMISSION_REQUIRED). Nothing is deleted: every version stays and can be made live again. request_id is your key for this rollback: retry with the same key and you get the first answer back; use a new key for a new rollback. A version whose queue screen contains code answers WORKFLOW_QUEUE_CODE_ROLLBACK (Queue UI designer). Confirm with the user first. Needs planner:promote and permission to configure the workflow.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "version_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Version Id",
      "type": "string"
    },
    "expected_published_version_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Expected Published Version Id",
      "type": "string"
    },
    "request_id": {
      "maxLength": 500,
      "minLength": 1,
      "title": "Request Id",
      "type": "string"
    }
  },
  "required": [
    "workflow_definition_id",
    "version_id",
    "expected_published_version_id",
    "request_id"
  ],
  "title": "workflow_rollbackArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_runs_listList every recorded run of one workflow, newest first (all triggers, not only scheduled). Each run has status, timing, trigger, environment, the newest failed step's error_type, phase availability and the saved version it ran (version_id, version; null when the workflow is edited in place); never input, output or error text. Production runs only unless environment is test or all. Follow next_cursor while has_more. since is a timezone-aware ISO timestamp. Open one run with workflow_get_phases (include_trace for its step graph); read its logs with organization_logs_list(run_id, start=started_at, end=finished_at). Needs executions:read and permission to view the workflow, the same check as workflow_get; those also read its runs' phases, trace and logs, without logs:read. STAFF may pass organization_id with internal_schedules:read in that org.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 512,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "status": {
      "anyOf": [
        {
          "enum": [
            "pending",
            "running",
            "completed",
            "completed_with_failures",
            "failed",
            "canceled"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "environment": {
      "default": "prod",
      "enum": [
        "prod",
        "test",
        "all"
      ],
      "title": "Environment",
      "type": "string"
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Since"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_runs_listArguments",
  "type": "object",
  "additionalProperties": false
}
workflow_versions_listList a workflow's saved versions, newest first: which one is published and when each was published. Use it to answer version-history questions: when each version was saved and published, which version runs now, what was rolled back to. It does not show what changed between versions (no content diff). Each version has version_id, version, base_version_id (the version it was saved from), created_at, published, published_at (last publish or rollback to it) and publication_count. published_version_id is the version that runs now. Metadata only: never source code, definitions, hashes or who saved it. A LEGACY_IN_PLACE workflow is edited in place and has no versions. Follow next_cursor while has_more. A new version comes from the Planner (save with workflow_id and base_version_id = the published version) and is published from the app; workflow_rollback makes an earlier live version live again. Needs executions:read and permission to view the workflow, the same check as workflow_get. STAFF may pass organization_id with internal_schedules:read in that org.
Input schema
{
  "properties": {
    "workflow_definition_id": {
      "maxLength": 500,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_.:-]+$",
      "title": "Workflow Definition Id",
      "type": "string"
    },
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 512,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cursor"
    },
    "organization_id": {
      "anyOf": [
        {
          "description": "Exact organization ID, slug, or name. Omit to use the organization where this credential was created.",
          "maxLength": 200,
          "minLength": 1,
          "pattern": "^[^\\\\?#]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Organization Id"
    }
  },
  "required": [
    "workflow_definition_id"
  ],
  "title": "workflow_versions_listArguments",
  "type": "object",
  "additionalProperties": false
}
workflows_listFind workflows you may view, including delivered code-backed workflows. These are the organization's permitted workflows, not the global agent catalog. Inspect one with workflow_get before supplying runtime inputs.
Input schema
{
  "properties": {
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "maximum": 1000000,
      "minimum": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "workflows_listArguments",
  "type": "object",
  "additionalProperties": false
}

Security model

Authorization defines the boundary.

  • Interactive OAuth access is bound to the approving user, selected XY organization, exact MCP resource, and approved scopes.
  • Personal API keys are also user-bound; service API keys represent unattended organization systems rather than a human actor.
  • Every OAuth request rechecks the user's current organization membership and assigned API scopes; endpoint-specific workflow permissions still apply.
  • Interactive access must be enabled for the organization, and each user receives only the scopes assigned to their identity.
  • Every tool operation receives a request ID and a payload-free audit record with its credential, actor when applicable, organization, route, outcome, and opaque target identifiers.
  • OAuth grants and API keys are environment-bound; this public guide always uses production.
  • Tool discovery is filtered to the scopes on the current OAuth grant or API key.
  • Queue UI Designer supports personal access with explicit workflow permissions and system keys with organization authorization. Only system keys with queue_ui:approve can use queue_ui_approve; personal OAuth cannot. Publish never grants approval.
  • API keys belong in a secret manager or OS keychain, never in a URL or source control.
  • Credential-bound workflows require an exact visible Password Vault reference. MCP clients can discover safe metadata and receive credential IDs, never plaintext secrets.
For AI agents