{ "openapi": "3.1.0", "info": { "title": "Sim API v2 — Workflows", "description": "Version 2 of the Sim REST API for workflow management, deployment versions, execution, run lifecycle, folders, and portable import and export.", "version": "2.0.0", "contact": { "name": "Sim Support", "email": "help@sim.ai", "url": "https://www.sim.ai" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "https://www.sim.ai", "description": "Production" } ], "tags": [ { "name": "Workflows", "description": "Manage and execute workflow definitions, folders, deployment versions, and portable imports and exports." }, { "name": "Workflow Runs", "description": "Inspect, resume, and cancel workflow runs." } ], "security": [ { "apiKey": [] } ], "paths": { "/api/v2/workflows": { "get": { "operationId": "listWorkflows", "summary": "List Workflows", "description": "List workflows in a workspace with folder and deployment filters, search, sorting, and opaque cursor pagination.", "tags": ["Workflows"], "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "description": "Workspace whose workflows should be listed.", "schema": { "type": "string", "minLength": 1, "description": "Workspace whose workflows should be listed." } }, { "name": "folderPath", "in": "query", "required": false, "description": "Restrict results to workflows in this folder path.", "schema": { "description": "Restrict results to workflows in this folder path.", "type": "string" } }, { "name": "deployedOnly", "in": "query", "required": false, "description": "Return only workflows with an active deployment when true.", "schema": { "description": "Return only workflows with an active deployment when true.", "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum workflows to return per page.", "schema": { "default": 50, "description": "Maximum workflows to return per page.", "type": "number", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor returned by a previous request.", "schema": { "description": "Opaque pagination cursor returned by a previous request.", "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring search on the resource name.", "schema": { "description": "Case-insensitive substring search on the resource name.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field used to sort the result.", "schema": { "default": "position", "description": "Field used to sort the result.", "type": "string", "enum": ["position", "name", "createdAt", "updatedAt", "runCount"] } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "default": "asc", "description": "Sort direction.", "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "A page of workflows.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createWorkflowV2", "summary": "Create Workflow", "description": "Create a workflow in a workspace root or canonical workflow folder.", "tags": ["Workflows"], "requestBody": { "required": true, "description": "Name, description, workspace, and optional folder for a new workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowRequest" } } } }, "responses": { "201": { "description": "The created workflow.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}": { "get": { "operationId": "getWorkflow", "summary": "Get Workflow", "description": "Get a workflow with its variables and deployed API-trigger inputs.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } } ], "responses": { "200": { "description": "The requested workflow.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "operationId": "updateWorkflowV2", "summary": "Update Workflow", "description": "Rename, describe, or move a workflow to a canonical folder path.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } } ], "requestBody": { "required": true, "description": "Fields to update on an existing workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkflowRequest" } } } }, "responses": { "200": { "description": "The updated workflow.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteWorkflowV2", "summary": "Delete Workflow", "description": "Permanently delete a workflow and its associated mutable state.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } } ], "responses": { "200": { "description": "The workflow was deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/versions": { "get": { "operationId": "listWorkflowVersionsV2", "summary": "List Workflow Versions", "description": "List immutable deployment versions of a workflow, newest first.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum deployment versions to return per page.", "schema": { "default": 50, "description": "Maximum deployment versions to return per page.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor returned by a previous request.", "schema": { "description": "Opaque pagination cursor returned by a previous request.", "type": "string" } } ], "responses": { "200": { "description": "A page of deployment versions.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowVersionListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/versions/{version}": { "get": { "operationId": "getWorkflowVersionV2", "summary": "Get Workflow Version", "description": "Get an immutable deployment version and its pinned workflow graph snapshot.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier." } }, { "name": "version", "in": "path", "required": true, "description": "Numeric deployment version.", "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Numeric deployment version.", "examples": [3] } } ], "responses": { "200": { "description": "The requested deployment version.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowVersionDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/deploy": { "post": { "operationId": "deployWorkflow", "summary": "Deploy Workflow", "description": "Create and asynchronously activate a deployment version. Poll the workflow until the lifecycle attempt reaches a terminal state.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } } ], "requestBody": { "required": false, "description": "Optional metadata for the new deployment version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployWorkflowRequest" } } } }, "responses": { "200": { "description": "The accepted deployment attempt.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "undeployWorkflow", "summary": "Undeploy Workflow", "description": "Deactivate the currently serving workflow version.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } } ], "responses": { "200": { "description": "The workflow was undeployed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndeployWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/rollback": { "post": { "operationId": "rollbackWorkflow", "summary": "Rollback Workflow", "description": "Asynchronously reactivate a previous deployment version, selecting the preceding active version when no version is supplied.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } } ], "requestBody": { "required": false, "description": "Optional deployment version to reactivate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackWorkflowRequest" } } } }, "responses": { "200": { "description": "The accepted rollback attempt.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/export": { "get": { "operationId": "exportWorkflow", "summary": "Export Workflow", "description": "Export a portable, secret-sanitized workflow. Workspace-scoped bindings must be selected again after import.", "tags": ["Workflows"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } } ], "responses": { "200": { "description": "The workflow export payload.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/import": { "post": { "operationId": "importWorkflow", "summary": "Import Workflow", "description": "Create a workflow from a portable export object, bare state, or JSON string.", "tags": ["Workflows"], "requestBody": { "required": true, "description": "Portable workflow data and destination metadata for an import.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportWorkflowRequest" } } } }, "responses": { "201": { "description": "The imported workflow.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/execute": { "post": { "operationId": "executeWorkflowV2", "summary": "Execute Workflow", "description": "Execute a deployed workflow synchronously, asynchronously, or as Server-Sent Events. Public workflows permit anonymous synchronous and streaming execution; asynchronous execution requires an API key.", "tags": ["Workflows"], "security": [ { "apiKey": [] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } }, { "name": "x-run-id", "in": "header", "required": false, "description": "Caller-supplied run identifier. Available only to API-key callers.", "schema": { "description": "Caller-supplied run identifier. Available only to API-key callers.", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "examples": ["run_8f14e45f-ceea-467f-a"] } } ], "requestBody": { "required": true, "description": "Input and execution-mode options for a deployed workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteWorkflowRequest" } } } }, "responses": { "200": { "description": "A synchronous run result or Server-Sent Event stream.", "headers": { "X-Run-Id": { "$ref": "#/components/headers/X-Run-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteWorkflowSyncResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "202": { "description": "The asynchronous run was queued.", "headers": { "X-Run-Id": { "$ref": "#/components/headers/X-Run-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteWorkflowQueuedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/UsageLimitExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/RunIdConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/runs": { "get": { "operationId": "listWorkflowRunsV2", "summary": "List Workflow Runs", "description": "List recorded runs of a workflow with filtering and opaque cursor pagination.", "tags": ["Workflow Runs"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by run status.", "schema": { "description": "Filter by run status.", "type": "string", "enum": ["pending", "running", "completed", "failed", "cancelled", "paused"] } }, { "name": "trigger", "in": "query", "required": false, "description": "Filter by trigger type.", "schema": { "description": "Filter by trigger type.", "type": "string", "minLength": 1 } }, { "name": "startDate", "in": "query", "required": false, "description": "Include runs started at or after this ISO 8601 timestamp.", "schema": { "description": "Include runs started at or after this ISO 8601 timestamp.", "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))$" } }, { "name": "endDate", "in": "query", "required": false, "description": "Include runs started at or before this ISO 8601 timestamp.", "schema": { "description": "Include runs started at or before this ISO 8601 timestamp.", "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))$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum workflow runs to return per page.", "schema": { "default": 50, "description": "Maximum workflow runs to return per page.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor returned by a previous request.", "schema": { "description": "Opaque pagination cursor returned by a previous request.", "type": "string", "minLength": 1 } }, { "name": "order", "in": "query", "required": false, "description": "Sort order by run start time.", "schema": { "default": "desc", "description": "Sort order by run start time.", "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "A page of workflow runs.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/runs/{runId}": { "get": { "operationId": "getWorkflowRunV2", "summary": "Get Workflow Run", "description": "Get current workflow run state, optionally including final and block outputs.", "tags": ["Workflow Runs"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier." } }, { "name": "runId", "in": "path", "required": true, "description": "Unique workflow run identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] } }, { "name": "includeOutput", "in": "query", "required": false, "description": "Include final and block outputs when true.", "schema": { "description": "Include final and block outputs when true.", "type": "string", "enum": ["true", "false"] } }, { "name": "selectedOutputs", "in": "query", "required": false, "description": "Comma-separated block output references to include.", "schema": { "description": "Comma-separated block output references to include.", "type": "string" } } ], "responses": { "200": { "description": "The workflow run status.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/runs/{runId}/resume": { "post": { "operationId": "resumeWorkflowRunV2", "summary": "Resume Workflow Run", "description": "Resume one human-in-the-loop pause context. The resumed attempt receives a new run identifier and may complete synchronously or return a queue receipt.", "tags": ["Workflow Runs"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier." } }, { "name": "runId", "in": "path", "required": true, "description": "Unique workflow run identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] } } ], "requestBody": { "required": true, "description": "Pause context and optional input used to resume a workflow run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeWorkflowRequest" } } } }, "responses": { "200": { "description": "The resumed workflow attempt completed synchronously.", "headers": { "X-Run-Id": { "$ref": "#/components/headers/X-Run-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeWorkflowSyncResponse" } } } }, "202": { "description": "The resumed workflow attempt was queued.", "headers": { "X-Run-Id": { "$ref": "#/components/headers/X-Run-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeWorkflowQueuedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/UsageLimitExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/{id}/runs/{runId}/cancel": { "post": { "operationId": "cancelRunV2", "summary": "Cancel Workflow Run", "description": "Request cancellation of a running, queued, or paused workflow run.", "tags": ["Workflow Runs"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique workflow identifier.", "schema": { "type": "string", "minLength": 1, "description": "Unique workflow identifier." } }, { "name": "runId", "in": "path", "required": true, "description": "Unique workflow run identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] } } ], "responses": { "200": { "description": "The cancellation outcome.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelWorkflowRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/v2/workflows/folders": { "get": { "operationId": "listWorkflowsFolders", "summary": "List Workflow Folders", "description": "List canonical workflow folders in a workspace.", "tags": ["Workflows"], "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "description": "Workspace whose folders should be listed.", "schema": { "type": "string", "minLength": 1, "description": "Workspace whose folders should be listed." } }, { "name": "parentPath", "in": "query", "required": false, "description": "Restrict results to direct children of this parent path.", "schema": { "description": "Restrict results to direct children of this parent path.", "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match against the folder name.", "schema": { "description": "Case-insensitive substring match against the folder name.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field used to sort the result.", "schema": { "default": "name", "description": "Field used to sort the result.", "type": "string", "enum": ["name", "createdAt", "updatedAt"] } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction.", "schema": { "default": "asc", "description": "Sort direction.", "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "A list of workflow folders.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowFolderListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createWorkflowsFolder", "summary": "Create Workflow Folder", "description": "Create a canonical workflow folder in a workspace.", "tags": ["Workflows"], "requestBody": { "required": true, "description": "Workspace and canonical path for a new workflow folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowFolderRequest" } } } }, "responses": { "201": { "description": "The created workflow folder.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowFolderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "operationId": "relocateWorkflowsFolder", "summary": "Rename or Move Workflow Folder", "description": "Rename or move a workflow folder and its descendants to a canonical path.", "tags": ["Workflows"], "requestBody": { "required": true, "description": "Current and destination paths for a workflow folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelocateWorkflowFolderRequest" } } } }, "responses": { "200": { "description": "The relocated workflow folder.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelocateWorkflowFolderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteWorkflowsFolder", "summary": "Delete Workflow Folder", "description": "Delete a workflow folder, optionally including its descendants and workflows.", "tags": ["Workflows"], "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "description": "Workspace containing the folder.", "schema": { "type": "string", "minLength": 1, "description": "Workspace containing the folder." } }, { "name": "path", "in": "query", "required": true, "description": "Path of the folder to delete.", "schema": { "description": "Path of the folder to delete.", "type": "string" } }, { "name": "recursive", "in": "query", "required": false, "description": "Delete nested files and folders when true.", "schema": { "description": "Delete nested files and folders when true.", "default": "false", "type": "string" } } ], "responses": { "200": { "description": "The workflow folder was deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkflowFolderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your Sim API key (personal or workspace). Generate one from the Sim dashboard under Settings > API Keys." } }, "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." } }, "Retry-After": { "description": "Seconds to wait before retrying a rate-limited request.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying a rate-limited request." } }, "X-Run-Id": { "description": "Identifier assigned to the workflow run.", "schema": { "type": "string", "minLength": 1, "title": "Run identifier", "description": "Identifier assigned to the workflow run." } } }, "responses": { "BadRequest": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "Unauthorized": { "description": "The API key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "UsageLimitExceeded": { "description": "The workspace has exceeded its usage or billing limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "Forbidden": { "description": "The caller lacks access to the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "Conflict": { "description": "The request conflicts with current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "RunIdConflict": { "description": "The run identifier is already associated with a different request.", "headers": { "X-Run-Id": { "$ref": "#/components/headers/X-Run-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "Gone": { "description": "The requested generated resource has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "PayloadTooLarge": { "description": "The request body exceeds the allowed size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "UnsupportedMediaType": { "description": "The request uses an unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "Locked": { "description": "The resource is locked and cannot be modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "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" } } } }, "InternalError": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "ServiceUnavailable": { "description": "A required service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } } }, "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": "Optional structured error details." } }, "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." } } ] }, "WorkflowListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] }, "name": { "type": "string", "description": "Workflow name.", "examples": ["Customer support triage"] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow description, or null when none is set." }, "folderPath": { "type": "string", "description": "Canonical containing-folder path; `/` is the workspace root.", "examples": ["/Operations"] }, "workspaceId": { "type": "string", "description": "Workspace that owns the workflow." }, "isDeployed": { "type": "boolean", "description": "Whether the workflow has an active deployment." }, "deployedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 activation timestamp, or null when not deployed.", "format": "date-time" }, "runCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total recorded workflow runs." }, "lastRunAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the latest run, or null when never run.", "format": "date-time" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the workflow was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the workflow was last updated.", "format": "date-time" } }, "required": [ "id", "name", "description", "folderPath", "workspaceId", "isDeployed", "deployedAt", "runCount", "lastRunAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "Workflow summary", "description": "Summary of a workflow and its deployment and run state." }, "WorkflowListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowListItem" }, "description": "Items in the current page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page, or null when no more items remain." } }, "required": ["data", "nextCursor"], "additionalProperties": false, "title": "Workflow list response", "description": "A cursor-paginated page of workflow summaries.", "examples": [ { "data": [ { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Customer support triage", "description": "Routes incoming support requests to the right team.", "folderPath": "/Operations", "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "isDeployed": true, "deployedAt": "2026-06-12T10:30:00.000Z", "runCount": 42, "lastRunAt": "2026-08-09T18:04:11.000Z", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-08-09T18:04:11.000Z" } ], "nextCursor": null } ] }, "CreateWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowListItem" } }, "required": ["data"], "additionalProperties": false, "title": "Create workflow response", "description": "The created workflow summary.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Customer support triage", "description": "Routes incoming support requests to the right team.", "folderPath": "/Operations", "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "isDeployed": true, "deployedAt": "2026-06-12T10:30:00.000Z", "runCount": 42, "lastRunAt": "2026-08-09T18:04:11.000Z", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-08-09T18:04:11.000Z" } } ] }, "CreateWorkflowRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "description": "Workspace in which to create the workflow." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workflow name." }, "description": { "description": "Optional workflow description.", "anyOf": [ { "type": "string", "maxLength": 50000 }, { "type": "null" } ] }, "folderPath": { "description": "Folder path. A missing leading slash is normalized before validation.", "type": "string" } }, "required": ["workspaceId", "name"], "additionalProperties": false, "title": "Create workflow request", "description": "Name, description, workspace, and optional folder for a new workflow." }, "WorkflowInputField": { "type": "object", "properties": { "name": { "type": "string", "description": "Input field name." }, "type": { "type": "string", "description": "Input field type." }, "description": { "description": "Optional input field description.", "type": "string" } }, "required": ["name", "type"], "additionalProperties": false, "title": "Workflow input field", "description": "A deployed API trigger input exposed by a workflow." }, "WorkflowDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] }, "name": { "type": "string", "description": "Workflow name.", "examples": ["Customer support triage"] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow description, or null when none is set." }, "folderPath": { "type": "string", "description": "Canonical containing-folder path; `/` is the workspace root.", "examples": ["/Operations"] }, "workspaceId": { "type": "string", "description": "Workspace that owns the workflow." }, "isDeployed": { "type": "boolean", "description": "Whether the workflow has an active deployment." }, "deployedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 activation timestamp, or null when not deployed.", "format": "date-time" }, "runCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total recorded workflow runs." }, "lastRunAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the latest run, or null when never run.", "format": "date-time" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the workflow was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the workflow was last updated.", "format": "date-time" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Structured workflow variable value." }, "description": "Workflow-scoped variables keyed by variable identifier." }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowInputField" }, "description": "Input fields exposed by the workflow API trigger." } }, "required": [ "id", "name", "description", "folderPath", "workspaceId", "isDeployed", "deployedAt", "runCount", "lastRunAt", "createdAt", "updatedAt", "variables", "inputs" ], "additionalProperties": false, "title": "Workflow detail", "description": "Full workflow summary with variables and API-trigger input fields." }, "WorkflowDetailResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowDetail" } }, "required": ["data"], "additionalProperties": false, "title": "Workflow detail response", "description": "Detailed workflow metadata, variables, and trigger inputs.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Customer support triage", "description": "Routes incoming support requests to the right team.", "folderPath": "/Operations", "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "isDeployed": true, "deployedAt": "2026-06-12T10:30:00.000Z", "runCount": 42, "lastRunAt": "2026-08-09T18:04:11.000Z", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-08-09T18:04:11.000Z", "variables": {}, "inputs": [] } } ] }, "UpdateWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowListItem" } }, "required": ["data"], "additionalProperties": false, "title": "Update workflow response", "description": "The updated workflow summary.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Customer support triage", "description": "Routes incoming support requests to the right team.", "folderPath": "/Operations", "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "isDeployed": true, "deployedAt": "2026-06-12T10:30:00.000Z", "runCount": 42, "lastRunAt": "2026-08-09T18:04:11.000Z", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-08-09T18:04:11.000Z" } } ] }, "UpdateWorkflowRequest": { "type": "object", "properties": { "name": { "description": "Replacement workflow name.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "Replacement workflow description; null clears it.", "anyOf": [ { "type": "string", "maxLength": 50000 }, { "type": "null" } ] }, "folderPath": { "description": "Destination folder path; `/` moves the workflow to the workspace root.", "type": "string" } }, "additionalProperties": false, "title": "Update workflow request", "description": "Fields to update on an existing workflow." }, "DeleteWorkflowResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the deleted workflow." }, "deleted": { "type": "boolean", "const": true, "description": "Confirms that the workflow was deleted." } }, "required": ["id", "deleted"], "additionalProperties": false, "title": "Delete workflow result", "description": "Confirmation that a workflow was deleted." }, "DeleteWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/DeleteWorkflowResult" } }, "required": ["data"], "additionalProperties": false, "title": "Delete workflow response", "description": "Confirmation that the workflow was deleted.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "deleted": true } } ] }, "WorkflowVersion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique deployment-version identifier." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Monotonically increasing deployment version number." }, "name": { "description": "Optional deployment-version label.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "description": "Optional deployment-version release note.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isActive": { "type": "boolean", "description": "Whether this version is currently serving executions." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when this version was created.", "format": "date-time" }, "deployedBy": { "description": "Display name of the user who created the deployment, when available.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latestOperationStatus": { "description": "Latest lifecycle-operation status for this version.", "anyOf": [ { "type": "string", "enum": ["preparing", "activating", "active", "failed", "superseded"] }, { "type": "null" } ] } }, "required": ["id", "version", "isActive", "createdAt"], "additionalProperties": false, "title": "Workflow version", "description": "A saved deployment version of a workflow." }, "WorkflowVersionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVersion" }, "description": "Items in the current page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page, or null when no more items remain." } }, "required": ["data", "nextCursor"], "additionalProperties": false, "title": "Workflow version list response", "description": "A cursor-paginated page of deployment versions.", "examples": [ { "data": [ { "id": "version_3", "version": 3, "name": "Escalation routing", "description": "Adds the priority escalation branch.", "isActive": true, "createdAt": "2026-06-12T10:30:00.000Z", "deployedBy": "Jane Smith", "latestOperationStatus": "active" } ], "nextCursor": null } ] }, "DeployedWorkflowState": { "title": "Deployed workflow state", "description": "Workflow graph snapshot pinned by a deployment version.", "type": "object", "additionalProperties": true }, "WorkflowVersionDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique deployment-version identifier." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Monotonically increasing deployment version number." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version label, or null when unset." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version release note, or null when unset." }, "isActive": { "type": "boolean", "description": "Whether this version is currently serving executions." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when this version was created.", "format": "date-time" }, "state": { "description": "Deployed workflow graph snapshot pinned by this version.", "$ref": "#/components/schemas/DeployedWorkflowState" } }, "required": ["id", "version", "name", "description", "isActive", "createdAt", "state"], "additionalProperties": false, "title": "Workflow version detail", "description": "A deployment version together with the workflow state it pins." }, "WorkflowVersionDetailResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowVersionDetail" } }, "required": ["data"], "additionalProperties": false, "title": "Workflow version detail response", "description": "The deployment version and its pinned workflow graph.", "examples": [ { "data": { "id": "version_3", "version": 3, "name": "Escalation routing", "description": "Adds the priority escalation branch.", "isActive": true, "createdAt": "2026-06-12T10:30:00.000Z", "state": { "blocks": {}, "edges": [] } } } ] }, "ActiveDeploymentSummary": { "type": "object", "properties": { "deploymentVersionId": { "type": "string", "description": "Identifier of the active deployment version." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Numeric active deployment version." }, "deployedAt": { "type": "string", "description": "ISO 8601 timestamp when this version became active.", "format": "date-time" } }, "required": ["deploymentVersionId", "version", "deployedAt"], "additionalProperties": false, "title": "Active deployment", "description": "Summary of the workflow version currently serving API executions." }, "DeploymentOperationSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique deployment operation identifier." }, "deploymentVersionId": { "type": "string", "description": "Deployment version targeted by this operation." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Numeric deployment version." }, "action": { "type": "string", "enum": ["deploy", "activate"], "description": "Operation being performed on the deployment version." }, "status": { "type": "string", "enum": ["preparing", "activating", "active", "failed", "superseded"], "description": "Current deployment lifecycle status." }, "isCurrent": { "default": true, "description": "Whether this operation still describes the current deployment attempt.", "type": "boolean" }, "readiness": { "$ref": "#/components/schemas/DeploymentReadiness" }, "requestedAt": { "type": "string", "description": "ISO 8601 timestamp when the deployment operation was requested.", "format": "date-time" }, "activatedAt": { "description": "ISO 8601 activation timestamp, or null before activation completes.", "format": "date-time", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "description": "Deployment failure details, or null when no failure occurred.", "anyOf": [ { "$ref": "#/components/schemas/DeploymentOperationError" }, { "type": "null" } ] } }, "required": [ "id", "deploymentVersionId", "version", "action", "status", "isCurrent", "readiness", "requestedAt" ], "additionalProperties": false, "title": "Deployment operation", "description": "Lifecycle state of a deployment or version-activation attempt." }, "DeploymentReadiness": { "type": "object", "properties": { "webhooks": { "type": "string", "enum": ["pending", "ready", "not_applicable"], "description": "Webhook synchronization readiness." }, "schedules": { "type": "string", "enum": ["pending", "ready", "not_applicable"], "description": "Schedule synchronization readiness." }, "mcp": { "type": "string", "enum": ["pending", "ready", "not_applicable"], "description": "MCP synchronization readiness." } }, "required": ["webhooks", "schedules", "mcp"], "additionalProperties": false, "title": "Deployment readiness", "description": "Readiness of the side effects required to activate a deployment." }, "DeploymentOperationError": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable deployment failure code." }, "message": { "type": "string", "description": "Human-readable deployment failure message." }, "retryable": { "type": "boolean", "description": "Whether retrying the deployment may succeed." } }, "required": ["code", "message", "retryable"], "additionalProperties": false, "title": "Deployment operation error", "description": "Failure details for a deployment lifecycle operation." }, "DeployResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] }, "isDeployed": { "type": "boolean", "description": "Whether a workflow version is currently live and available for API execution." }, "deployedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.", "format": "date-time", "examples": ["2026-06-12T10:30:00.000Z"] }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal synchronization warnings. Empty when there is nothing to report." }, "activeDeployment": { "anyOf": [ { "$ref": "#/components/schemas/ActiveDeploymentSummary" }, { "type": "null" } ], "description": "Currently live deployment version, or null while no version is active." }, "latestDeploymentAttempt": { "anyOf": [ { "$ref": "#/components/schemas/DeploymentOperationSummary" }, { "type": "null" } ], "description": "Most recent deployment lifecycle attempt, or null when none is available." }, "version": { "description": "Deployment version created for this attempt, when available.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "isDeployed", "deployedAt", "warnings", "activeDeployment", "latestDeploymentAttempt" ], "additionalProperties": false, "title": "Deploy result", "description": "Deployment attempt accepted for processing. Activation is asynchronous; inspect `isDeployed` and `latestDeploymentAttempt` for current state." }, "DeployWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/DeployResult" } }, "required": ["data"], "additionalProperties": false, "title": "Deploy workflow response", "description": "Current deployment state after accepting the attempt.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "isDeployed": true, "deployedAt": "2026-06-12T10:30:00.000Z", "warnings": [], "activeDeployment": null, "latestDeploymentAttempt": null, "version": 3 } } ] }, "DeployWorkflowRequest": { "default": {}, "title": "Deploy workflow request", "description": "Optional metadata for the new deployment version.", "examples": [ { "name": "Escalation routing", "description": "Adds the priority escalation branch." } ], "type": "object", "properties": { "name": { "description": "Optional label for the deployment version.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "description": "Optional release note for the deployment version.", "anyOf": [ { "type": "string", "maxLength": 50000 }, { "type": "null" } ] } } }, "UndeployResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] }, "isDeployed": { "type": "boolean", "description": "Whether a workflow version is currently live and available for API execution." }, "deployedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.", "format": "date-time", "examples": ["2026-06-12T10:30:00.000Z"] }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal synchronization warnings. Empty when there is nothing to report." }, "activeDeployment": { "anyOf": [ { "$ref": "#/components/schemas/ActiveDeploymentSummary" }, { "type": "null" } ], "description": "Currently live deployment version, or null while no version is active." }, "latestDeploymentAttempt": { "anyOf": [ { "$ref": "#/components/schemas/DeploymentOperationSummary" }, { "type": "null" } ], "description": "Most recent deployment lifecycle attempt, or null when none is available." } }, "required": [ "id", "isDeployed", "deployedAt", "warnings", "activeDeployment", "latestDeploymentAttempt" ], "additionalProperties": false, "title": "Undeploy result", "description": "Deployment state after a successful undeploy. `isDeployed` is false and no workflow version is active." }, "UndeployWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/UndeployResult" } }, "required": ["data"], "additionalProperties": false, "title": "Undeploy workflow response", "description": "Deployment state after deactivating the active version.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "isDeployed": false, "deployedAt": null, "warnings": [], "activeDeployment": null, "latestDeploymentAttempt": null } } ] }, "RollbackResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique workflow identifier.", "examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"] }, "isDeployed": { "type": "boolean", "description": "Whether a workflow version is currently live and available for API execution." }, "deployedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.", "format": "date-time", "examples": ["2026-06-12T10:30:00.000Z"] }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal synchronization warnings. Empty when there is nothing to report." }, "activeDeployment": { "anyOf": [ { "$ref": "#/components/schemas/ActiveDeploymentSummary" }, { "type": "null" } ], "description": "Currently live deployment version, or null while no version is active." }, "latestDeploymentAttempt": { "anyOf": [ { "$ref": "#/components/schemas/DeploymentOperationSummary" }, { "type": "null" } ], "description": "Most recent deployment lifecycle attempt, or null when none is available." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Deployment version selected for re-activation." } }, "required": [ "id", "isDeployed", "deployedAt", "warnings", "activeDeployment", "latestDeploymentAttempt", "version" ], "additionalProperties": false, "title": "Rollback result", "description": "Rollback attempt accepted for processing. Activation is asynchronous; inspect `isDeployed` and `latestDeploymentAttempt` for current state." }, "RollbackWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/RollbackResult" } }, "required": ["data"], "additionalProperties": false, "title": "Rollback workflow response", "description": "Current deployment state after accepting the rollback attempt.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "isDeployed": true, "deployedAt": "2026-06-12T10:30:00.000Z", "warnings": [], "activeDeployment": null, "latestDeploymentAttempt": null, "version": 2 } } ] }, "RollbackWorkflowRequest": { "default": {}, "title": "Rollback workflow request", "description": "Optional deployment version to reactivate.", "examples": [ { "version": 2 } ], "type": "object", "properties": { "version": { "description": "Deployment version to reactivate. Omit to select the previous active version.", "type": "integer", "minimum": 1, "maximum": 2147483647 } } }, "WorkflowExportPayload": { "type": "object", "properties": { "version": { "type": "string", "const": "1.0", "description": "Workflow export format version." }, "exportedAt": { "type": "string", "description": "ISO 8601 timestamp when the export was created.", "format": "date-time" }, "workflow": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the source workflow." }, "name": { "type": "string", "description": "Name of the exported workflow." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description of the exported workflow, or null when unset." }, "workspaceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the source workspace, or null for legacy exports." }, "folderPath": { "type": "string", "description": "Canonical containing-folder path; `/` is the workspace root." } }, "required": ["id", "name", "description", "workspaceId", "folderPath"], "additionalProperties": false, "description": "Source workflow metadata." }, "state": { "type": "object", "additionalProperties": true, "description": "Secret-sanitized workflow graph, edges, loops, parallels, metadata, and variables." } }, "required": ["version", "exportedAt", "workflow", "state"], "additionalProperties": false, "title": "Workflow export payload", "description": "Portable, secret-sanitized workflow export. Workspace-scoped bindings must be selected again after import." }, "ExportWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowExportPayload" } }, "required": ["data"], "additionalProperties": false, "title": "Export workflow response", "description": "Portable, secret-sanitized workflow data.", "examples": [ { "data": { "version": "1.0", "exportedAt": "2026-08-09T18:04:11.000Z", "workflow": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Customer support triage", "description": "Routes incoming support requests to the right team.", "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "folderPath": "/Operations" }, "state": { "blocks": {}, "edges": [] } } } ] }, "ImportedWorkflow": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the imported workflow." }, "name": { "type": "string", "description": "Imported workflow name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Imported workflow description." }, "workspaceId": { "type": "string", "description": "Workspace that owns the imported workflow." }, "folderPath": { "type": "string", "description": "Canonical containing-folder path." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the workflow was imported.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the workflow was last updated.", "format": "date-time" } }, "required": [ "id", "name", "description", "workspaceId", "folderPath", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "Imported workflow", "description": "Workflow created by an import operation." }, "ImportWorkflowResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/ImportedWorkflow" } }, "required": ["data"], "additionalProperties": false, "title": "Import workflow response", "description": "The workflow created by the import.", "examples": [ { "data": { "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "name": "Customer support triage", "description": "Routes incoming support requests to the right team.", "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64", "folderPath": "/Operations", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-08-09T18:04:11.000Z" } } ] }, "ImportWorkflowRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "description": "Workspace in which to import the workflow." }, "workflow": { "anyOf": [ { "type": "string", "minLength": 1, "description": "JSON string containing a workflow export object or bare workflow state." }, { "type": "object", "additionalProperties": true, "description": "Workflow export object or bare workflow state." } ], "description": "Workflow export object, bare workflow state, or JSON string containing either form." }, "folderPath": { "description": "Destination folder path; omit for the workspace root.", "type": "string" }, "name": { "description": "Override for the imported workflow name.", "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "description": "Override for the imported workflow description.", "type": "string", "maxLength": 2000 } }, "required": ["workspaceId", "workflow"], "additionalProperties": false, "title": "Import workflow request", "description": "Portable workflow data and destination metadata for an import." }, "ExecutionError": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable workflow execution failure message." }, "code": { "type": "string", "enum": [ "TIMEOUT", "CANCELLED", "USAGE_LIMIT_EXCEEDED", "INVALID_INPUT", "BLOCK_EXECUTION_FAILED", "CHILD_WORKFLOW_FAILED", "OUTPUT_TOO_LARGE", "EXECUTION_FAILED" ], "description": "Stable machine-readable execution failure code." }, "blockId": { "description": "Identifier of the failing block, when attributable.", "type": "string" }, "blockName": { "description": "Display name of the failing block.", "type": "string" }, "blockType": { "description": "Integration or block type that failed.", "type": "string" } }, "required": ["message", "code"], "additionalProperties": false, "title": "Execution error", "description": "Structured in-band failure details for a workflow run." }, "WorkflowRunResult": { "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] }, "workflowId": { "type": "string", "description": "Workflow that produced the run." }, "status": { "type": "string", "enum": ["completed", "failed", "paused", "cancelled"], "description": "Terminal or paused run status." }, "output": { "description": "Workflow output, including partial output on failure." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ExecutionError" }, { "type": "null" } ], "description": "Structured execution failure, or null when none occurred." }, "startedAt": { "description": "ISO 8601 timestamp when execution started.", "format": "date-time", "type": "string" }, "endedAt": { "description": "ISO 8601 timestamp when execution ended.", "format": "date-time", "type": "string" }, "durationMs": { "description": "Execution duration in milliseconds.", "type": "number", "minimum": 0 } }, "required": ["runId", "workflowId", "status", "output", "error"], "additionalProperties": false, "title": "Workflow run result", "description": "Synchronous workflow run output and in-band execution status." }, "ExecuteWorkflowSyncResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowRunResult" } }, "required": ["data"], "additionalProperties": false, "title": "Synchronous workflow execution response", "description": "Completed, failed, paused, or cancelled synchronous workflow run.", "examples": [ { "data": { "runId": "run_8f14e45f-ceea-467f-a", "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "status": "completed", "output": { "result": "Ticket routed to Support" }, "error": null, "startedAt": "2026-08-09T18:04:10.000Z", "endedAt": "2026-08-09T18:04:11.000Z", "durationMs": 1000 } } ] }, "QueuedWorkflowRun": { "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] }, "statusUrl": { "type": "string", "format": "uri", "description": "Absolute URL of the workflow run resource." } }, "required": ["runId", "statusUrl"], "additionalProperties": false, "title": "Queued workflow run", "description": "Receipt returned when a workflow run is queued." }, "ExecuteWorkflowQueuedResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/QueuedWorkflowRun" } }, "required": ["data"], "additionalProperties": false, "title": "Queued workflow execution response", "description": "Receipt returned for an asynchronous workflow run.", "examples": [ { "data": { "runId": "run_8f14e45f-ceea-467f-a", "statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a" } } ] }, "ExecuteWorkflowRequest": { "type": "object", "properties": { "input": { "description": "Workflow input keyed by deployed trigger input-field name.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Value supplied for one workflow input field." } }, "async": { "default": false, "description": "Queue the run and return a 202 receipt when true.", "type": "boolean" }, "executionTimeoutSeconds": { "description": "Server-side timeout for an asynchronous run, in seconds.", "type": "integer", "minimum": 1, "maximum": 604800 }, "stream": { "default": false, "description": "Return Server-Sent Events instead of JSON when true.", "type": "boolean" }, "selectedOutputs": { "description": "Block output references to include in a streamed response.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "includeThinking": { "default": false, "description": "Include model reasoning events in an agent-event stream.", "type": "boolean" }, "includeToolCalls": { "default": false, "description": "Include tool-call events in an agent-event stream.", "type": "boolean" }, "includeFileBase64": { "description": "Inline eligible output files as base64 content.", "type": "boolean" }, "base64MaxBytes": { "description": "Maximum total bytes of file content to inline as base64.", "type": "integer", "exclusiveMinimum": 0, "maximum": 10485760 } }, "additionalProperties": false, "title": "Execute workflow request", "description": "Input and execution-mode options for a deployed workflow.", "examples": [ { "input": { "ticketId": "ticket_123" } }, { "input": { "ticketId": "ticket_123" }, "async": true }, { "input": { "ticketId": "ticket_123" }, "stream": true } ] }, "WorkflowRunListItem": { "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] }, "workflowId": { "type": "string", "description": "Workflow that produced the run." }, "status": { "type": "string", "enum": ["pending", "running", "completed", "failed", "cancelled", "paused"], "description": "Current or terminal run status." }, "trigger": { "type": "string", "description": "Trigger type that started the run." }, "startedAt": { "type": "string", "description": "ISO 8601 timestamp when the run started.", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the run ended, or null while active.", "format": "date-time" }, "durationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Run duration in milliseconds, or null while active." }, "cost": { "anyOf": [ { "type": "object", "properties": { "total": { "type": "number", "description": "Total credits consumed by the run." } }, "required": ["total"], "additionalProperties": false }, { "type": "null" } ], "description": "Credit cost, or null when unavailable." } }, "required": [ "runId", "workflowId", "status", "trigger", "startedAt", "endedAt", "durationMs", "cost" ], "additionalProperties": false, "title": "Workflow run summary", "description": "Summary of a recorded workflow run." }, "WorkflowRunListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunListItem" }, "description": "Items in the current page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page, or null when no more items remain." } }, "required": ["data", "nextCursor"], "additionalProperties": false, "title": "Workflow run list response", "description": "A cursor-paginated page of workflow run summaries.", "examples": [ { "data": [ { "runId": "run_8f14e45f-ceea-467f-a", "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "status": "completed", "trigger": "api", "startedAt": "2026-08-09T18:04:10.000Z", "endedAt": "2026-08-09T18:04:11.000Z", "durationMs": 1000, "cost": { "total": 12 } } ], "nextCursor": null } ] }, "WorkflowRunStatus": { "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] }, "workflowId": { "type": "string", "description": "Workflow that produced the run." }, "status": { "type": "string", "enum": ["queued", "pending", "running", "completed", "failed", "cancelled", "paused"], "description": "Current or terminal run status." }, "trigger": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Trigger type, or null before the run is recorded." }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 start timestamp, or null while queued.", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 end timestamp, or null while nonterminal.", "format": "date-time" }, "durationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Run duration in milliseconds, or null while active." }, "paused": { "anyOf": [ { "type": "object", "properties": { "contextId": { "type": "string", "description": "Resume context identifier for the earliest active pause point." }, "pausedAt": { "type": "string", "description": "ISO 8601 timestamp when the execution entered the paused state." }, "resumeAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scheduled automatic-resume timestamp, or null when no resume time is set." }, "pauseKind": { "anyOf": [ { "type": "string", "enum": ["time", "human"] }, { "type": "null" } ], "description": "Whether the pause waits for time or human input, or null when unspecified." }, "blockedOnBlockId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow block awaiting resume, or null when no block is identified." }, "automaticResumeWaitingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason automatic resume is waiting, or null when it is not waiting." }, "pausePointCount": { "type": "number", "description": "Number of pause points tracked for the execution." }, "resumedCount": { "type": "number", "description": "Number of pause points that have resumed." } }, "required": [ "contextId", "pausedAt", "resumeAt", "pauseKind", "blockedOnBlockId", "automaticResumeWaitingReason", "pausePointCount", "resumedCount" ], "additionalProperties": false }, { "type": "null" } ], "description": "Current pause details, or null when the run is not paused." }, "cost": { "anyOf": [ { "type": "object", "properties": { "total": { "type": "number", "description": "Total credits consumed by the run." } }, "required": ["total"], "additionalProperties": false }, { "type": "null" } ], "description": "Credit cost, or null when unavailable." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ExecutionError" }, { "type": "null" } ], "description": "Structured execution failure, or null when none occurred." }, "output": { "anyOf": [ { "description": "Final workflow output value." }, { "type": "null" } ], "description": "Final workflow output when requested, otherwise null." }, "blockOutputs": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Output value produced by one workflow block." } }, { "type": "null" } ], "description": "Selected block outputs when requested, otherwise null." } }, "required": [ "runId", "workflowId", "status", "trigger", "startedAt", "endedAt", "durationMs", "paused", "cost", "error", "output", "blockOutputs" ], "additionalProperties": false, "title": "Workflow run status", "description": "Detailed current state of a workflow run." }, "WorkflowRunStatusResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowRunStatus" } }, "required": ["data"], "additionalProperties": false, "title": "Workflow run status response", "description": "Detailed current state of a workflow run.", "examples": [ { "data": { "runId": "run_8f14e45f-ceea-467f-a", "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "status": "completed", "trigger": "api", "startedAt": "2026-08-09T18:04:10.000Z", "endedAt": "2026-08-09T18:04:11.000Z", "durationMs": 1000, "paused": null, "cost": { "total": 12 }, "error": null, "output": { "result": "Ticket routed to Support" }, "blockOutputs": null } } ] }, "ResumeWorkflowSyncResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowRunResult" } }, "required": ["data"], "additionalProperties": false, "title": "Synchronous workflow resume response", "description": "Completed, failed, paused, or cancelled resumed workflow run.", "examples": [ { "data": { "runId": "run_8f14e45f-ceea-467f-a", "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36", "status": "completed", "output": { "result": "Ticket routed to Support" }, "error": null, "startedAt": "2026-08-09T18:04:10.000Z", "endedAt": "2026-08-09T18:04:11.000Z", "durationMs": 1000 } } ] }, "QueuedWorkflowResume": { "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] }, "statusUrl": { "type": "string", "format": "uri", "description": "Absolute URL of the workflow run resource." }, "queuePosition": { "description": "Current queue position, when available.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["runId", "statusUrl"], "additionalProperties": false, "title": "Queued workflow resume", "description": "Receipt returned when a resumed workflow attempt is queued." }, "ResumeWorkflowQueuedResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/QueuedWorkflowResume" } }, "required": ["data"], "additionalProperties": false, "title": "Queued workflow resume response", "description": "Receipt returned when a resumed workflow attempt is queued.", "examples": [ { "data": { "runId": "run_8f14e45f-ceea-467f-a", "statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a" } } ] }, "ResumeWorkflowRequest": { "type": "object", "properties": { "contextId": { "type": "string", "minLength": 1, "description": "Human-in-the-loop pause-context identifier." }, "input": { "description": "Input supplied to the paused workflow block." } }, "required": ["contextId"], "additionalProperties": false, "title": "Resume workflow request", "description": "Pause context and optional input used to resume a workflow run.", "examples": [ { "contextId": "ctx_123", "input": { "approved": true } } ] }, "CancelWorkflowRunResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether cancellation was accepted." }, "runId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Unique workflow run identifier.", "examples": ["run_8f14e45f-ceea-467f-a"] }, "redisAvailable": { "type": "boolean", "description": "Whether the distributed cancellation channel was available." }, "durablyRecorded": { "type": "boolean", "description": "Whether cancellation was recorded durably." }, "locallyAborted": { "type": "boolean", "description": "Whether an in-process execution was aborted." }, "pausedCancelled": { "type": "boolean", "description": "Whether a paused execution was cancelled." }, "reason": { "description": "Machine-readable cancellation outcome when cancellation was partial.", "type": "string", "enum": [ "recorded", "redis_unavailable", "redis_write_failed", "paused_event_publish_failed", "paused_database_cancel_failed" ] } }, "required": [ "success", "runId", "redisAvailable", "durablyRecorded", "locallyAborted", "pausedCancelled" ], "additionalProperties": false, "title": "Cancel workflow run result", "description": "Outcome of a workflow run cancellation request." }, "CancelWorkflowRunResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/CancelWorkflowRunResult" } }, "required": ["data"], "additionalProperties": false, "title": "Cancel workflow run response", "description": "Outcome of the cancellation request.", "examples": [ { "data": { "success": true, "runId": "run_8f14e45f-ceea-467f-a", "redisAvailable": true, "durablyRecorded": true, "locallyAborted": true, "pausedCancelled": false, "reason": "recorded" } } ] }, "WorkflowFolder": { "type": "object", "properties": { "name": { "type": "string", "description": "Folder name." }, "path": { "type": "string", "description": "Canonical folder path used as the public folder identifier." }, "parentPath": { "type": "string", "description": "Canonical parent path; `/` is the root." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the folder was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the folder was last updated.", "format": "date-time" }, "locked": { "type": "boolean", "description": "Whether the folder is currently locked for mutation." } }, "required": ["name", "path", "parentPath", "createdAt", "updatedAt", "locked"], "additionalProperties": false, "title": "Workflow folder", "description": "A canonical workflow folder and its mutation lock state." }, "WorkflowFolderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowFolder" }, "description": "Items in the current page." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page, or null when no more items remain." } }, "required": ["data", "nextCursor"], "additionalProperties": false, "title": "Workflow folder list response", "description": "A list of canonical workflow folders.", "examples": [ { "data": [ { "name": "Operations", "path": "/Operations", "parentPath": "/", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-05-01T09:00:00.000Z", "locked": false } ], "nextCursor": null } ] }, "WorkflowFolderData": { "type": "object", "properties": { "folder": { "description": "Created or relocated workflow folder.", "$ref": "#/components/schemas/WorkflowFolder" } }, "required": ["folder"], "additionalProperties": false, "title": "Workflow folder data", "description": "A created or relocated workflow folder." }, "CreateWorkflowFolderResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowFolderData" } }, "required": ["data"], "additionalProperties": false, "title": "Create workflow folder response", "description": "The created workflow folder.", "examples": [ { "data": { "folder": { "name": "Operations", "path": "/Operations", "parentPath": "/", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-05-01T09:00:00.000Z", "locked": false } } } ] }, "CreateWorkflowFolderRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "description": "Workspace in which to create the folder." }, "path": { "description": "Path of the folder to create.", "type": "string" } }, "required": ["workspaceId", "path"], "additionalProperties": false, "title": "Create workflow folder request", "description": "Workspace and canonical path for a new workflow folder." }, "RelocateWorkflowFolderResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/WorkflowFolderData" } }, "required": ["data"], "additionalProperties": false, "title": "Relocate workflow folder response", "description": "The relocated workflow folder.", "examples": [ { "data": { "folder": { "name": "Support", "path": "/Support", "parentPath": "/", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-05-01T09:00:00.000Z", "locked": false } } } ] }, "RelocateWorkflowFolderRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "description": "Workspace containing the folder." }, "path": { "description": "Current folder path.", "type": "string" }, "destinationPath": { "description": "New full path for the folder and its descendants.", "type": "string" } }, "required": ["workspaceId", "path", "destinationPath"], "additionalProperties": false, "title": "Relocate workflow folder request", "description": "Current and destination paths for a workflow folder." }, "DeleteWorkflowFolderResult": { "type": "object", "properties": { "path": { "type": "string", "description": "Path of the deleted workflow folder." }, "deleted": { "type": "boolean", "const": true, "description": "Confirms that the folder was deleted." }, "deletedItems": { "type": "object", "properties": { "folders": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of folders deleted." }, "workflows": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of workflows deleted." } }, "required": ["folders", "workflows"], "additionalProperties": false, "description": "Resources removed by the deletion." } }, "required": ["path", "deleted", "deletedItems"], "additionalProperties": false, "title": "Delete workflow folder result", "description": "Confirmation and deletion counts for a workflow folder." }, "DeleteWorkflowFolderResponse": { "type": "object", "properties": { "data": { "description": "Response data.", "$ref": "#/components/schemas/DeleteWorkflowFolderResult" } }, "required": ["data"], "additionalProperties": false, "title": "Delete workflow folder response", "description": "Confirmation and counts for the deleted folder.", "examples": [ { "data": { "path": "/Operations", "deleted": true, "deletedItems": { "folders": 1, "workflows": 0 } } } ] } } }, "x-generated-by": "scripts/generate-openapi.ts" }