# Get workflow state (/api-reference/workflows/getWorkflowState)

`GET /api/v2/workflows/{workflowId}/state`

Read the saved editable draft, including blocks, edges, loop and parallel containers, and variables. Requires workspace read access. Configured values are included; use this state with Replace workflow state for same-workspace editing, or Export workflow for portable data with registered credential fields cleared. This read records no audit event; `HEAD` mirrors `GET`.

OAuth scope: `api:read`.

## Authentication

```json

{
  "requirements": [
    {
      "apiKey": []
    },
    {
      "oauthBearer": [
        "api:read"
      ]
    }
  ],
  "schemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description."
    },
    "oauthBearer": {
      "type": "oauth2",
      "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
          "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "scopes": {
            "api:read": "Read your workspaces, workflows, files, tables, and logs",
            "api:write": "Read, create, change, run, and delete resources in your workspaces",
            "offline_access": "Stay signed in without asking again"
          }
        }
      }
    }
  }
}

```

Required OAuth scope: `api:read`.

## Request examples

### cURL

```bash
curl --request GET 'https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/state' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### JavaScript

```javascript
const response = await fetch("https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/state", {
  "method": "GET",
  "headers": {
    "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import requests

response = requests.request(
    "GET",
    "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/state",
    headers={
  "X-API-Key": "YOUR_API_KEY"
},
)
response.raise_for_status()
result = response.json()
```

### Go

```go
package main

import (
  "io"
  "net/http"
  "os"
)

func check(err error) {
  if err != nil { panic(err) }
}

func must[T any](value T, err error) T {
  check(err)
  return value
}

func main() {

  request := must(http.NewRequest("GET", "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/state", nil))
  request.Header.Set("X-API-Key", "YOUR_API_KEY")
  response := must(http.DefaultClient.Do(request))
  defer response.Body.Close()
  if response.StatusCode >= 400 { panic(response.Status) }
  must(io.Copy(os.Stdout, response.Body))
}
```

### Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/state"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    var request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).build();
    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream());
    try (var body = response.body()) {
      if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode());
      body.transferTo(System.out);
    }
  }
}
```

### C#

```csharp
using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/state");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY");
using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
await response.Content.CopyToAsync(Console.OpenStandardOutput());
```

## Parameters

```json

[
  {
    "name": "workflowId",
    "in": "path",
    "required": true,
    "description": "Unique workflow identifier.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "description": "Unique workflow identifier.",
      "examples": [
        "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"
      ]
    }
  }
]

```

## Responses

### 200

```json

{
  "description": "The workflow draft graph.",
  "headers": {
    "X-RateLimit-Limit": {
      "description": "Maximum requests allowed in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit",
        "description": "Maximum requests allowed in the current window."
      }
    },
    "X-RateLimit-Remaining": {
      "description": "Requests remaining in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit remaining",
        "description": "Requests remaining in the current window."
      }
    },
    "X-RateLimit-Reset": {
      "description": "ISO 8601 timestamp when the current rate-limit window resets.",
      "schema": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "title": "Rate limit reset",
        "description": "ISO 8601 timestamp when the current rate-limit window resets."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "blocks": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Block identifier, unique within the workflow."
                    },
                    "type": {
                      "type": "string",
                      "description": "Registered block type."
                    },
                    "name": {
                      "type": "string",
                      "description": "Block display name; must be unique within the workflow."
                    },
                    "position": {
                      "type": "object",
                      "properties": {
                        "x": {
                          "type": "number",
                          "description": "Canvas x coordinate."
                        },
                        "y": {
                          "type": "number",
                          "description": "Canvas y coordinate."
                        }
                      },
                      "required": [
                        "x",
                        "y"
                      ],
                      "additionalProperties": false,
                      "description": "Canvas coordinates of a block."
                    },
                    "subBlocks": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Sub-block identifier."
                          },
                          "type": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Sub-block input type."
                          },
                          "value": {
                            "description": "Configured value; shape depends on the sub-block type."
                          }
                        },
                        "required": [
                          "id",
                          "type",
                          "value"
                        ],
                        "additionalProperties": false,
                        "description": "One configurable input on a block."
                      },
                      "description": "Configured inputs keyed by sub-block id."
                    },
                    "outputs": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "description": "Declared shape of one output; depends on the block type."
                      },
                      "description": "Declared output shape keyed by output name."
                    },
                    "enabled": {
                      "type": "boolean",
                      "description": "Whether the block runs."
                    },
                    "horizontalHandles": {
                      "description": "Whether edge handles render horizontally.",
                      "type": "boolean"
                    },
                    "height": {
                      "description": "Rendered block height.",
                      "type": "number"
                    },
                    "advancedMode": {
                      "description": "Whether the block is edited in advanced mode.",
                      "type": "boolean"
                    },
                    "errorEnabled": {
                      "description": "Whether the block exposes an error branch.",
                      "type": "boolean"
                    },
                    "retry": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean",
                          "description": "Whether the block retries on failure."
                        },
                        "maxTries": {
                          "type": "integer",
                          "minimum": 2,
                          "maximum": 5,
                          "description": "Total attempts, including the first."
                        },
                        "waitBetweenTriesMs": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 5000,
                          "description": "Delay between attempts, in milliseconds."
                        }
                      },
                      "required": [
                        "enabled",
                        "maxTries",
                        "waitBetweenTriesMs"
                      ],
                      "additionalProperties": false,
                      "description": "Per-block retry configuration."
                    },
                    "triggerMode": {
                      "description": "Whether the block acts as the workflow trigger.",
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "parentId": {
                          "description": "Identifier of the containing loop or parallel.",
                          "type": "string"
                        },
                        "extent": {
                          "description": "Constrains the block to its parent bounds.",
                          "type": "string",
                          "const": "parent"
                        },
                        "width": {
                          "description": "Rendered container width.",
                          "type": "number"
                        },
                        "height": {
                          "description": "Rendered container height.",
                          "type": "number"
                        },
                        "collection": {
                          "description": "Items a forEach loop or collection parallel iterates."
                        },
                        "count": {
                          "description": "Iteration count for a `for` loop or count parallel.",
                          "type": "number"
                        },
                        "loopType": {
                          "description": "Loop container kind.",
                          "type": "string",
                          "enum": [
                            "for",
                            "forEach",
                            "while",
                            "doWhile"
                          ]
                        },
                        "whileCondition": {
                          "description": "Condition expression for a `while` loop.",
                          "type": "string"
                        },
                        "doWhileCondition": {
                          "description": "Condition expression for a `doWhile` loop.",
                          "type": "string"
                        },
                        "parallelType": {
                          "description": "Parallel container kind.",
                          "type": "string",
                          "enum": [
                            "collection",
                            "count"
                          ]
                        },
                        "batchSize": {
                          "description": "Maximum concurrent branches of a parallel.",
                          "type": "number"
                        },
                        "type": {
                          "description": "Container subtype.",
                          "type": "string"
                        },
                        "canonicalModes": {
                          "description": "Per-field editing mode, keyed by canonical parameter id.",
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "type": "string",
                            "enum": [
                              "basic",
                              "advanced"
                            ]
                          }
                        }
                      },
                      "additionalProperties": false,
                      "description": "Container and layout metadata carried by a block."
                    },
                    "locked": {
                      "description": "Whether the block is locked against edits.",
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "id",
                    "type",
                    "name",
                    "position",
                    "subBlocks",
                    "outputs",
                    "enabled"
                  ],
                  "additionalProperties": false,
                  "title": "Workflow block",
                  "description": "One node of a workflow graph and its configuration."
                },
                "description": "Blocks keyed by block id."
              },
              "edges": {
                "maxItems": 10000,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Edge identifier, unique within the workflow."
                    },
                    "source": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Source block id."
                    },
                    "target": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Target block id."
                    },
                    "sourceHandle": {
                      "description": "Source port, or null for the block default.",
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "targetHandle": {
                      "description": "Target port, or null for the block default.",
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "type": {
                      "description": "Edge renderer type.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "source",
                    "target"
                  ],
                  "additionalProperties": false,
                  "title": "Workflow edge",
                  "description": "A directed connection between two blocks."
                },
                "description": "Directed connections between blocks."
              },
              "loops": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Loop container identifier; equal to the loop block id."
                    },
                    "nodes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Block ids inside the loop."
                    },
                    "iterations": {
                      "type": "number",
                      "description": "Resolved iteration count."
                    },
                    "loopType": {
                      "type": "string",
                      "enum": [
                        "for",
                        "forEach",
                        "while",
                        "doWhile"
                      ],
                      "description": "Loop kind."
                    },
                    "forEachItems": {
                      "description": "Items a forEach loop iterates, or the expression producing them.",
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "description": "One item the loop iterates."
                          }
                        },
                        {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "description": "One item the loop iterates."
                          }
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "whileCondition": {
                      "description": "Condition expression for a `while` loop.",
                      "type": "string"
                    },
                    "doWhileCondition": {
                      "description": "Condition expression for a `doWhile` loop.",
                      "type": "string"
                    },
                    "enabled": {
                      "description": "Whether the loop runs.",
                      "type": "boolean"
                    },
                    "locked": {
                      "description": "Whether the loop is locked against edits.",
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "id",
                    "nodes",
                    "iterations",
                    "loopType"
                  ],
                  "additionalProperties": false,
                  "title": "Workflow loop",
                  "description": "A loop container derived from the workflow blocks."
                },
                "description": "Loop containers keyed by container id; always present, `{}` when there are none."
              },
              "parallels": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Parallel container identifier; equal to the parallel block id."
                    },
                    "nodes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Block ids inside the parallel."
                    },
                    "distribution": {
                      "description": "Items distributed across branches, or the expression producing them.",
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "description": "One item distributed to a branch."
                          }
                        },
                        {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "description": "One item distributed to a branch."
                          }
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "count": {
                      "description": "Fixed branch count.",
                      "type": "number"
                    },
                    "parallelType": {
                      "description": "Parallel kind.",
                      "type": "string",
                      "enum": [
                        "count",
                        "collection"
                      ]
                    },
                    "batchSize": {
                      "description": "Maximum concurrent branches.",
                      "type": "number"
                    },
                    "enabled": {
                      "description": "Whether the parallel runs.",
                      "type": "boolean"
                    },
                    "locked": {
                      "description": "Whether the parallel is locked against edits.",
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "id",
                    "nodes"
                  ],
                  "additionalProperties": false,
                  "title": "Workflow parallel",
                  "description": "A parallel container derived from the workflow blocks."
                },
                "description": "Parallel containers keyed by container id; always present, `{}` when there are none."
              },
              "variables": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Variable identifier."
                    },
                    "name": {
                      "type": "string",
                      "description": "Variable name, referenced from block inputs."
                    },
                    "type": {
                      "default": "string",
                      "description": "Declared variable type.",
                      "type": "string",
                      "enum": [
                        "string",
                        "number",
                        "boolean",
                        "object",
                        "array",
                        "plain"
                      ]
                    },
                    "value": {
                      "description": "Variable value; free-form and validated per `type` at use time."
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "type",
                    "value"
                  ],
                  "additionalProperties": false,
                  "title": "Workflow variable",
                  "description": "A workflow-scoped variable."
                },
                "description": "Workflow variables keyed by variable id; always present, `{}` when there are none."
              }
            },
            "required": [
              "blocks",
              "edges",
              "loops",
              "parallels",
              "variables"
            ],
            "additionalProperties": false,
            "title": "Workflow graph",
            "description": "Response data."
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false,
        "title": "Workflow state response",
        "description": "The editable draft graph of a workflow.",
        "examples": [
          {
            "data": {
              "blocks": {},
              "edges": [],
              "loops": {},
              "parallels": {},
              "variables": {}
            }
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Response example 1",
          "value": {
            "data": {
              "blocks": {},
              "edges": [],
              "loops": {},
              "parallels": {},
              "variables": {}
            }
          }
        }
      }
    }
  }
}

```

### 400

```json

{
  "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "BAD_REQUEST",
          "message": "Invalid request"
        }
      }
    }
  }
}

```

### 401

```json

{
  "description": "The API credential is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "UNAUTHORIZED",
          "message": "Authentication required"
        }
      }
    }
  }
}

```

### 403

```json

{
  "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "FORBIDDEN",
          "message": "Insufficient workspace permissions",
          "details": {
            "code": "INSUFFICIENT_WORKSPACE_ROLE"
          }
        }
      }
    }
  }
}

```

### 404

```json

{
  "description": "The requested resource was not found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "NOT_FOUND",
          "message": "Not found"
        }
      }
    }
  }
}

```

### 429

```json

{
  "description": "The caller exceeded the request rate limit.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "RATE_LIMITED",
          "message": "API rate limit exceeded",
          "details": {
            "retryAfter": "2026-01-01T00:00:30.000Z"
          }
        }
      }
    }
  }
}

```

### 500

```json

{
  "description": "An unexpected server error occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "INTERNAL_ERROR",
          "message": "Internal server error"
        }
      }
    }
  }
}

```

### 503

```json

{
  "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "Service temporarily unavailable"
        }
      }
    }
  }
}

```

## Referenced schemas

The following definitions preserve recursive references and composition exactly.

```json

{
  "#/components/headers/X-RateLimit-Limit": {
    "description": "Maximum requests allowed in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit",
      "description": "Maximum requests allowed in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Remaining": {
    "description": "Requests remaining in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit remaining",
      "description": "Requests remaining in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Reset": {
    "description": "ISO 8601 timestamp when the current rate-limit window resets.",
    "schema": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "title": "Rate limit reset",
      "description": "ISO 8601 timestamp when the current rate-limit window resets."
    }
  },
  "#/components/schemas/WorkflowStateResponse": {
    "type": "object",
    "properties": {
      "data": {
        "description": "Response data.",
        "$ref": "#/components/schemas/WorkflowGraph"
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false,
    "title": "Workflow state response",
    "description": "The editable draft graph of a workflow.",
    "examples": [
      {
        "data": {
          "blocks": {},
          "edges": [],
          "loops": {},
          "parallels": {},
          "variables": {}
        }
      }
    ]
  },
  "#/components/schemas/WorkflowGraph": {
    "type": "object",
    "properties": {
      "blocks": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/WorkflowBlock"
        },
        "description": "Blocks keyed by block id."
      },
      "edges": {
        "maxItems": 10000,
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/WorkflowEdge"
        },
        "description": "Directed connections between blocks."
      },
      "loops": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/WorkflowLoop"
        },
        "description": "Loop containers keyed by container id; always present, `{}` when there are none."
      },
      "parallels": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/WorkflowParallel"
        },
        "description": "Parallel containers keyed by container id; always present, `{}` when there are none."
      },
      "variables": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/WorkflowVariable"
        },
        "description": "Workflow variables keyed by variable id; always present, `{}` when there are none."
      }
    },
    "required": [
      "blocks",
      "edges",
      "loops",
      "parallels",
      "variables"
    ],
    "additionalProperties": false,
    "title": "Workflow graph",
    "description": "Response data."
  },
  "#/components/schemas/WorkflowBlock": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "Block identifier, unique within the workflow."
      },
      "type": {
        "type": "string",
        "description": "Registered block type."
      },
      "name": {
        "type": "string",
        "description": "Block display name; must be unique within the workflow."
      },
      "position": {
        "type": "object",
        "properties": {
          "x": {
            "type": "number",
            "description": "Canvas x coordinate."
          },
          "y": {
            "type": "number",
            "description": "Canvas y coordinate."
          }
        },
        "required": [
          "x",
          "y"
        ],
        "additionalProperties": false,
        "description": "Canvas coordinates of a block."
      },
      "subBlocks": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1,
              "description": "Sub-block identifier."
            },
            "type": {
              "type": "string",
              "minLength": 1,
              "description": "Sub-block input type."
            },
            "value": {
              "description": "Configured value; shape depends on the sub-block type."
            }
          },
          "required": [
            "id",
            "type",
            "value"
          ],
          "additionalProperties": false,
          "description": "One configurable input on a block."
        },
        "description": "Configured inputs keyed by sub-block id."
      },
      "outputs": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "description": "Declared shape of one output; depends on the block type."
        },
        "description": "Declared output shape keyed by output name."
      },
      "enabled": {
        "type": "boolean",
        "description": "Whether the block runs."
      },
      "horizontalHandles": {
        "description": "Whether edge handles render horizontally.",
        "type": "boolean"
      },
      "height": {
        "description": "Rendered block height.",
        "type": "number"
      },
      "advancedMode": {
        "description": "Whether the block is edited in advanced mode.",
        "type": "boolean"
      },
      "errorEnabled": {
        "description": "Whether the block exposes an error branch.",
        "type": "boolean"
      },
      "retry": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether the block retries on failure."
          },
          "maxTries": {
            "type": "integer",
            "minimum": 2,
            "maximum": 5,
            "description": "Total attempts, including the first."
          },
          "waitBetweenTriesMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5000,
            "description": "Delay between attempts, in milliseconds."
          }
        },
        "required": [
          "enabled",
          "maxTries",
          "waitBetweenTriesMs"
        ],
        "additionalProperties": false,
        "description": "Per-block retry configuration."
      },
      "triggerMode": {
        "description": "Whether the block acts as the workflow trigger.",
        "type": "boolean"
      },
      "data": {
        "type": "object",
        "properties": {
          "parentId": {
            "description": "Identifier of the containing loop or parallel.",
            "type": "string"
          },
          "extent": {
            "description": "Constrains the block to its parent bounds.",
            "type": "string",
            "const": "parent"
          },
          "width": {
            "description": "Rendered container width.",
            "type": "number"
          },
          "height": {
            "description": "Rendered container height.",
            "type": "number"
          },
          "collection": {
            "description": "Items a forEach loop or collection parallel iterates."
          },
          "count": {
            "description": "Iteration count for a `for` loop or count parallel.",
            "type": "number"
          },
          "loopType": {
            "description": "Loop container kind.",
            "type": "string",
            "enum": [
              "for",
              "forEach",
              "while",
              "doWhile"
            ]
          },
          "whileCondition": {
            "description": "Condition expression for a `while` loop.",
            "type": "string"
          },
          "doWhileCondition": {
            "description": "Condition expression for a `doWhile` loop.",
            "type": "string"
          },
          "parallelType": {
            "description": "Parallel container kind.",
            "type": "string",
            "enum": [
              "collection",
              "count"
            ]
          },
          "batchSize": {
            "description": "Maximum concurrent branches of a parallel.",
            "type": "number"
          },
          "type": {
            "description": "Container subtype.",
            "type": "string"
          },
          "canonicalModes": {
            "description": "Per-field editing mode, keyed by canonical parameter id.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string",
              "enum": [
                "basic",
                "advanced"
              ]
            }
          }
        },
        "additionalProperties": false,
        "description": "Container and layout metadata carried by a block."
      },
      "locked": {
        "description": "Whether the block is locked against edits.",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "type",
      "name",
      "position",
      "subBlocks",
      "outputs",
      "enabled"
    ],
    "additionalProperties": false,
    "title": "Workflow block",
    "description": "One node of a workflow graph and its configuration."
  },
  "#/components/schemas/WorkflowEdge": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "Edge identifier, unique within the workflow."
      },
      "source": {
        "type": "string",
        "minLength": 1,
        "description": "Source block id."
      },
      "target": {
        "type": "string",
        "minLength": 1,
        "description": "Target block id."
      },
      "sourceHandle": {
        "description": "Source port, or null for the block default.",
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "targetHandle": {
        "description": "Target port, or null for the block default.",
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "type": {
        "description": "Edge renderer type.",
        "type": "string"
      }
    },
    "required": [
      "id",
      "source",
      "target"
    ],
    "additionalProperties": false,
    "title": "Workflow edge",
    "description": "A directed connection between two blocks."
  },
  "#/components/schemas/WorkflowLoop": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Loop container identifier; equal to the loop block id."
      },
      "nodes": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Block ids inside the loop."
      },
      "iterations": {
        "type": "number",
        "description": "Resolved iteration count."
      },
      "loopType": {
        "type": "string",
        "enum": [
          "for",
          "forEach",
          "while",
          "doWhile"
        ],
        "description": "Loop kind."
      },
      "forEachItems": {
        "description": "Items a forEach loop iterates, or the expression producing them.",
        "anyOf": [
          {
            "type": "array",
            "items": {
              "description": "One item the loop iterates."
            }
          },
          {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "description": "One item the loop iterates."
            }
          },
          {
            "type": "string"
          }
        ]
      },
      "whileCondition": {
        "description": "Condition expression for a `while` loop.",
        "type": "string"
      },
      "doWhileCondition": {
        "description": "Condition expression for a `doWhile` loop.",
        "type": "string"
      },
      "enabled": {
        "description": "Whether the loop runs.",
        "type": "boolean"
      },
      "locked": {
        "description": "Whether the loop is locked against edits.",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "nodes",
      "iterations",
      "loopType"
    ],
    "additionalProperties": false,
    "title": "Workflow loop",
    "description": "A loop container derived from the workflow blocks."
  },
  "#/components/schemas/WorkflowParallel": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Parallel container identifier; equal to the parallel block id."
      },
      "nodes": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Block ids inside the parallel."
      },
      "distribution": {
        "description": "Items distributed across branches, or the expression producing them.",
        "anyOf": [
          {
            "type": "array",
            "items": {
              "description": "One item distributed to a branch."
            }
          },
          {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "description": "One item distributed to a branch."
            }
          },
          {
            "type": "string"
          }
        ]
      },
      "count": {
        "description": "Fixed branch count.",
        "type": "number"
      },
      "parallelType": {
        "description": "Parallel kind.",
        "type": "string",
        "enum": [
          "count",
          "collection"
        ]
      },
      "batchSize": {
        "description": "Maximum concurrent branches.",
        "type": "number"
      },
      "enabled": {
        "description": "Whether the parallel runs.",
        "type": "boolean"
      },
      "locked": {
        "description": "Whether the parallel is locked against edits.",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "nodes"
    ],
    "additionalProperties": false,
    "title": "Workflow parallel",
    "description": "A parallel container derived from the workflow blocks."
  },
  "#/components/schemas/WorkflowVariable": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "Variable identifier."
      },
      "name": {
        "type": "string",
        "description": "Variable name, referenced from block inputs."
      },
      "type": {
        "default": "string",
        "description": "Declared variable type.",
        "type": "string",
        "enum": [
          "string",
          "number",
          "boolean",
          "object",
          "array",
          "plain"
        ]
      },
      "value": {
        "description": "Variable value; free-form and validated per `type` at use time."
      }
    },
    "required": [
      "id",
      "name",
      "type",
      "value"
    ],
    "additionalProperties": false,
    "title": "Workflow variable",
    "description": "A workflow-scoped variable."
  },
  "#/components/responses/BadRequest": {
    "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "BAD_REQUEST",
            "message": "Invalid request"
          }
        }
      }
    }
  },
  "#/components/schemas/V2Error": {
    "type": "object",
    "properties": {
      "error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the error."
          },
          "details": {
            "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/V2ActionableForbiddenDetails"
              },
              {
                "description": "Other structured context defined by the specific error."
              }
            ]
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false,
        "description": "Canonical error details."
      }
    },
    "required": [
      "error"
    ],
    "additionalProperties": false,
    "title": "v2 error response",
    "description": "Canonical error envelope returned by the public v2 API.",
    "examples": [
      {
        "error": {
          "code": "BAD_REQUEST",
          "message": "The request is invalid."
        }
      }
    ]
  },
  "#/components/schemas/V2ActionableForbiddenDetails": {
    "type": "object",
    "properties": {
      "code": {
        "$ref": "#/components/schemas/V2ForbiddenDetailCode"
      }
    },
    "required": [
      "code"
    ],
    "additionalProperties": {
      "description": "Additional context for this refusal."
    },
    "title": "Actionable forbidden details",
    "description": "Machine-readable cause and optional context for an actionable `403` response."
  },
  "#/components/schemas/V2ForbiddenDetailCode": {
    "type": "string",
    "enum": [
      "INSUFFICIENT_WORKSPACE_ROLE",
      "PERSONAL_API_KEYS_DISABLED",
      "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
      "PRINCIPAL_KIND_NOT_PERMITTED",
      "ORGANIZATION_MEMBERSHIP_REQUIRED",
      "ORGANIZATION_ADMIN_REQUIRED",
      "ENTERPRISE_PLAN_REQUIRED",
      "SSO_DISABLED",
      "SSO_DOMAIN_NOT_VERIFIED",
      "SSO_PROVIDER_LIMIT_REACHED",
      "ORGANIZATION_PLAN_REQUIRED",
      "AUDIT_LOGS_DISABLED",
      "ACCESS_REQUESTS_DISABLED",
      "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
      "SKILL_EDITOR_ACCESS_REQUIRED",
      "SECRET_ADMIN_ACCESS_REQUIRED",
      "WORKSPACE_RESOURCE_LIMIT_REACHED",
      "PUBLIC_SHARING_NOT_ALLOWED",
      "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
      "MCP_SERVER_URL_NOT_ALLOWED",
      "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
      "CHAT_AUTH_MODE_NOT_PERMITTED",
      "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
      "PERMISSION_GROUP_CAPABILITY_BLOCKED",
      "INTEGRATION_NOT_ALLOWED",
      "INSUFFICIENT_SCOPE",
      "SCIM_MANAGED_MEMBERSHIP"
    ],
    "title": "Forbidden detail code",
    "description": "Stable cause code for an actionable `403` response."
  },
  "#/components/responses/Unauthorized": {
    "description": "The API credential is missing or invalid.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "UNAUTHORIZED",
            "message": "Authentication required"
          }
        }
      }
    }
  },
  "#/components/responses/Forbidden": {
    "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "FORBIDDEN",
            "message": "Insufficient workspace permissions",
            "details": {
              "code": "INSUFFICIENT_WORKSPACE_ROLE"
            }
          }
        }
      }
    }
  },
  "#/components/responses/NotFound": {
    "description": "The requested resource was not found.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "NOT_FOUND",
            "message": "Not found"
          }
        }
      }
    }
  },
  "#/components/responses/RateLimited": {
    "description": "The caller exceeded the request rate limit.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "RATE_LIMITED",
            "message": "API rate limit exceeded",
            "details": {
              "retryAfter": "2026-01-01T00:00:30.000Z"
            }
          }
        }
      }
    }
  },
  "#/components/headers/Retry-After": {
    "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Retry after",
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
    }
  },
  "#/components/responses/InternalError": {
    "description": "An unexpected server error occurred.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "INTERNAL_ERROR",
            "message": "Internal server error"
          }
        }
      }
    }
  },
  "#/components/responses/ServiceUnavailable": {
    "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "SERVICE_UNAVAILABLE",
            "message": "Service temporarily unavailable"
          }
        }
      }
    }
  }
}

```

[Download OpenAPI specification](/openapi.json)

Source: `openapi-v2-workflows.json`, operation `getWorkflowState`.