# Apply workflow operations (/api-reference/workflows/applyWorkflowOperations) `POST /api/v2/workflows/{workflowId}/operations` Apply draft edits and block enablement changes in one write. Requires workspace write access. The live deployment is unchanged; lint is advisory. Inspect `skipped` and `inputValidationErrors` for edits that did not apply. Deferred edges apply when their targets exist; do not resubmit them. With `atomic=true`, declined operations or dropped inputs return `409` (`OPERATIONS_NOT_APPLIED`) without saving. Use returned `mintedBlockIds` in later requests. `dryRun=true` evaluates without saving, auditing, or notifying. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`. ## Authentication ```json { "requirements": [ { "apiKey": [] }, { "oauthBearer": [ "api:write" ] } ], "schemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description." }, "oauthBearer": { "type": "oauth2", "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).", "flows": { "authorizationCode": { "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize", "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token", "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token", "scopes": { "api:read": "Read your workspaces, workflows, files, tables, and logs", "api:write": "Read, create, change, run, and delete resources in your workspaces", "offline_access": "Stay signed in without asking again" } } } } } } ``` Required OAuth scope: `api:write`. ## Request examples ### cURL ```bash curl --request POST 'https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/operations' \ --header 'X-API-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "operations": [ { "operation_type": "add", "block_id": "agent-1", "params": { "type": "agent", "name": "Triage", "inputs": { "tools": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] } } } ] }' ``` ### JavaScript ```javascript const response = await fetch("https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/operations", { "method": "POST", "headers": { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" }, "body": "{\n \"operations\": [\n {\n \"operation_type\": \"add\",\n \"block_id\": \"agent-1\",\n \"params\": {\n \"type\": \"agent\",\n \"name\": \"Triage\",\n \"inputs\": {\n \"tools\": [\n {\n \"type\": \"cloudwatch\",\n \"operation\": \"describe_alarm_history\",\n \"usageControl\": \"auto\",\n \"params\": {}\n }\n ]\n }\n }\n }\n ]\n}" }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const result = await response.json(); ``` ### Python ```python import requests response = requests.request( "POST", "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/operations", headers={ "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" }, data="{\n \"operations\": [\n {\n \"operation_type\": \"add\",\n \"block_id\": \"agent-1\",\n \"params\": {\n \"type\": \"agent\",\n \"name\": \"Triage\",\n \"inputs\": {\n \"tools\": [\n {\n \"type\": \"cloudwatch\",\n \"operation\": \"describe_alarm_history\",\n \"usageControl\": \"auto\",\n \"params\": {}\n }\n ]\n }\n }\n }\n ]\n}", ) response.raise_for_status() result = response.json() ``` ### Go ```go package main import ( "io" "net/http" "os" "strings" ) func check(err error) { if err != nil { panic(err) } } func must[T any](value T, err error) T { check(err) return value } func main() { request := must(http.NewRequest("POST", "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/operations", strings.NewReader("{\n \"operations\": [\n {\n \"operation_type\": \"add\",\n \"block_id\": \"agent-1\",\n \"params\": {\n \"type\": \"agent\",\n \"name\": \"Triage\",\n \"inputs\": {\n \"tools\": [\n {\n \"type\": \"cloudwatch\",\n \"operation\": \"describe_alarm_history\",\n \"usageControl\": \"auto\",\n \"params\": {}\n }\n ]\n }\n }\n }\n ]\n}"))) request.Header.Set("X-API-Key", "YOUR_API_KEY") request.Header.Set("Content-Type", "application/json") response := must(http.DefaultClient.Do(request)) defer response.Body.Close() if response.StatusCode >= 400 { panic(response.Status) } must(io.Copy(os.Stdout, response.Body)) } ``` ### Java ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Example { public static void main(String[] args) throws Exception { var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/operations")); builder.header("X-API-Key", "YOUR_API_KEY"); builder.header("Content-Type", "application/json"); var request = builder.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"operations\": [\n {\n \"operation_type\": \"add\",\n \"block_id\": \"agent-1\",\n \"params\": {\n \"type\": \"agent\",\n \"name\": \"Triage\",\n \"inputs\": {\n \"tools\": [\n {\n \"type\": \"cloudwatch\",\n \"operation\": \"describe_alarm_history\",\n \"usageControl\": \"auto\",\n \"params\": {}\n }\n ]\n }\n }\n }\n ]\n}")).build(); var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream()); try (var body = response.body()) { if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode()); body.transferTo(System.out); } } } ``` ### C# ```csharp using System; using System.IO; using System.Net.Http; using System.Text; using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/operations"); request.Content = new StringContent("{\n \"operations\": [\n {\n \"operation_type\": \"add\",\n \"block_id\": \"agent-1\",\n \"params\": {\n \"type\": \"agent\",\n \"name\": \"Triage\",\n \"inputs\": {\n \"tools\": [\n {\n \"type\": \"cloudwatch\",\n \"operation\": \"describe_alarm_history\",\n \"usageControl\": \"auto\",\n \"params\": {}\n }\n ]\n }\n }\n }\n ]\n}", Encoding.UTF8); request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY"); request.Content!.Headers.ContentType = System.Net.Http.Headers.MediaTypeHeaderValue.Parse("application/json"); using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead); response.EnsureSuccessStatusCode(); await response.Content.CopyToAsync(Console.OpenStandardOutput()); ``` ## Parameters ```json [ { "name": "workflowId", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": [ "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36" ] } }, { "name": "dryRun", "in": "query", "required": false, "description": "Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs.", "schema": { "description": "Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs.", "type": "boolean" } } ] ``` ## Request body ```json { "required": true, "description": "A batch of semantic edits against a workflow graph.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "operation_type": { "type": "string", "const": "add", "description": "Create a new block." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "description": "Registered block type." }, "name": { "type": "string", "minLength": 1, "description": "Block display name." }, "inputs": { "allOf": [ { "type": "object", "properties": { "tools": { "maxItems": 100, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(?!(?:custom-tool|mcp|mcp-server-advanced)$).+$", "description": "Catalog block id, such as `cloudwatch` or `slack`. Use the block id, never an underlying tool id." }, "operation": { "description": "Operation ID from Get Block. Required when the block exposes multiple operations; it may differ from the tool ID.", "type": "string", "minLength": 1, "maxLength": 255 }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One tool parameter value." }, "description": "Parameters fixed by the workflow author. Parameters left out remain available for the model to supply when the tool declares them." } }, "required": [ "type" ], "additionalProperties": { "description": "Forward-compatible integration tool metadata preserved by the workflow editor." }, "title": "Agent integration tool", "description": "A catalog integration operation the Agent may call. Resolve valid block and operation ids through the block catalog.", "examples": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] }, { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "customToolId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Custom tool ID from List Custom Tools." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "customToolId" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "schema": { "type": "object", "properties": { "type": { "description": "Function declaration discriminator.", "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Function name presented to the model." }, "description": { "description": "What the inline custom tool does.", "type": "string" }, "parameters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One JSON Schema keyword on the function parameters." }, "description": "JSON Schema describing the function arguments." } }, "required": [ "name", "parameters" ], "additionalProperties": { "description": "Additional function declaration metadata." }, "description": "OpenAI-style function definition." } }, "required": [ "function" ], "additionalProperties": { "description": "Additional custom tool declaration metadata." }, "description": "Inline OpenAI-style function declaration." }, "code": { "type": "string", "description": "Inline tool implementation executed by the Function runtime." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "schema", "code" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } } ], "title": "Agent custom tool", "description": "A workspace custom tool. Prefer `customToolId`; inline declarations are also accepted.", "examples": [ { "type": "custom-tool", "customToolId": "cst_01J9X2ABCDEF", "usageControl": "auto" } ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp", "description": "MCP-tool discriminator." }, "params": { "allOf": [ { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "MCP server id returned by `GET /api/v2/mcp-servers`." }, "toolName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name returned by the MCP server’s tools endpoint." } }, "required": [ "serverId", "toolName" ], "additionalProperties": { "description": "One parameter fixed by the workflow author." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One parameter fixed by the workflow author." } } ], "description": "MCP server and tool identity plus any tool arguments fixed by the workflow author." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP tool metadata preserved by the workflow editor." }, "title": "Agent MCP tool", "description": "One tool discovered from a workspace MCP server.", "examples": [ { "type": "mcp", "params": { "serverId": "mcp_01J9X2ABCDEF", "toolName": "search_docs" }, "usageControl": "auto" } ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp-server-advanced", "description": "Server-wide MCP binding discriminator." }, "operationPolicy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Allow all operations available to the authorized credential." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "allow", "description": "Allow only the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Allowed exact MCP tool names; an empty list grants no access." } }, "required": [ "mode", "operations" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "deny", "description": "Exclude the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Denied exact MCP tool names; an empty list allows otherwise permitted tools." } }, "required": [ "mode", "operations" ], "additionalProperties": false } ], "description": "Saved workflow operation restrictions that can only narrow authorized credential access." }, "params": { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Workspace MCP server ID or explicit credential-group managed MCP connection ID." } }, "required": [ "serverId" ], "additionalProperties": false, "description": "Executable server or connection identity for authorized operation discovery and execution." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP server metadata preserved by the workflow editor." }, "title": "Agent MCP server (advanced)", "description": "Dynamically discovered operations permitted by the authorized credential and saved block policy.", "examples": [ { "type": "mcp-server-advanced", "params": { "serverId": "mcp_01J9X2ABCDEF" }, "usageControl": "auto" } ] } ], "title": "Agent tool", "description": "A catalog integration operation, workspace custom tool, or MCP tool available to an Agent." }, "description": "Agent tools configuration. Applies to a `tool-input` field; other block inputs remain catalog-defined.", "title": "Agent tools input" } }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } } ], "description": "Block configuration keyed by sub-block id." } }, "required": [ "type", "name" ], "additionalProperties": { "description": "One block-specific input or connection descriptor." }, "description": "Block `type`, `name`, and optional `inputs`, `connections`, `retry`, `triggerMode`, or `advancedMode`. `inputs` maps sub-block ids directly to values, never through `subBlocks`. Keep `retry`, `triggerMode`, and `advancedMode` beside `inputs`. `connections` maps source handles to target ids, `{ block, handle }`, or arrays; `success` aliases `source`." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "edit", "description": "Change an existing block: its inputs, name, or connections." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "allOf": [ { "type": "object", "properties": { "inputs": { "allOf": [ { "type": "object", "properties": { "tools": { "maxItems": 100, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(?!(?:custom-tool|mcp|mcp-server-advanced)$).+$", "description": "Catalog block id, such as `cloudwatch` or `slack`. Use the block id, never an underlying tool id." }, "operation": { "description": "Operation ID from Get Block. Required when the block exposes multiple operations; it may differ from the tool ID.", "type": "string", "minLength": 1, "maxLength": 255 }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One tool parameter value." }, "description": "Parameters fixed by the workflow author. Parameters left out remain available for the model to supply when the tool declares them." } }, "required": [ "type" ], "additionalProperties": { "description": "Forward-compatible integration tool metadata preserved by the workflow editor." }, "title": "Agent integration tool", "description": "A catalog integration operation the Agent may call. Resolve valid block and operation ids through the block catalog.", "examples": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] }, { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "customToolId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Custom tool ID from List Custom Tools." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "customToolId" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "schema": { "type": "object", "properties": { "type": { "description": "Function declaration discriminator.", "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Function name presented to the model." }, "description": { "description": "What the inline custom tool does.", "type": "string" }, "parameters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One JSON Schema keyword on the function parameters." }, "description": "JSON Schema describing the function arguments." } }, "required": [ "name", "parameters" ], "additionalProperties": { "description": "Additional function declaration metadata." }, "description": "OpenAI-style function definition." } }, "required": [ "function" ], "additionalProperties": { "description": "Additional custom tool declaration metadata." }, "description": "Inline OpenAI-style function declaration." }, "code": { "type": "string", "description": "Inline tool implementation executed by the Function runtime." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "schema", "code" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } } ], "title": "Agent custom tool", "description": "A workspace custom tool. Prefer `customToolId`; inline declarations are also accepted.", "examples": [ { "type": "custom-tool", "customToolId": "cst_01J9X2ABCDEF", "usageControl": "auto" } ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp", "description": "MCP-tool discriminator." }, "params": { "allOf": [ { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "MCP server id returned by `GET /api/v2/mcp-servers`." }, "toolName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name returned by the MCP server’s tools endpoint." } }, "required": [ "serverId", "toolName" ], "additionalProperties": { "description": "One parameter fixed by the workflow author." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One parameter fixed by the workflow author." } } ], "description": "MCP server and tool identity plus any tool arguments fixed by the workflow author." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP tool metadata preserved by the workflow editor." }, "title": "Agent MCP tool", "description": "One tool discovered from a workspace MCP server.", "examples": [ { "type": "mcp", "params": { "serverId": "mcp_01J9X2ABCDEF", "toolName": "search_docs" }, "usageControl": "auto" } ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp-server-advanced", "description": "Server-wide MCP binding discriminator." }, "operationPolicy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Allow all operations available to the authorized credential." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "allow", "description": "Allow only the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Allowed exact MCP tool names; an empty list grants no access." } }, "required": [ "mode", "operations" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "deny", "description": "Exclude the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Denied exact MCP tool names; an empty list allows otherwise permitted tools." } }, "required": [ "mode", "operations" ], "additionalProperties": false } ], "description": "Saved workflow operation restrictions that can only narrow authorized credential access." }, "params": { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Workspace MCP server ID or explicit credential-group managed MCP connection ID." } }, "required": [ "serverId" ], "additionalProperties": false, "description": "Executable server or connection identity for authorized operation discovery and execution." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP server metadata preserved by the workflow editor." }, "title": "Agent MCP server (advanced)", "description": "Dynamically discovered operations permitted by the authorized credential and saved block policy.", "examples": [ { "type": "mcp-server-advanced", "params": { "serverId": "mcp_01J9X2ABCDEF" }, "usageControl": "auto" } ] } ], "title": "Agent tool", "description": "A catalog integration operation, workspace custom tool, or MCP tool available to an Agent." }, "description": "Agent tools configuration. Applies to a `tool-input` field; other block inputs remain catalog-defined.", "title": "Agent tools input" } }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } } ], "description": "Block configuration keyed by sub-block id." } }, "additionalProperties": { "description": "One operation parameter; see the description for the accepted keys." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One operation parameter; see the description for the accepted keys." } } ], "description": "Patch only supplied fields: `inputs`, `name`, `connections`, `removeEdges`, `nestedNodes`, `retry`, `triggerMode`, and `advancedMode`. `inputs` maps sub-block ids directly to values, never through `subBlocks`. Keep `retry`, `triggerMode`, and `advancedMode` beside `inputs`. `connections` maps source handles to target ids, `{ block, handle }`, or arrays; `success` aliases `source`. Re-sending `connections` replaces outgoing edges; use `removeEdges` to delete selected edges." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "delete", "description": "Remove a block and every edge touching it." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." } }, "required": [ "operation_type", "block_id" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "insert_into_subflow", "description": "Create a block inside a loop or parallel container." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "type": "object", "properties": { "subflowId": { "type": "string", "minLength": 1, "description": "Loop or parallel container to insert the block into." }, "type": { "type": "string", "minLength": 1, "description": "Registered block type." }, "name": { "type": "string", "minLength": 1, "description": "Block display name." }, "inputs": { "allOf": [ { "type": "object", "properties": { "tools": { "maxItems": 100, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(?!(?:custom-tool|mcp|mcp-server-advanced)$).+$", "description": "Catalog block id, such as `cloudwatch` or `slack`. Use the block id, never an underlying tool id." }, "operation": { "description": "Operation ID from Get Block. Required when the block exposes multiple operations; it may differ from the tool ID.", "type": "string", "minLength": 1, "maxLength": 255 }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One tool parameter value." }, "description": "Parameters fixed by the workflow author. Parameters left out remain available for the model to supply when the tool declares them." } }, "required": [ "type" ], "additionalProperties": { "description": "Forward-compatible integration tool metadata preserved by the workflow editor." }, "title": "Agent integration tool", "description": "A catalog integration operation the Agent may call. Resolve valid block and operation ids through the block catalog.", "examples": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] }, { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "customToolId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Custom tool ID from List Custom Tools." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "customToolId" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "schema": { "type": "object", "properties": { "type": { "description": "Function declaration discriminator.", "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Function name presented to the model." }, "description": { "description": "What the inline custom tool does.", "type": "string" }, "parameters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One JSON Schema keyword on the function parameters." }, "description": "JSON Schema describing the function arguments." } }, "required": [ "name", "parameters" ], "additionalProperties": { "description": "Additional function declaration metadata." }, "description": "OpenAI-style function definition." } }, "required": [ "function" ], "additionalProperties": { "description": "Additional custom tool declaration metadata." }, "description": "Inline OpenAI-style function declaration." }, "code": { "type": "string", "description": "Inline tool implementation executed by the Function runtime." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "schema", "code" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } } ], "title": "Agent custom tool", "description": "A workspace custom tool. Prefer `customToolId`; inline declarations are also accepted.", "examples": [ { "type": "custom-tool", "customToolId": "cst_01J9X2ABCDEF", "usageControl": "auto" } ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp", "description": "MCP-tool discriminator." }, "params": { "allOf": [ { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "MCP server id returned by `GET /api/v2/mcp-servers`." }, "toolName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name returned by the MCP server’s tools endpoint." } }, "required": [ "serverId", "toolName" ], "additionalProperties": { "description": "One parameter fixed by the workflow author." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One parameter fixed by the workflow author." } } ], "description": "MCP server and tool identity plus any tool arguments fixed by the workflow author." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP tool metadata preserved by the workflow editor." }, "title": "Agent MCP tool", "description": "One tool discovered from a workspace MCP server.", "examples": [ { "type": "mcp", "params": { "serverId": "mcp_01J9X2ABCDEF", "toolName": "search_docs" }, "usageControl": "auto" } ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "mcp-server-advanced", "description": "Server-wide MCP binding discriminator." }, "operationPolicy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Allow all operations available to the authorized credential." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "allow", "description": "Allow only the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Allowed exact MCP tool names; an empty list grants no access." } }, "required": [ "mode", "operations" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "deny", "description": "Exclude the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Denied exact MCP tool names; an empty list allows otherwise permitted tools." } }, "required": [ "mode", "operations" ], "additionalProperties": false } ], "description": "Saved workflow operation restrictions that can only narrow authorized credential access." }, "params": { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Workspace MCP server ID or explicit credential-group managed MCP connection ID." } }, "required": [ "serverId" ], "additionalProperties": false, "description": "Executable server or connection identity for authorized operation discovery and execution." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP server metadata preserved by the workflow editor." }, "title": "Agent MCP server (advanced)", "description": "Dynamically discovered operations permitted by the authorized credential and saved block policy.", "examples": [ { "type": "mcp-server-advanced", "params": { "serverId": "mcp_01J9X2ABCDEF" }, "usageControl": "auto" } ] } ], "title": "Agent tool", "description": "A catalog integration operation, workspace custom tool, or MCP tool available to an Agent." }, "description": "Agent tools configuration. Applies to a `tool-input` field; other block inputs remain catalog-defined.", "title": "Agent tools input" } }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } } ], "description": "Block configuration keyed by sub-block id." } }, "required": [ "subflowId", "type", "name" ], "additionalProperties": { "description": "One block-specific input or connection descriptor." }, "description": "Container, block `type`, `name`, and the same optional fields as `add`. `inputs` maps sub-block ids directly to values, never through `subBlocks`. Keep `retry`, `triggerMode`, and `advancedMode` beside `inputs`. `connections` maps source handles to target ids, `{ block, handle }`, or arrays; `success` aliases `source`." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "extract_from_subflow", "description": "Move a block out of its loop or parallel container." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "type": "object", "properties": { "subflowId": { "type": "string", "minLength": 1, "description": "Loop or parallel container the block moves into or out of." } }, "required": [ "subflowId" ], "additionalProperties": { "description": "One block-specific input." }, "description": "Container identifier, plus any block-specific inputs." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false } ], "title": "Workflow edit operation", "description": "One semantic edit against a workflow graph." }, "description": "Edits to apply, in a single batch." }, "atomic": { "default": false, "description": "Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead.", "type": "boolean" }, "layout": { "default": "targeted", "description": "Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied.", "type": "string", "enum": [ "targeted", "none" ] }, "setBlockEnabled": { "description": "Blocks to enable or disable, applied after `operations`. Disabling a loop or parallel cascades to its unlocked descendants; enabling a block whose container is disabled is declined.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "enabled": { "type": "boolean", "description": "Whether the block should run." } }, "required": [ "block_id", "enabled" ], "additionalProperties": false } } }, "required": [ "operations" ], "additionalProperties": false, "title": "Apply workflow operations request", "description": "A batch of semantic edits against a workflow graph.", "examples": [ { "operations": [ { "operation_type": "add", "block_id": "agent-1", "params": { "type": "agent", "name": "Triage", "inputs": { "tools": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] } } } ] } ] }, "examples": { "example1": { "summary": "Request example 1", "value": { "operations": [ { "operation_type": "add", "block_id": "agent-1", "params": { "type": "agent", "name": "Triage", "inputs": { "tools": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] } } } ] } } } } } } ``` ## Responses ### 200 ```json { "description": "The batch was applied.", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the workflow whose draft graph was written." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal notes about blocks and edges that were normalized or dropped before persistence and, when `lint` has findings, one line counting them by category, so a caller that reads only `warnings` still learns they exist. The findings themselves are in `lint`. Empty when there is nothing to report." }, "needsRedeployment": { "type": "boolean", "description": "Whether the live deployment differs from the draft. A graph write never changes what the deployed endpoint serves; deploy to publish it. On a dry run, this describes the state before the proposed write." }, "applied": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Operations the engine applied." }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "block_not_found", "invalid_block_type", "block_not_allowed", "model_not_allowed", "block_locked", "tool_not_allowed", "invalid_edge_target", "invalid_edge_source", "invalid_edge_scope", "invalid_source_handle", "invalid_target_handle", "invalid_subblock_field", "missing_required_params", "invalid_subflow_parent", "nested_subflow_not_allowed", "duplicate_block_name", "reserved_block_name", "retry_not_supported", "duplicate_trigger", "duplicate_single_instance_block", "disabled_ancestor" ], "description": "Machine-readable reason the engine declined an operation." }, "operationType": { "type": "string", "description": "The `operation_type` that was declined." }, "blockId": { "type": "string", "description": "Block the declined operation targeted." }, "reason": { "type": "string", "description": "Human-readable explanation." }, "details": { "description": "Additional context for the reason; keys depend on `type`.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One piece of engine-supplied context for the reason." } } }, "required": [ "type", "operationType", "blockId", "reason" ], "additionalProperties": false, "title": "Workflow skipped item", "description": "One operation the edit engine did not apply." }, "description": "Operations the engine declined. Empty when everything applied." }, "deferred": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "block_not_found", "invalid_block_type", "block_not_allowed", "model_not_allowed", "block_locked", "tool_not_allowed", "invalid_edge_target", "invalid_edge_source", "invalid_edge_scope", "invalid_source_handle", "invalid_target_handle", "invalid_subblock_field", "missing_required_params", "invalid_subflow_parent", "nested_subflow_not_allowed", "duplicate_block_name", "reserved_block_name", "retry_not_supported", "duplicate_trigger", "duplicate_single_instance_block", "disabled_ancestor" ], "description": "Machine-readable reason the engine declined an operation." }, "operationType": { "type": "string", "description": "The `operation_type` that was declined." }, "blockId": { "type": "string", "description": "Block the declined operation targeted." }, "reason": { "type": "string", "description": "Human-readable explanation." }, "details": { "description": "Additional context for the reason; keys depend on `type`.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One piece of engine-supplied context for the reason." } } }, "required": [ "type", "operationType", "blockId", "reason" ], "additionalProperties": false, "title": "Workflow skipped item", "description": "One operation the edit engine did not apply." }, "description": "Edges waiting for target blocks. They apply automatically when their targets exist, in this batch or a later one. Do not resubmit them." }, "inputValidationErrors": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block whose input was rejected." }, "blockType": { "type": "string", "description": "Type of the block whose input was rejected." }, "field": { "type": "string", "description": "Sub-block field that was rejected." }, "error": { "type": "string", "description": "Why the value was rejected." } }, "required": [ "blockId", "blockType", "field", "error" ], "additionalProperties": false, "title": "Workflow input validation error", "description": "One block input that was dropped rather than persisted." }, "description": "Block inputs that were dropped rather than persisted, and only those. The rest of the operation still applied. References that merely fail to resolve stay persisted and are reported in `lint.unresolvedReferences` instead." }, "mintedBlockIds": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "description": "The id the block was actually given." }, "description": "Assigned IDs keyed by requested `block_id`, including only changed IDs. `add` and `insert_into_subflow` replace non-UUID labels with minted UUIDs. References within the batch are remapped automatically; later requests must use the minted IDs. Supply UUIDs to preserve your chosen IDs. Empty on dry runs, which return provisional IDs in `previewBlockIds` instead." }, "previewBlockIds": { "description": "Dry run only: the provisional id the evaluation assigned to each block whose `block_id` was not already a UUID, keyed by the `block_id` you asked for. These are not the ids a committed apply produces — the real apply mints new ones — so never wire a later request against them. Wire edges by `block_id` within one batch, or by the `mintedBlockIds` the real apply returns.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "description": "The provisional id the dry run assigned." } }, "lint": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." } }, "required": [ "blockId", "blockName", "blockType" ], "additionalProperties": false }, "description": "Blocks with no incoming edge. A trigger block is naturally a source; anything else here is unreachable." }, "sinks": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." } }, "required": [ "blockId", "blockName", "blockType" ], "additionalProperties": false }, "description": "Blocks with no outgoing edge." }, "orphanBlocks": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." } }, "required": [ "blockId", "blockName", "blockType" ], "additionalProperties": false }, "description": "Blocks with neither an incoming nor an outgoing edge." }, "emptyOutgoingPorts": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "handle": { "type": "string", "description": "Source handle with nothing connected to it." }, "label": { "type": "string", "description": "Human-readable name of the port." } }, "required": [ "blockId", "blockName", "blockType", "handle", "label" ], "additionalProperties": false }, "description": "Branch and container ports that lead nowhere." }, "invalidBranchPorts": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "sourceHandle": { "type": "string", "description": "Source handle that does not match the block." }, "reason": { "type": "string", "description": "Why the handle is not valid for this block." } }, "required": [ "blockId", "blockName", "blockType", "sourceHandle", "reason" ], "additionalProperties": false }, "description": "Condition and router edges whose source handle names no real branch." }, "invalidConnectionTargets": { "type": "array", "items": { "type": "object", "properties": { "sourceBlockId": { "type": "string", "description": "Block the edge leaves." }, "sourceBlockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the source block." }, "sourceHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle the edge leaves from." }, "targetBlockId": { "type": "string", "description": "Block the edge points at." }, "reason": { "type": "string", "description": "Why the target is not a legal destination." } }, "required": [ "sourceBlockId", "sourceBlockName", "sourceHandle", "targetBlockId", "reason" ], "additionalProperties": false }, "description": "Edges pointing at a block that cannot legally receive them." }, "fieldIssues": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "missingRequiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required sub-block fields that resolve empty in the active mode." }, "inactiveModeValues": { "type": "array", "items": { "type": "object", "properties": { "canonicalId": { "type": "string", "description": "Canonical parameter the two sub-block modes share." }, "activeMemberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sub-block the runtime reads, where the value should live." }, "inactiveMemberId": { "type": "string", "description": "Sub-block holding the stranded value, which the runtime ignores." }, "kind": { "type": "string", "enum": [ "credential", "resource", "other" ], "description": "What kind of value is stranded." } }, "required": [ "canonicalId", "activeMemberId", "inactiveMemberId", "kind" ], "additionalProperties": false }, "description": "Values stranded on the inactive member of a canonical pair." } }, "required": [ "blockId", "blockName", "blockType", "missingRequiredFields", "inactiveModeValues" ], "additionalProperties": false }, "description": "Per-block configuration problems. The most actionable part of the report for a headless graph builder: a block missing a required field will fail at run time." }, "unresolvedReferences": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "field": { "type": "string", "description": "Sub-block field holding the reference." }, "value": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "The reference, or references, that did not resolve." }, "kind": { "type": "string", "enum": [ "credential", "resource", "custom-tool", "mcp-tool", "skill", "block-output" ], "description": "What kind of entity the reference was expected to name." }, "reason": { "type": "string", "description": "Why the reference does not resolve." } }, "required": [ "blockId", "blockName", "blockType", "field", "value", "kind", "reason" ], "additionalProperties": false }, "description": "Credential, resource, tool, and skill references that do not resolve; `block-output` references that will not work as written: a block that does not exist, or an output field the block does not have (reason `unknown-field`); and text outputs written unquoted in a JSON field (reason `unquoted-json-string`), which leave the field invalid JSON at run time unless the text is itself JSON. These values are still persisted; they are reported, not dropped." }, "tableFieldIssues": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "field": { "type": "string", "description": "The filter or sort field that names no column." }, "tableName": { "type": "string", "description": "Display name of the table the block is bound to." } }, "required": [ "blockId", "blockName", "blockType", "field", "tableName" ], "additionalProperties": false }, "description": "Table block `filter` and `order` fields checked against the bound table's live schema that name no column (nor the implicit `id`, `createdAt`, `updatedAt`). Such a run fails inside the block's error edge. A filter holding a `` reference, or one that is not JSON, is not checked." }, "manualRunIssue": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "no-trigger", "multiple-api-triggers", "trigger-not-connected" ], "description": "Why the run is refused." }, "message": { "type": "string", "description": "The error the manual run raises." }, "blockId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Trigger the run would start from, when the problem is that trigger." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of that trigger." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of that trigger." } }, "required": [ "reason", "message", "blockId", "blockName", "blockType" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why a manual run from the editor's Run button would be refused before it starts: no enabled trigger it can start from, more than one API trigger, or a selected trigger with no outgoing connection. The API run endpoints do not apply these checks. `null` when no manual-run issue is reported: the run can begin, only a chat trigger can start the workflow, or the graph is empty (reported in `notes` instead)." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Advisory notes about the report itself." } }, "required": [ "sources", "sinks", "orphanBlocks", "emptyOutgoingPorts", "invalidBranchPorts", "invalidConnectionTargets", "fieldIssues", "unresolvedReferences", "tableFieldIssues", "manualRunIssue", "notes" ], "additionalProperties": false, "title": "Workflow lint report", "description": "Advisory findings about a saved graph. Findings never block a write or a deploy; they tell a caller what will misbehave at run time." }, "dryRun": { "type": "boolean", "description": "Whether this request only evaluated. `true` means nothing was persisted; the outcome describes what a committed apply of the same body would produce." } }, "required": [ "id", "warnings", "needsRedeployment", "applied", "skipped", "deferred", "inputValidationErrors", "mintedBlockIds", "lint", "dryRun" ], "additionalProperties": false, "title": "Apply workflow operations result", "description": "Response data." } }, "required": [ "data" ], "additionalProperties": false, "title": "Apply workflow operations response", "description": "Outcome of a batch of semantic edits.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "applied": 1, "skipped": [], "deferred": [], "inputValidationErrors": [], "mintedBlockIds": { "agent-1": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77" }, "lint": { "sources": [ { "blockId": "start-1", "blockName": "Start", "blockType": "start_trigger" } ], "sinks": [ { "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77", "blockName": "Triage", "blockType": "agent" } ], "orphanBlocks": [], "emptyOutgoingPorts": [], "invalidBranchPorts": [], "invalidConnectionTargets": [], "fieldIssues": [ { "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77", "blockName": "Triage", "blockType": "agent", "missingRequiredFields": [ "systemPrompt" ], "inactiveModeValues": [] } ], "unresolvedReferences": [], "tableFieldIssues": [], "manualRunIssue": null, "notes": [] }, "warnings": [ "Workflow lint found issues (Blocks missing required fields: 1). The findings are in `lint`." ], "needsRedeployment": true, "dryRun": false } } ] }, "examples": { "example1": { "summary": "Response example 1", "value": { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "applied": 1, "skipped": [], "deferred": [], "inputValidationErrors": [], "mintedBlockIds": { "agent-1": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77" }, "lint": { "sources": [ { "blockId": "start-1", "blockName": "Start", "blockType": "start_trigger" } ], "sinks": [ { "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77", "blockName": "Triage", "blockType": "agent" } ], "orphanBlocks": [], "emptyOutgoingPorts": [], "invalidBranchPorts": [], "invalidConnectionTargets": [], "fieldIssues": [ { "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77", "blockName": "Triage", "blockType": "agent", "missingRequiredFields": [ "systemPrompt" ], "inactiveModeValues": [] } ], "unresolvedReferences": [], "tableFieldIssues": [], "manualRunIssue": null, "notes": [] }, "warnings": [ "Workflow lint found issues (Blocks missing required fields: 1). The findings are in `lint`." ], "needsRedeployment": true, "dryRun": false } } } } } } } ``` ### 400 ```json { "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } } ``` ### 401 ```json { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } } ``` ### 403 ```json { "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } } ``` ### 404 ```json { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } } ``` ### 409 ```json { "description": "The request conflicts with current resource state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with current resource state" } } } } } ``` ### 413 ```json { "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "Request body is too large" } } } } } ``` ### 415 ```json { "description": "The request uses an unsupported media type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Request body must be sent as application/json" } } } } } ``` ### 423 ```json { "description": "The resource is temporarily locked or unavailable; retry the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "LOCKED", "message": "Workflow is locked" } } } } } ``` ### 429 ```json { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } } ``` ### 500 ```json { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } ``` ### 503 ```json { "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } ``` ## Referenced schemas The following definitions preserve recursive references and composition exactly. ```json { "#/components/schemas/ApplyWorkflowOperationsRequest": { "type": "object", "properties": { "operations": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEditOperation" }, "description": "Edits to apply, in a single batch." }, "atomic": { "default": false, "description": "Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead.", "type": "boolean" }, "layout": { "default": "targeted", "description": "Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied.", "type": "string", "enum": [ "targeted", "none" ] }, "setBlockEnabled": { "description": "Blocks to enable or disable, applied after `operations`. Disabling a loop or parallel cascades to its unlocked descendants; enabling a block whose container is disabled is declined.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "enabled": { "type": "boolean", "description": "Whether the block should run." } }, "required": [ "block_id", "enabled" ], "additionalProperties": false } } }, "required": [ "operations" ], "additionalProperties": false, "title": "Apply workflow operations request", "description": "A batch of semantic edits against a workflow graph.", "examples": [ { "operations": [ { "operation_type": "add", "block_id": "agent-1", "params": { "type": "agent", "name": "Triage", "inputs": { "tools": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] } } } ] } ] }, "#/components/schemas/WorkflowEditOperation": { "oneOf": [ { "type": "object", "properties": { "operation_type": { "type": "string", "const": "add", "description": "Create a new block." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "description": "Registered block type." }, "name": { "type": "string", "minLength": 1, "description": "Block display name." }, "inputs": { "allOf": [ { "type": "object", "properties": { "tools": { "description": "Agent tools configuration. Applies to a `tool-input` field; other block inputs remain catalog-defined.", "$ref": "#/components/schemas/AgentToolInput" } }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } } ], "description": "Block configuration keyed by sub-block id." } }, "required": [ "type", "name" ], "additionalProperties": { "description": "One block-specific input or connection descriptor." }, "description": "Block `type`, `name`, and optional `inputs`, `connections`, `retry`, `triggerMode`, or `advancedMode`. `inputs` maps sub-block ids directly to values, never through `subBlocks`. Keep `retry`, `triggerMode`, and `advancedMode` beside `inputs`. `connections` maps source handles to target ids, `{ block, handle }`, or arrays; `success` aliases `source`." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "edit", "description": "Change an existing block: its inputs, name, or connections." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "allOf": [ { "type": "object", "properties": { "inputs": { "allOf": [ { "type": "object", "properties": { "tools": { "description": "Agent tools configuration. Applies to a `tool-input` field; other block inputs remain catalog-defined.", "$ref": "#/components/schemas/AgentToolInput" } }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } } ], "description": "Block configuration keyed by sub-block id." } }, "additionalProperties": { "description": "One operation parameter; see the description for the accepted keys." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One operation parameter; see the description for the accepted keys." } } ], "description": "Patch only supplied fields: `inputs`, `name`, `connections`, `removeEdges`, `nestedNodes`, `retry`, `triggerMode`, and `advancedMode`. `inputs` maps sub-block ids directly to values, never through `subBlocks`. Keep `retry`, `triggerMode`, and `advancedMode` beside `inputs`. `connections` maps source handles to target ids, `{ block, handle }`, or arrays; `success` aliases `source`. Re-sending `connections` replaces outgoing edges; use `removeEdges` to delete selected edges." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "delete", "description": "Remove a block and every edge touching it." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." } }, "required": [ "operation_type", "block_id" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "insert_into_subflow", "description": "Create a block inside a loop or parallel container." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "type": "object", "properties": { "subflowId": { "type": "string", "minLength": 1, "description": "Loop or parallel container to insert the block into." }, "type": { "type": "string", "minLength": 1, "description": "Registered block type." }, "name": { "type": "string", "minLength": 1, "description": "Block display name." }, "inputs": { "allOf": [ { "type": "object", "properties": { "tools": { "description": "Agent tools configuration. Applies to a `tool-input` field; other block inputs remain catalog-defined.", "$ref": "#/components/schemas/AgentToolInput" } }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One block-specific input whose accepted shape is published by the block catalog." } } ], "description": "Block configuration keyed by sub-block id." } }, "required": [ "subflowId", "type", "name" ], "additionalProperties": { "description": "One block-specific input or connection descriptor." }, "description": "Container, block `type`, `name`, and the same optional fields as `add`. `inputs` maps sub-block ids directly to values, never through `subBlocks`. Keep `retry`, `triggerMode`, and `advancedMode` beside `inputs`. `connections` maps source handles to target ids, `{ block, handle }`, or arrays; `success` aliases `source`." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_type": { "type": "string", "const": "extract_from_subflow", "description": "Move a block out of its loop or parallel container." }, "block_id": { "type": "string", "minLength": 1, "description": "Block the operation targets. For `add`, the id the new block will be given." }, "params": { "type": "object", "properties": { "subflowId": { "type": "string", "minLength": 1, "description": "Loop or parallel container the block moves into or out of." } }, "required": [ "subflowId" ], "additionalProperties": { "description": "One block-specific input." }, "description": "Container identifier, plus any block-specific inputs." } }, "required": [ "operation_type", "block_id", "params" ], "additionalProperties": false } ], "title": "Workflow edit operation", "description": "One semantic edit against a workflow graph." }, "#/components/schemas/AgentToolInput": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/AgentTool" }, "description": "Agent tools configuration. Applies to a `tool-input` field; other block inputs remain catalog-defined.", "title": "Agent tools input" }, "#/components/schemas/AgentTool": { "oneOf": [ { "$ref": "#/components/schemas/AgentIntegrationTool" }, { "$ref": "#/components/schemas/AgentCustomTool" }, { "$ref": "#/components/schemas/AgentMcpTool" }, { "$ref": "#/components/schemas/AgentMcpServerAdvanced" } ], "title": "Agent tool", "description": "A catalog integration operation, workspace custom tool, or MCP tool available to an Agent." }, "#/components/schemas/AgentIntegrationTool": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(?!(?:custom-tool|mcp|mcp-server-advanced)$).+$", "description": "Catalog block id, such as `cloudwatch` or `slack`. Use the block id, never an underlying tool id." }, "operation": { "description": "Operation ID from Get Block. Required when the block exposes multiple operations; it may differ from the tool ID.", "type": "string", "minLength": 1, "maxLength": 255 }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One tool parameter value." }, "description": "Parameters fixed by the workflow author. Parameters left out remain available for the model to supply when the tool declares them." } }, "required": [ "type" ], "additionalProperties": { "description": "Forward-compatible integration tool metadata preserved by the workflow editor." }, "title": "Agent integration tool", "description": "A catalog integration operation the Agent may call. Resolve valid block and operation ids through the block catalog.", "examples": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] }, "#/components/schemas/AgentCustomTool": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "customToolId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Custom tool ID from List Custom Tools." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "customToolId" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } }, { "type": "object", "properties": { "type": { "type": "string", "const": "custom-tool", "description": "Custom-tool discriminator." }, "schema": { "type": "object", "properties": { "type": { "description": "Function declaration discriminator.", "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Function name presented to the model." }, "description": { "description": "What the inline custom tool does.", "type": "string" }, "parameters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One JSON Schema keyword on the function parameters." }, "description": "JSON Schema describing the function arguments." } }, "required": [ "name", "parameters" ], "additionalProperties": { "description": "Additional function declaration metadata." }, "description": "OpenAI-style function definition." } }, "required": [ "function" ], "additionalProperties": { "description": "Additional custom tool declaration metadata." }, "description": "Inline OpenAI-style function declaration." }, "code": { "type": "string", "description": "Inline tool implementation executed by the Function runtime." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "schema", "code" ], "additionalProperties": { "description": "Forward-compatible custom tool metadata preserved by the workflow editor." } } ], "title": "Agent custom tool", "description": "A workspace custom tool. Prefer `customToolId`; inline declarations are also accepted.", "examples": [ { "type": "custom-tool", "customToolId": "cst_01J9X2ABCDEF", "usageControl": "auto" } ] }, "#/components/schemas/AgentMcpTool": { "type": "object", "properties": { "type": { "type": "string", "const": "mcp", "description": "MCP-tool discriminator." }, "params": { "allOf": [ { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "MCP server id returned by `GET /api/v2/mcp-servers`." }, "toolName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name returned by the MCP server’s tools endpoint." } }, "required": [ "serverId", "toolName" ], "additionalProperties": { "description": "One parameter fixed by the workflow author." } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One parameter fixed by the workflow author." } } ], "description": "MCP server and tool identity plus any tool arguments fixed by the workflow author." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP tool metadata preserved by the workflow editor." }, "title": "Agent MCP tool", "description": "One tool discovered from a workspace MCP server.", "examples": [ { "type": "mcp", "params": { "serverId": "mcp_01J9X2ABCDEF", "toolName": "search_docs" }, "usageControl": "auto" } ] }, "#/components/schemas/AgentMcpServerAdvanced": { "type": "object", "properties": { "type": { "type": "string", "const": "mcp-server-advanced", "description": "Server-wide MCP binding discriminator." }, "operationPolicy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Allow all operations available to the authorized credential." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "allow", "description": "Allow only the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Allowed exact MCP tool names; an empty list grants no access." } }, "required": [ "mode", "operations" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "deny", "description": "Exclude the selected exact operations." }, "operations": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact MCP tool name on the resolved connection, without a Sim server prefix." }, "description": "Denied exact MCP tool names; an empty list allows otherwise permitted tools." } }, "required": [ "mode", "operations" ], "additionalProperties": false } ], "description": "Saved workflow operation restrictions that can only narrow authorized credential access." }, "params": { "type": "object", "properties": { "serverId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Workspace MCP server ID or explicit credential-group managed MCP connection ID." } }, "required": [ "serverId" ], "additionalProperties": false, "description": "Executable server or connection identity for authorized operation discovery and execution." }, "usageControl": { "type": "string", "enum": [ "auto", "force", "none" ], "description": "Selector Permission Mode: `auto` lets the model decide, `force` requires a call, and `none` disables it. Supply this property and omit `usageControlExpression` to select or switch to Selector mode; do not send null or set `canonicalModes` or block-level `advancedMode`. With neither property, the default is `auto`." }, "usageControlExpression": { "type": "string", "maxLength": 2048, "description": "Variable Permission Mode: a reference such as `` or a literal such as `none`, resolving to `auto`, `force`, or `none` at execution time. Supply this property and omit `usageControl` to select or switch to Variable mode; do not send null or set `canonicalModes` or block-level `advancedMode`." } }, "required": [ "type", "params" ], "additionalProperties": { "description": "Forward-compatible MCP server metadata preserved by the workflow editor." }, "title": "Agent MCP server (advanced)", "description": "Dynamically discovered operations permitted by the authorized credential and saved block policy.", "examples": [ { "type": "mcp-server-advanced", "params": { "serverId": "mcp_01J9X2ABCDEF" }, "usageControl": "auto" } ] }, "#/components/headers/X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "#/components/headers/X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "#/components/headers/X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } }, "#/components/schemas/ApplyWorkflowOperationsResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/ApplyWorkflowOperationsResult" } }, "required": [ "data" ], "additionalProperties": false, "title": "Apply workflow operations response", "description": "Outcome of a batch of semantic edits.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "applied": 1, "skipped": [], "deferred": [], "inputValidationErrors": [], "mintedBlockIds": { "agent-1": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77" }, "lint": { "sources": [ { "blockId": "start-1", "blockName": "Start", "blockType": "start_trigger" } ], "sinks": [ { "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77", "blockName": "Triage", "blockType": "agent" } ], "orphanBlocks": [], "emptyOutgoingPorts": [], "invalidBranchPorts": [], "invalidConnectionTargets": [], "fieldIssues": [ { "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77", "blockName": "Triage", "blockType": "agent", "missingRequiredFields": [ "systemPrompt" ], "inactiveModeValues": [] } ], "unresolvedReferences": [], "tableFieldIssues": [], "manualRunIssue": null, "notes": [] }, "warnings": [ "Workflow lint found issues (Blocks missing required fields: 1). The findings are in `lint`." ], "needsRedeployment": true, "dryRun": false } } ] }, "#/components/schemas/ApplyWorkflowOperationsResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the workflow whose draft graph was written." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal notes about blocks and edges that were normalized or dropped before persistence and, when `lint` has findings, one line counting them by category, so a caller that reads only `warnings` still learns they exist. The findings themselves are in `lint`. Empty when there is nothing to report." }, "needsRedeployment": { "type": "boolean", "description": "Whether the live deployment differs from the draft. A graph write never changes what the deployed endpoint serves; deploy to publish it. On a dry run, this describes the state before the proposed write." }, "applied": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Operations the engine applied." }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowSkippedItem" }, "description": "Operations the engine declined. Empty when everything applied." }, "deferred": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowSkippedItem" }, "description": "Edges waiting for target blocks. They apply automatically when their targets exist, in this batch or a later one. Do not resubmit them." }, "inputValidationErrors": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowInputValidationError" }, "description": "Block inputs that were dropped rather than persisted, and only those. The rest of the operation still applied. References that merely fail to resolve stay persisted and are reported in `lint.unresolvedReferences` instead." }, "mintedBlockIds": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "description": "The id the block was actually given." }, "description": "Assigned IDs keyed by requested `block_id`, including only changed IDs. `add` and `insert_into_subflow` replace non-UUID labels with minted UUIDs. References within the batch are remapped automatically; later requests must use the minted IDs. Supply UUIDs to preserve your chosen IDs. Empty on dry runs, which return provisional IDs in `previewBlockIds` instead." }, "previewBlockIds": { "description": "Dry run only: the provisional id the evaluation assigned to each block whose `block_id` was not already a UUID, keyed by the `block_id` you asked for. These are not the ids a committed apply produces — the real apply mints new ones — so never wire a later request against them. Wire edges by `block_id` within one batch, or by the `mintedBlockIds` the real apply returns.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "description": "The provisional id the dry run assigned." } }, "lint": { "$ref": "#/components/schemas/WorkflowLintReport" }, "dryRun": { "type": "boolean", "description": "Whether this request only evaluated. `true` means nothing was persisted; the outcome describes what a committed apply of the same body would produce." } }, "required": [ "id", "warnings", "needsRedeployment", "applied", "skipped", "deferred", "inputValidationErrors", "mintedBlockIds", "lint", "dryRun" ], "additionalProperties": false, "title": "Apply workflow operations result", "description": "Response data." }, "#/components/schemas/WorkflowSkippedItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "block_not_found", "invalid_block_type", "block_not_allowed", "model_not_allowed", "block_locked", "tool_not_allowed", "invalid_edge_target", "invalid_edge_source", "invalid_edge_scope", "invalid_source_handle", "invalid_target_handle", "invalid_subblock_field", "missing_required_params", "invalid_subflow_parent", "nested_subflow_not_allowed", "duplicate_block_name", "reserved_block_name", "retry_not_supported", "duplicate_trigger", "duplicate_single_instance_block", "disabled_ancestor" ], "description": "Machine-readable reason the engine declined an operation." }, "operationType": { "type": "string", "description": "The `operation_type` that was declined." }, "blockId": { "type": "string", "description": "Block the declined operation targeted." }, "reason": { "type": "string", "description": "Human-readable explanation." }, "details": { "description": "Additional context for the reason; keys depend on `type`.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "One piece of engine-supplied context for the reason." } } }, "required": [ "type", "operationType", "blockId", "reason" ], "additionalProperties": false, "title": "Workflow skipped item", "description": "One operation the edit engine did not apply." }, "#/components/schemas/WorkflowInputValidationError": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block whose input was rejected." }, "blockType": { "type": "string", "description": "Type of the block whose input was rejected." }, "field": { "type": "string", "description": "Sub-block field that was rejected." }, "error": { "type": "string", "description": "Why the value was rejected." } }, "required": [ "blockId", "blockType", "field", "error" ], "additionalProperties": false, "title": "Workflow input validation error", "description": "One block input that was dropped rather than persisted." }, "#/components/schemas/WorkflowLintReport": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." } }, "required": [ "blockId", "blockName", "blockType" ], "additionalProperties": false }, "description": "Blocks with no incoming edge. A trigger block is naturally a source; anything else here is unreachable." }, "sinks": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." } }, "required": [ "blockId", "blockName", "blockType" ], "additionalProperties": false }, "description": "Blocks with no outgoing edge." }, "orphanBlocks": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." } }, "required": [ "blockId", "blockName", "blockType" ], "additionalProperties": false }, "description": "Blocks with neither an incoming nor an outgoing edge." }, "emptyOutgoingPorts": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "handle": { "type": "string", "description": "Source handle with nothing connected to it." }, "label": { "type": "string", "description": "Human-readable name of the port." } }, "required": [ "blockId", "blockName", "blockType", "handle", "label" ], "additionalProperties": false }, "description": "Branch and container ports that lead nowhere." }, "invalidBranchPorts": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "sourceHandle": { "type": "string", "description": "Source handle that does not match the block." }, "reason": { "type": "string", "description": "Why the handle is not valid for this block." } }, "required": [ "blockId", "blockName", "blockType", "sourceHandle", "reason" ], "additionalProperties": false }, "description": "Condition and router edges whose source handle names no real branch." }, "invalidConnectionTargets": { "type": "array", "items": { "type": "object", "properties": { "sourceBlockId": { "type": "string", "description": "Block the edge leaves." }, "sourceBlockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the source block." }, "sourceHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle the edge leaves from." }, "targetBlockId": { "type": "string", "description": "Block the edge points at." }, "reason": { "type": "string", "description": "Why the target is not a legal destination." } }, "required": [ "sourceBlockId", "sourceBlockName", "sourceHandle", "targetBlockId", "reason" ], "additionalProperties": false }, "description": "Edges pointing at a block that cannot legally receive them." }, "fieldIssues": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "missingRequiredFields": { "type": "array", "items": { "type": "string" }, "description": "Required sub-block fields that resolve empty in the active mode." }, "inactiveModeValues": { "type": "array", "items": { "type": "object", "properties": { "canonicalId": { "type": "string", "description": "Canonical parameter the two sub-block modes share." }, "activeMemberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sub-block the runtime reads, where the value should live." }, "inactiveMemberId": { "type": "string", "description": "Sub-block holding the stranded value, which the runtime ignores." }, "kind": { "type": "string", "enum": [ "credential", "resource", "other" ], "description": "What kind of value is stranded." } }, "required": [ "canonicalId", "activeMemberId", "inactiveMemberId", "kind" ], "additionalProperties": false }, "description": "Values stranded on the inactive member of a canonical pair." } }, "required": [ "blockId", "blockName", "blockType", "missingRequiredFields", "inactiveModeValues" ], "additionalProperties": false }, "description": "Per-block configuration problems. The most actionable part of the report for a headless graph builder: a block missing a required field will fail at run time." }, "unresolvedReferences": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "field": { "type": "string", "description": "Sub-block field holding the reference." }, "value": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "The reference, or references, that did not resolve." }, "kind": { "type": "string", "enum": [ "credential", "resource", "custom-tool", "mcp-tool", "skill", "block-output" ], "description": "What kind of entity the reference was expected to name." }, "reason": { "type": "string", "description": "Why the reference does not resolve." } }, "required": [ "blockId", "blockName", "blockType", "field", "value", "kind", "reason" ], "additionalProperties": false }, "description": "Credential, resource, tool, and skill references that do not resolve; `block-output` references that will not work as written: a block that does not exist, or an output field the block does not have (reason `unknown-field`); and text outputs written unquoted in a JSON field (reason `unquoted-json-string`), which leave the field invalid JSON at run time unless the text is itself JSON. These values are still persisted; they are reported, not dropped." }, "tableFieldIssues": { "type": "array", "items": { "type": "object", "properties": { "blockId": { "type": "string", "description": "Block the finding is about." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the block, when it has one." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of the block, when it has one." }, "field": { "type": "string", "description": "The filter or sort field that names no column." }, "tableName": { "type": "string", "description": "Display name of the table the block is bound to." } }, "required": [ "blockId", "blockName", "blockType", "field", "tableName" ], "additionalProperties": false }, "description": "Table block `filter` and `order` fields checked against the bound table's live schema that name no column (nor the implicit `id`, `createdAt`, `updatedAt`). Such a run fails inside the block's error edge. A filter holding a `` reference, or one that is not JSON, is not checked." }, "manualRunIssue": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "no-trigger", "multiple-api-triggers", "trigger-not-connected" ], "description": "Why the run is refused." }, "message": { "type": "string", "description": "The error the manual run raises." }, "blockId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Trigger the run would start from, when the problem is that trigger." }, "blockName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of that trigger." }, "blockType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Registered type of that trigger." } }, "required": [ "reason", "message", "blockId", "blockName", "blockType" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why a manual run from the editor's Run button would be refused before it starts: no enabled trigger it can start from, more than one API trigger, or a selected trigger with no outgoing connection. The API run endpoints do not apply these checks. `null` when no manual-run issue is reported: the run can begin, only a chat trigger can start the workflow, or the graph is empty (reported in `notes` instead)." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Advisory notes about the report itself." } }, "required": [ "sources", "sinks", "orphanBlocks", "emptyOutgoingPorts", "invalidBranchPorts", "invalidConnectionTargets", "fieldIssues", "unresolvedReferences", "tableFieldIssues", "manualRunIssue", "notes" ], "additionalProperties": false, "title": "Workflow lint report", "description": "Advisory findings about a saved graph. Findings never block a write or a deploy; they tell a caller what will misbehave at run time." }, "#/components/responses/BadRequest": { "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "#/components/schemas/V2Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.", "anyOf": [ { "$ref": "#/components/schemas/V2ActionableForbiddenDetails" }, { "description": "Other structured context defined by the specific error." } ] } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Canonical error details." } }, "required": [ "error" ], "additionalProperties": false, "title": "v2 error response", "description": "Canonical error envelope returned by the public v2 API.", "examples": [ { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } ] }, "#/components/schemas/V2ActionableForbiddenDetails": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/V2ForbiddenDetailCode" } }, "required": [ "code" ], "additionalProperties": { "description": "Additional context for this refusal." }, "title": "Actionable forbidden details", "description": "Machine-readable cause and optional context for an actionable `403` response." }, "#/components/schemas/V2ForbiddenDetailCode": { "type": "string", "enum": [ "INSUFFICIENT_WORKSPACE_ROLE", "PERSONAL_API_KEYS_DISABLED", "WORKSPACE_KEY_OPERATION_NOT_PERMITTED", "PRINCIPAL_KIND_NOT_PERMITTED", "ORGANIZATION_MEMBERSHIP_REQUIRED", "ORGANIZATION_ADMIN_REQUIRED", "ENTERPRISE_PLAN_REQUIRED", "SSO_DISABLED", "SSO_DOMAIN_NOT_VERIFIED", "SSO_PROVIDER_LIMIT_REACHED", "ORGANIZATION_PLAN_REQUIRED", "AUDIT_LOGS_DISABLED", "ACCESS_REQUESTS_DISABLED", "ACCESS_REQUEST_ORGANIZATION_REQUIRED", "SKILL_EDITOR_ACCESS_REQUIRED", "SECRET_ADMIN_ACCESS_REQUIRED", "WORKSPACE_RESOURCE_LIMIT_REACHED", "PUBLIC_SHARING_NOT_ALLOWED", "CREDENTIAL_ADMIN_ACCESS_REQUIRED", "MCP_SERVER_URL_NOT_ALLOWED", "WORKSPACE_PLAN_CAPABILITY_REQUIRED", "CHAT_AUTH_MODE_NOT_PERMITTED", "CONNECTOR_MANAGED_RESOURCE_READ_ONLY", "PERMISSION_GROUP_CAPABILITY_BLOCKED", "INTEGRATION_NOT_ALLOWED", "INSUFFICIENT_SCOPE", "SCIM_MANAGED_MEMBERSHIP" ], "title": "Forbidden detail code", "description": "Stable cause code for an actionable `403` response." }, "#/components/responses/Unauthorized": { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } }, "#/components/responses/Forbidden": { "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } }, "#/components/responses/NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } }, "#/components/responses/Conflict": { "description": "The request conflicts with current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with current resource state" } } } } }, "#/components/responses/PayloadTooLarge": { "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "Request body is too large" } } } } }, "#/components/responses/UnsupportedMediaType": { "description": "The request uses an unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Request body must be sent as application/json" } } } } }, "#/components/responses/Locked": { "description": "The resource is temporarily locked or unavailable; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "LOCKED", "message": "Workflow is locked" } } } } }, "#/components/responses/RateLimited": { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } }, "#/components/headers/Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } }, "#/components/responses/InternalError": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } }, "#/components/responses/ServiceUnavailable": { "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } } ``` [Download OpenAPI specification](/openapi.json) Source: `openapi-v2-workflows.json`, operation `applyWorkflowOperations`.