Replace workflow state

PUT/api/v2/workflows/{workflowId}/state

Replace the draft graph in one write. Requires workspace write access. Concurrent row-locked writes are last-write-wins; IDs owned by another workflow return 409. Deployments, schedules, and webhook registrations are unchanged. Deploy to serve the edits.

Lint is advisory. Use dryRun=true to validate without saving, auditing, or notifying collaborators. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:write.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:write

OAuth flows

json

{
  "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"
    }
  }
}

OAuth scope: api:write.

Path parameters

workflowIdstringRequired

Unique workflow identifier.

minLength: 1

Query parameters

dryRunboolean

Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (409) as a committed write. needsRedeployment describes the pre-write state. For semantic operations, mintedBlockIds is empty; previewBlockIds contains provisional IDs with a warning, since committing mints new IDs.

Request body

Required

A complete replacement draft graph for a workflow.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

A complete replacement draft graph for a workflow.

5 fields

blocksobjectRequired

Blocks keyed by block id.

Schema details

Additional propertiesobject

One node of a workflow graph and its configuration.

15 fields

idstringRequired

Block identifier, unique within the workflow.

minLength: 1

typestringRequired

Registered block type.

minLength: 1

namestringRequired

Block display name; must be unique within the workflow.

minLength: 1
maxLength: 255

positionobjectRequired

Canvas coordinates of a block.

2 fields

xnumberRequired

Canvas x coordinate.

ynumberRequired

Canvas y coordinate.

subBlocksobjectRequired

Configured inputs keyed by sub-block id.

Schema details

Additional propertiesobject

One configurable input on a block.

3 fields

idstringRequired

Sub-block identifier.

minLength: 1

typestringRequired

Sub-block input type.

minLength: 1

valuevalueRequired

Configured value; shape depends on the sub-block type.

outputsobjectRequired

Declared output shape keyed by output name.

Schema details

Additional propertiesvalue

Declared shape of one output; depends on the block type.

enabledbooleanRequired

Whether the block runs.

horizontalHandlesboolean

Whether edge handles render horizontally.

heightnumber

Rendered block height.

advancedModeboolean

Whether the block is edited in advanced mode.

errorEnabledboolean

Whether the block exposes an error branch.

retryobject

Per-block retry configuration.

3 fields

enabledbooleanRequired

Whether the block retries on failure.

maxTriesintegerRequired

Total attempts, including the first.

minimum: 2
maximum: 5

waitBetweenTriesMsintegerRequired

Delay between attempts, in milliseconds.

minimum: 0
maximum: 5000

triggerModeboolean

Whether the block acts as the workflow trigger.

dataobject

Container and layout metadata carried by a block.

13 fields

parentIdstring

Identifier of the containing loop or parallel.

extentstring

Constrains the block to its parent bounds.

const: parent

widthnumber

Rendered container width.

heightnumber

Rendered container height.

collectionvalue

Items a forEach loop or collection parallel iterates.

countnumber

Iteration count for a for loop or count parallel.

loopTypestring

Loop container kind.

enum: ["for","forEach","while","doWhile"]

whileConditionstring

Condition expression for a while loop.

doWhileConditionstring

Condition expression for a doWhile loop.

parallelTypestring

Parallel container kind.

enum: ["collection","count"]

batchSizenumber

Maximum concurrent branches of a parallel.

typestring

Container subtype.

canonicalModesobject

Per-field editing mode, keyed by canonical parameter id.

Schema details

Additional propertiesstring

enum: ["basic","advanced"]

lockedboolean

Whether the block is locked against edits.

edgesarrayRequired

Directed connections between blocks.

maxItems: 10000

Schema details

Array itemobject

A directed connection between two blocks.

6 fields

idstringRequired

Edge identifier, unique within the workflow.

minLength: 1

sourcestringRequired

Source block id.

minLength: 1

targetstringRequired

Target block id.

minLength: 1

sourceHandlevalue

Source port, or null for the block default.

Schema details

Any of

Option 1string

Option 2null

targetHandlevalue

Target port, or null for the block default.

Schema details

Any of

Option 1string

Option 2null

typestring

Edge renderer type.

loopsobject

Ignored on write: loop containers are recomputed from blocks.

Schema details

Additional propertiesobject

A loop container derived from the workflow blocks.

9 fields

idstringRequired

Loop container identifier; equal to the loop block id.

nodesarrayRequired

Block ids inside the loop.

Schema details

Array itemstring

iterationsnumberRequired

Resolved iteration count.

loopTypestringRequired

Loop kind.

enum: ["for","forEach","while","doWhile"]

forEachItemsvalue

Items a forEach loop iterates, or the expression producing them.

Schema details

Any of

Option 1array

Schema details

Array itemvalue

One item the loop iterates.

Option 2object

Schema details

Additional propertiesvalue

One item the loop iterates.

Option 3string

whileConditionstring

Condition expression for a while loop.

doWhileConditionstring

Condition expression for a doWhile loop.

enabledboolean

Whether the loop runs.

lockedboolean

Whether the loop is locked against edits.

parallelsobject

Ignored on write: parallel containers are recomputed from blocks.

Schema details

Additional propertiesobject

A parallel container derived from the workflow blocks.

8 fields

idstringRequired

Parallel container identifier; equal to the parallel block id.

nodesarrayRequired

Block ids inside the parallel.

Schema details

Array itemstring

distributionvalue

Items distributed across branches, or the expression producing them.

Schema details

Any of

Option 1array

Schema details

Array itemvalue

One item distributed to a branch.

Option 2object

Schema details

Additional propertiesvalue

One item distributed to a branch.

Option 3string

countnumber

Fixed branch count.

parallelTypestring

Parallel kind.

enum: ["count","collection"]

batchSizenumber

Maximum concurrent branches.

enabledboolean

Whether the parallel runs.

lockedboolean

Whether the parallel is locked against edits.

variablesobject

Replacement variable set. Omit to leave the stored variables untouched.

Schema details

Additional propertiesobject

A workflow-scoped variable.

4 fields

idstringRequired

Variable identifier.

minLength: 1

namestringRequired

Variable name, referenced from block inputs.

minLength: 1
maxLength: 255

typestringRequired

Declared variable type.

enum: ["string","number","boolean","object","array","plain"]

valuevalueRequired

Variable value; free-form and validated per type at use time.

Additional properties are not allowed.

Request example 1

json

{
  "blocks": {},
  "edges": []
}

Responses

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

The draft graph was replaced.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Outcome of replacing a workflow draft graph.

1 field

dataobjectRequired

Response data.

5 fields

idstringRequired

Identifier of the workflow whose draft graph was written.

warningsarrayRequired

Non-fatal notes about blocks and edges that were normalized or dropped before persistence. Empty when there was nothing to report.

Schema details

Array itemstring

needsRedeploymentbooleanRequired

Whether the live deployment differs from the draft. A graph write never changes what the deployed endpoint serves; deploy to publish it. On a dry run, this describes the state before the proposed write.

lintobjectRequired

Advisory findings about a saved graph. Findings never block a write or a deploy; they tell a caller what will misbehave at run time.

11 fields

sourcesarrayRequired

Blocks with no incoming edge. A trigger block is naturally a source; anything else here is unreachable.

Schema details

Array itemobject

3 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

Additional properties are not allowed.

sinksarrayRequired

Blocks with no outgoing edge.

Schema details

Array itemobject

3 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

Additional properties are not allowed.

orphanBlocksarrayRequired

Blocks with neither an incoming nor an outgoing edge.

Schema details

Array itemobject

3 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

Additional properties are not allowed.

emptyOutgoingPortsarrayRequired

Branch and container ports that lead nowhere.

Schema details

Array itemobject

5 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

handlestringRequired

Source handle with nothing connected to it.

labelstringRequired

Human-readable name of the port.

Additional properties are not allowed.

invalidBranchPortsarrayRequired

Condition and router edges whose source handle names no real branch.

Schema details

Array itemobject

5 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

sourceHandlestringRequired

Source handle that does not match the block.

reasonstringRequired

Why the handle is not valid for this block.

Additional properties are not allowed.

invalidConnectionTargetsarrayRequired

Edges pointing at a block that cannot legally receive them.

Schema details

Array itemobject

5 fields

sourceBlockIdstringRequired

Block the edge leaves.

sourceBlockNamevalueRequired

Display name of the source block.

Schema details

Any of

Option 1string

Option 2null

sourceHandlevalueRequired

Handle the edge leaves from.

Schema details

Any of

Option 1string

Option 2null

targetBlockIdstringRequired

Block the edge points at.

reasonstringRequired

Why the target is not a legal destination.

Additional properties are not allowed.

fieldIssuesarrayRequired

Per-block configuration problems. The most actionable part of the report for a headless graph builder: a block missing a required field will fail at run time.

Schema details

Array itemobject

5 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

missingRequiredFieldsarrayRequired

Required sub-block fields that resolve empty in the active mode.

Schema details

Array itemstring

inactiveModeValuesarrayRequired

Values stranded on the inactive member of a canonical pair.

Schema details

Array itemobject

4 fields

canonicalIdstringRequired

Canonical parameter the two sub-block modes share.

activeMemberIdvalueRequired

Sub-block the runtime reads, where the value should live.

Schema details

Any of

Option 1string

Option 2null

inactiveMemberIdstringRequired

Sub-block holding the stranded value, which the runtime ignores.

kindstringRequired

What kind of value is stranded.

enum: ["credential","resource","other"]

Additional properties are not allowed.

unresolvedReferencesarrayRequired

Credential, resource, tool, and skill references that do not resolve; block-output references that will not work as written: a block that does not exist, or an output field the block does not have (reason unknown-field); and text outputs written unquoted in a JSON field (reason unquoted-json-string), which leave the field invalid JSON at run time unless the text is itself JSON. These values are still persisted; they are reported, not dropped.

Schema details

Array itemobject

7 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

fieldstringRequired

Sub-block field holding the reference.

valuevalueRequired

The reference, or references, that did not resolve.

Schema details

Any of

Option 1string

Option 2array

Schema details

Array itemstring

kindstringRequired

What kind of entity the reference was expected to name.

enum: ["credential","resource","custom-tool","mcp-tool","skill","block-output"]

reasonstringRequired

Why the reference does not resolve.

Additional properties are not allowed.

tableFieldIssuesarrayRequired

Table block filter and order fields checked against the bound table's live schema that name no column (nor the implicit id, createdAt, updatedAt). Such a run fails inside the block's error edge. A filter holding a <block.output> reference, or one that is not JSON, is not checked.

Schema details

Array itemobject

5 fields

blockIdstringRequired

Block the finding is about.

blockNamevalueRequired

Display name of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of the block, when it has one.

Schema details

Any of

Option 1string

Option 2null

fieldstringRequired

The filter or sort field that names no column.

tableNamestringRequired

Display name of the table the block is bound to.

Additional properties are not allowed.

manualRunIssuevalueRequired

Why a manual run from the editor's Run button would be refused before it starts: no enabled trigger it can start from, more than one API trigger, or a selected trigger with no outgoing connection. The API run endpoints do not apply these checks. null when no manual-run issue is reported: the run can begin, only a chat trigger can start the workflow, or the graph is empty (reported in notes instead).

Schema details

Any of

Option 1object

5 fields

reasonstringRequired

Why the run is refused.

enum: ["no-trigger","multiple-api-triggers","trigger-not-connected"]

messagestringRequired

The error the manual run raises.

blockIdvalueRequired

Trigger the run would start from, when the problem is that trigger.

Schema details

Any of

Option 1string

Option 2null

blockNamevalueRequired

Display name of that trigger.

Schema details

Any of

Option 1string

Option 2null

blockTypevalueRequired

Registered type of that trigger.

Schema details

Any of

Option 1string

Option 2null

Additional properties are not allowed.

Option 2null

notesarrayRequired

Advisory notes about the report itself.

Schema details

Array itemstring

Additional properties are not allowed.

dryRunbooleanRequired

Whether this request only validated. true means nothing was persisted; the findings describe what a committed write of the same body would produce.

Additional properties are not allowed.

Response example 1

json

{
  "data": {
    "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
    "warnings": [],
    "needsRedeployment": true,
    "dryRun": false,
    "lint": {
      "sources": [],
      "sinks": [],
      "orphanBlocks": [],
      "emptyOutgoingPorts": [],
      "invalidBranchPorts": [],
      "invalidConnectionTargets": [],
      "fieldIssues": [],
      "unresolvedReferences": [],
      "tableFieldIssues": [],
      "manualRunIssue": null,
      "notes": []
    }
  }
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum: 0
maximum: 9007199254740991

X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum: 0
maximum: 9007199254740991

X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

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))$

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.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}

The API credential is missing or invalid.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

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.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}

The requested resource was not found.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}

The request conflicts with current resource state.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "CONFLICT",
    "message": "The request conflicts with current resource state"
  }
}

The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}

The request uses an unsupported media type.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Request body must be sent as application/json"
  }
}

The resource is temporarily locked or unavailable; retry the request.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "LOCKED",
    "message": "Workflow is locked"
  }
}

The caller exceeded the request rate limit.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}

Response headers

Retry-Afterinteger

Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.

minimum: 0
maximum: 9007199254740991

An unexpected server error occurred.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

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.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Response headers

Retry-Afterinteger

Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.

minimum: 0
maximum: 9007199254740991

Authentication

Path parameters

Query parameters

Request body

Request example 1

Responses

200

Response example 1

Response headers

400

401

403

404

409

413

415

423

429

Response headers

500

503

Response headers