opensource/sim
3
0
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-09-24 15:45:35 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
ed60fbaa4e37185fe75605da95cb075f5ae089e8
sim/apps/docs/openapi-v2-workflows.json
T
WaleedandTheodore Li 656840a1b1 feat(api): make the platform operable headless over v2 (#6912) 
* feat(v2): download run output files by API key

Adds GET /api/v2/workflows/{id}/runs/{runId}/files/{fileId}, closing the
async-run loop for headless callers. A run's output carries UserFile URLs
pointing at /api/files/serve/..., which rejects x-api-key outright, so an
async run that produces a file previously had no byte path out for an API
key at all.

The file is addressed by the id the run reported and resolved against the
run's own recorded execution data, from which the storage key is read. The
request never supplies a storage key, so the endpoint cannot be aimed at
bytes the run did not produce. Resolution deliberately reads the
materialized-but-undisplayed recording, because the display projection
strips exactly the `key`/`context` fields a byte read needs.

Also hardens normalizeStartFile to derive a file's storage key only from a
validated internal serve URL, discarding any caller-supplied `key`/`context`.
A workspace API key has no human subject, so the executor resolves its actor
to the workspace billing owner (preprocessing.ts -> resolveSystemBillingAttribution);
verifyFileAccess then authorizes a workspace-context key as that owner, whose
reach is not bounded by the key's workspace. Accepting an attacker-authorable
key made that substitution exploitable as a confused deputy. Normalization is
all-or-nothing, so a forged file now drops the whole files input.

* feat(workflows): one graph-write door, principal-derived audit source, and v2 authoring endpoints

Extract replaceWorkflowNormalizedState as the single persistence primitive for a
workflow graph replace and route both the internal editor save and the Copilot
edit tool through it, so neither can skip state preparation, the row lock, the
lastSynced stamp, or custom-tool extraction by choosing a different entry point.

Derive the audit source from the acting principal instead of hardcoding
'copilot', then widen workflows.variables.apply_operations and
workflows.bulk.move to every principal kind.

Add GET/PUT /api/v2/workflows/{id}/state, POST /operations, /duplicate,
/restore, PATCH /variables, and POST /api/v2/workflows/move over surface-neutral
application use cases; move the edit engine to lib/workflows/editing.

* test(workflows): cover the graph-write primitive, audit source, and the v2 authoring surface

Pin the two-doors fix (preparation runs, the row is locked, custom-tool
extraction is post-commit and best-effort) and the false-audit fix (a session
principal writes source: 'session', a delegated one writes its service). Both
were verified to fail with the fix reverted.

Add the application matrix for replaceWorkflowState, applyWorkflowOperations,
readWorkflowGraph, and restoreWorkflow — role floor, principal-kind rejection
before canonical load, asserted-scope concealment, lock, validation, atomic
conflict, plan gate, and audit-then-notify ordering — plus route tests for
every new endpoint.

* test(workflows): pin the internal graph-write door and the v2 list scope

Characterize saveWorkflowNormalizedState's statuses, messages, and notification
after the persistence extraction, and cover the new scope filter on
GET /api/v2/workflows including a cursor replayed under a different scope.

* feat(api): add v2 block, tool, connector-type, and enrichment catalogs

Adds six read endpoints under /api/v2 that publish Sim's code-defined
catalogs: GET /blocks, GET /blocks/{blockId}, GET /tools,
GET /tools/{toolId}, GET /connector-types, and GET /enrichments.

These read like static reference data and are not. What a caller may
place is decided per workspace by its permission-group integration
allowlist, per organization by which unreleased blocks have been
revealed, per deployment by ALLOWED_INTEGRATIONS, and per workspace
again by the workflows it has deployed as blocks. So all six are plain
defineWorkspaceOperation reads at minimumRole 'read' with
workspaceApiKey 'allow' — the exact policy of credentials.providers.list
— and every response keeps Cache-Control: private, no-store, because an
unrevealed preview block's existence must not leak across organizations
through a shared cache.

Trigger blocks ride as ?capability=trigger rather than a second
endpoint, and workspace custom blocks ride inside /blocks discriminated
by `source`, so "what may I place?" stays a one-call question.

The block projection is extracted out of the Copilot get_blocks_metadata
tool and rewritten onto @/tools/metadata and @/tools/metadata-outputs.
That cuts the tool's own @/tools/registry edge as a side effect: its
module graph drops from 6,756 to 1,318, and the new routes land at
1,673-1,734, next to the shipped /v2/credentials/providers baseline of
1,668.

Supporting changes:

- scripts/sync-tool-metadata.ts derives hostedApiKey ('always' |
  'conditional' | 'none') from each tool's `hosting`. The config itself
  stays excluded because it holds closures, but "does Sim host the key"
  is a first-order authoring question, so the answer is emitted.
- getCopilotToolDescription takes hostedApiKey as an option instead of
  reading `hosting` off the tool, so both an executable ToolConfig and
  the generated metadata can answer it through one shared derivation.
- principalUserId / allowedIntegrationTypes move out of
  lib/credentials/application/provider-catalog.ts into
  lib/integrations/principal-scope.server.ts. Two copies of the
  workspace integration gate would diverge first on the workspace-key
  path, which has no user for permission groups to key on.
- scripts/check-tool-registry-boundary.ts walked page.tsx/layout.tsx
  under app/workspace only, so a route importing the executable registry
  passed green. It now walks a list of entry sources, seeded with the
  four catalog route subtrees and the shared projection barrel. Routes
  are covered per subtree rather than wholesale because 122 of ~1,130
  route files legitimately execute tools.

Registry sweeps parse every block, tool, connector type, and enrichment
through its published response schema and compare against the wire
round-trip. They caught a real drift while being written: an operation's
inputs were typed as a union of the tool-param and block-input shapes,
and the union resolved to whichever member matched first, silently
dropping a block input's `schema`.

* docs(api): stop publishing a 413 GET /workflows/{id}/state cannot emit

* feat(v2): read upload-session state

Adds GET /api/v2/files/uploads/{uploadId}. Only DELETE was exported, so a
caller that lost track of a transfer could abort it but could not ask
whether the session was still alive, already finalized, or failed — the
resume story was missing.

Runs on a new files.upload.read operation at minimumRole 'read' rather than
reusing uploadCancel, which is a 'write': asking about a session must not
require permission to destroy it. The GET is a control leg like every other,
so it carries the signed upload token and re-authorizes the caller's present
workspace permission through reauthorizeWorkspaceUploadPurpose instead of
resolving the session on its id alone.

* fix(api): reconcile v2 catalog and workflow-authoring integration

Merging the catalog and workflow-authoring branches surfaced four issues
that neither produced in isolation.

- Route and OpenAPI counters were bumped to the same value on both
  branches, so git merged them as one change while the merged tree holds
  the sum. Corrects the route ratchet to 1142 and the workflows document
  to 29 operations (152 total), then regenerates the OpenAPI documents
  and the CLI surface from the reconciled contracts.
- The seven new workflow operations were published in the spec but absent
  from the workflow API reference groups, which `check:openapi` rejects.
- `route-policies.ts` reached `WorkflowOperationsNotAppliedError` through
  `apply-workflow-operations`, dragging the edit engine — and its diff and
  comparison dependencies, which reach a client OAuth hook — into every
  route that uses the shared workflow error policies. The class moves to
  its own leaf module, mirroring `WorkflowImportError`, and each importer
  now takes it from there.
- The operations route test shadowed that class inside its module mock, so
  `instanceof` matched a fake and the assertion pinned a message the
  production class never emits. It now uses the real class and asserts the
  real message.

* feat(v2): extract ZIP archives over the public API

Adds POST /api/v2/files/{fileId}/extract and widens files.extract_archive
from principalKinds ['session'] / workspaceApiKey 'deny' to admit personal
and workspace API keys at the unchanged 'write' role.

The widening is an authorization change, so the justification lives in the
operation's TSDoc: extraction grants no capability an API key lacks, since
every file it writes could be created one at a time through files.create and
files.upload.create, both already 'allow' at the same role. It only collapses
many calls into one. The previous ['session'] restriction read as an artifact
of the UI having been the only caller. Delegated services stay out — no
copilot or executor caller exists and admitting one is a separate decision.

The response is counts plus the destination folderPath, never the extracted
files: a large archive would otherwise materialize thousands of objects into
one body. Callers page GET /api/v2/files?folderPath=... instead. The use case
returns the internal display path and the adapter projects it to a v2 path,
keeping the use case surface-neutral.

* feat(v2): extract file text over the public API

Adds GET /api/v2/files/{fileId}/text. Text extraction previously sat behind
checkInternalAuth on /api/files/parse, a route that also mixes in external-URL
fetching, execution-file upload, and multi-file aggregation, so it could not be
reused. The parse call is lifted into a thin application use case instead.

Runs on the existing files.read_content operation unchanged — it is already
workspaceApiKey 'allow' at the read role, and turning bytes it already
authorizes into text grants no further reach.

`degraded` is a required, non-optional boolean on the response. The legacy doc
and ppt parsers deliberately return best-effort or placeholder content rather
than throwing, so an omittable flag would let a client that never checks it
treat guessed text as extracted text. It is reported honestly rather than
converted into an error, because the parsers' behaviour is deliberate and
characterization-tested.

The read is bounded on its input at 25 MiB before extraction rather than on its
output after, given the parsers' documented DoS history; a caller may lower the
ceiling but never raise it.

* feat(v2): restore archived folders and list the archived set

DELETE /api/v2/files/folders archives recursively, so a recursive delete was
unrecoverable over the API: the archived files stayed visible through
GET /api/v2/files?scope=archived, but nothing could rebuild the folder
structure.

Adds POST /api/v2/files/folders/restore, path-addressed like the rest of the
v2 folder family, and a `scope` selector on the folder list so a caller can
find the archived path to hand it.

`scope` extends the files folder-list query rather than the shared
v2ListFoldersQuerySchema: only workspace files have an archived folder set, so
adding it to the shared schema would give tables, workflows, and knowledge a
parameter they ignore. GET /api/v2/files/folders is a FULL_SET_LIST, not paged,
so no cursor binding changes — list-pagination.test.ts passes unchanged.

Restore resolves the archived folder from its path by scanning the archived
set rather than walking the live tree, which by definition does not contain
the folder being restored. The folder-restored analytics hook now reports the
folder actually restored rather than the requested selector, which carries no
id on a path-addressed surface.

* feat(v2): bulk-download a file selection as a zip

Adds GET /api/v2/files/bulk-download, an adapter over the existing
downloadWorkspaceFileItems use case and its internal binary route.

Path collision: a static segment beside [fileId] permanently shadows a file
whose id equals it, and workspaceFileIdSchema does accept [A-Za-z0-9_-]+.
Rather than invent a new shape, this follows the existing bulk-delete sibling:
the hyphenated form cannot be produced by either minted id shape (UUID v4 or
wf_<shortId>), so the shadowed id is unreachable in practice. Documented on
the contract so the reasoning is not lost.

Folders are addressed by path, matching the rest of the v2 file surface. The
paths resolve against the folder set the selection already loads, so it costs
no extra query, and a path matching no folder is rejected rather than silently
dropped — a misspelled folder must not yield a zip of whatever else was
selected. The empty-selection and folder-count guards now account for
folderPaths, which a path-only selection would otherwise have tripped.

Selections are comma-separated only: v2 rejects a query parameter sent more
than once, so a repeated-parameter form would never reach the schema. Pinned by
a test so the contract cannot advertise a form the boundary rejects.

* feat(v2): expose run output files and optional inline bytes on the runs read

GET /api/v2/workflows/{id}/runs/{runId} now reports the files a run produced,
each with the downloadPath that fetches its bytes, and can inline them as
base64 on request.

Gated by includeOutput, matching `output`'s nullability: a caller that did not
ask for output does not receive a file list it did not request. The async
execute request's rejection of includeFileBase64 is deliberately left alone —
at submit time the run has not happened, so there is nothing to inline; reading
a finished run is the first moment the question means anything.

Inlining is capped per file at the executor's 16 MiB inline ceiling, which a
caller may lower but never raise. A file above it answers 413 naming that
file's downloadPath, so the caller is told exactly how to get the bytes rather
than being left stuck.

The descriptor deliberately omits the storage key — files are addressed by id
and the key is re-derived from the run's recording — and omits an expiry, which
the recording does not carry and which would be fabricated if published.

The route becomes headSafe: false, since inlining reads object storage. The
builder enforces that this requires the use case to expose authorize(), so HEAD
still answers from a real authorization rather than from authentication alone.

* feat(v2): permanently delete an archived file

DELETE /api/v2/files/{fileId} only archives — the OpenAPI says its stored bytes
are never removed — so there was no way to actually destroy a file over the API.
Adds the repository primitive, application use case, operation, and
DELETE /api/v2/files/{fileId}/permanent.

A distinct path rather than a flag on the ordinary delete: a query parameter
that turns a recoverable archive into an irreversible destruction is set by
accident, and the two acts carry different minimum roles, which one route
declaration cannot express. The file must already be archived; a live file
answers 409 naming the archive step, so no single request can turn a live file
into lost bytes.

minimumRole 'admin', which forces workspaceApiKey 'deny' since the workspace-key
ceiling is 'write' — the desired policy anyway: unattended credentials should
not destroy bytes.

Row first, then object. The two legs commit independently, so one can survive a
crash between them: deleting the row first leaves at most an orphaned object for
the storage sweep, while the reverse would leave a live row pointing at bytes
that no longer exist — a file that lists and opens but can never be read. A
failed object delete is therefore reported as objectDeleted: false rather than
thrown, because the request has genuinely succeeded once the row is gone. Both
directions are pinned by failure-injection tests, verified to fail when the
order is reversed.

Audited as a distinct FILE_PERMANENTLY_DELETED action, not a reuse of
FILE_DELETED, which records the recoverable archive step.

* feat(api): v2 log analytics, itemized cost, filters, and sortable query

Adds the aggregate and rich-read halves of the public logs surface, and
fixes three defects the existing reads carry.

Aggregate analytics. `GET /api/v2/logs/stats` returns time-bucketed run
counts, success rate, error count, mean latency, and the window bounds,
per workflow and for the workspace. The first-party route was a raw
handler with inline SQL and inline aggregation, so it is split into a
repository (`lib/logs/stats-queries.ts`), a pure aggregator
(`lib/logs/stats.ts`), and an application use case. That route keeps its
legacy authorization — it answers a caller without workspace access with
a zeroed 200, where v2 conceals the workspace as a 404 — and consumes
only the two surface-neutral halves.

`segmentCount` had no `.int()`, `.min()`, or `.max()`, so `0` divided by
zero and `1e9` allocated two billion-element arrays: both caller-reachable
500s. Bounded on both contracts. `workflows` is capped, with the workspace
totals still computed from every workflow and the cut reported as
`workflowsTruncated`.

Detail reads gain the itemized `cost.items` ledger (`null` and `[]` are
distinct answers and both reachable) and `workflowInput`, restoring a
v1→v2 regression.

The list gains `workflowName` and `status` filters, and `includeJobRuns`,
which unions Chat and Sim-agent job runs into the sequence behind a new
`kind` discriminator — without it a job run is indistinguishable from a
run whose workflow was deleted. A filter no job row can answer drops the
branch outright rather than meaning two things across the union.

`POST /api/v2/logs/query` carries the additional sort columns. `GET /logs`
is untouched: its single `order` param rests on there being exactly one
sortable column, and both escapes from that are ruled out, so the rich
read gets its own endpoint — the split the table surface already ships.
It uses the shared keyset scheme with the two nullable sort columns read
through a sentinel, since a keyset cannot compare against null.

`folderPaths` now covers a folder's whole subtree on the public path, as
it already did everywhere else; it previously omitted every nested run
with no error. The path strings did not change, so a folder-scope version
is stamped into the cursor and in-flight tokens restart rather than
silently skipping rows.

Also fixes `folderName`, which ILIKEd `workflow.name` — a copy of the
clause above it — and so searched workflow names instead of folders.

`buildLogSortCursorCondition`'s `IS NULL` disjunct is documented and
pinned: under `NULLS LAST` the null block is only reachable through it,
so removing it as a duplicate-row fix makes those runs unpageable.

Ratchets: route count 1142 -> 1144; logs OpenAPI operations 2 -> 4; total
operations 152 -> 154.

* feat(api): v2 tables run state, dispatch polling, batch update, bulk, archive

Closes the headless gaps on the v2 tables surface.

- Per-cell run state is now readable through an opt-in `includeRunState` on
  `GET /rows`, `POST /query`, and `GET /rows/{rowId}`. The default projection
  is byte-identical; a page whose sidecar outgrows its byte budget is a 413
  rather than a silent truncation.
- Run dispatches are addressable: `GET /tables/dispatches/{dispatchId}`
  publishes the column's full four-state domain so polling a finished run is
  not a 500, and `GET /tables/{tableId}/dispatches` lists what is in flight.
- `POST /rows/batch-update` takes one distinct patch per row. Its transaction
  moved out of the Copilot-only module into a surface-neutral use case both
  surfaces now call.
- `GET .../enrichment/{groupId}` publishes the provider cascade, cost, and
  timing behind one enrichment cell.
- `POST /tables/bulk-move` and `/bulk-delete` reach the existing bulk use
  cases, which now accept folders by canonical path and resolve them inside
  the application layer.
- `DELETE` is recoverable: `scope=archived` on the table list plus
  `POST /tables/{tableId}/restore`.

* feat(api): expose knowledge chunks, tag writes, archive/restore on v2

Closes the knowledge cluster's remaining public-surface gaps.

Chunks: list/read/create/update/delete/bulk under
`/api/v2/knowledge/{id}/documents/{documentId}/chunks`. `queryChunks` gains
an `id` tiebreaker on every sort so the list pages on a keyset rather than an
offset — `tokenCount` and `enabled` are both non-unique, so a page boundary
inside a run of equal values used to repeat or drop the tied rows. The
internal offset caller is unchanged; the two positioning schemes share one
read.

Tag definitions: create, update, delete, next-slot, usage, and the
document-scoped save and cleanup. Without them a caller could write a tag
value into a slot with no definition and then had no way to name it, so
tag-filtered retrieval was unbuildable end-to-end. `v2KnowledgeTagSchema`
gains `id`, without which PATCH and DELETE are unaddressable. The
document-scoped DELETE is pinned to `action: 'cleanup'`: the domain's `'all'`
deletes the whole knowledge base's tag vocabulary from a document path.

Archive/restore: `GET /api/v2/knowledge/archived` as a sibling route rather
than a `scope` param — the two reads bind different operations and a v2 route
declares one — plus `POST /api/v2/knowledge/{id}/restore`. `knowledge.restore`
is a new workspace operation carrying `delete`'s policy, since an operation's
inverse must not be harder to reach; the internal session route now delegates
its workspace branch to the shared use case and keeps only the legacy personal
one.

Also: `POST .../documents/from-workspace-files` surfaces `addWorkspaceFiles`,
so a file already in workspace storage no longer has to be re-uploaded
byte-for-byte to be indexed; the `chunkingConfig` write widens to the
first-party five-key schema with its refines and separator bounds, while the
response stays `.catchall` so a legacy JSONB row cannot 500; and
`CONNECTOR_MANAGED_RESOURCE_READ_ONLY` joins `FORBIDDEN_DETAIL_CODES` now that
the bare 403 on connector-managed chunk writes is wire-reachable.

Document upsert is deliberately not included.

* feat(api): add v2 credential rotation and a gate-exempt capabilities endpoint

PATCH /api/v2/credentials/{credentialId} rotates service-account secret
material or renames a credential in place, preserving the credential id so
existing workflow, deployment, paused-run, connector, and webhook references
keep working. Re-posting to POST /api/v2/credentials answers 409, and
delete-and-recreate mints a new id, so rotation previously had no door.

The route is adapter-only: updateWorkspaceCredentialUseCase already owned the
rotation, its audit projection, and credentials.update. It gains one additive
assertedWorkspaceId field for the v2 workspace assertion, and the per-principal
credential-type table that deleteCredentialUseCase already applied is lifted
into requireManageableCredentialType so both operations share it. Without it a
personal API key could rename an env_workspace row and toV2Credential's throw
would surface as a caller-reachable 500.

CredentialProviderOperationError now maps to 503 with Retry-After when the
provider is unreachable, instead of the 400 its OrchestrationError('validation')
base projected. A transient outage rendered as a permanent input error invites a
caller to revoke a working credential.

GET /api/v2/meta reports the calling key's rollout cohort, type, and expiry.
It is the one route declaring the new typed gate: 'exempt' option, because the
rollout gate and the unknown-path catch-all answer byte-identical 404s and a
gated /api/v2/meta could never resolve that ambiguity. Authentication still runs
first, so the only fact disclosed is one about the caller's own credential.

* feat(api): publish deployment lifecycle and workflow-MCP v2 surfaces

Adds the four deployment-lifecycle operations v2 was missing, and the
workflow-as-MCP publishing surface, both as adapters over application use
cases that already existed.

Deployment lifecycle:
- PATCH /api/v2/workflows/{id}/versions/{version} relabels a version.
  Deliberately not the internal route's body-shape dispatch between
  "rename" and "promote to live".
- POST .../versions/{version}/activate promotes a version. Same use case
  as rollback under a different transition, on its own path because the
  two mean opposite things to a caller.
- POST .../versions/{version}/revert overwrites the draft. Accepts the
  literal `active` alongside a version number.
- PATCH /api/v2/workflows/{id}/deployment toggles unauthenticated public
  execution.

`workflows.public_api.update` widens from session-only to session plus
personal API key: it is an admin-role change the same accountable human
may make from a script. Workspace keys stay denied. Its EE refusal now
carries PUBLIC_SHARING_NOT_ALLOWED instead of a bare forbidden.

Workflow MCP servers:
- /api/v2/workflow-mcp-servers list, create, update, delete, plus
  publish and unpublish of a workflow as a tool. Named apart from
  /api/v2/mcp-servers, which registers the external servers Sim calls.
- The six mcp_servers.workflow_deployments operations widen from
  ['delegated'] to admit sessions and personal API keys; roles and the
  workspace-key denial are unchanged.
- The server list gains keyset pagination, matching its external
  sibling, since nothing caps how many a workspace publishes.
- Server, tool, and workflow reads move out of the use case into
  lib/mcp/queries.

Route ratchet 1150 -> 1160; OpenAPI operations 161 -> 171.

* feat(api): extract chat deployments and publish the v2 surface

Chat deployment was a shipped module with no public API and two
authorization systems: `lib/workflows/application/chat-deployments.ts`
had deploy/undeploy extracted, but only Copilot used them — the REST
routes reimplemented workflow authorization inline, and `PATCH
/api/chat/manage/[id]` additionally owned password encryption, the
auth-type field-clearing matrix, identifier uniqueness, the
redeploy-gating protocol with two 409s, a raw db.update, and a manual
recordAudit.

New `lib/chat-deployments` domain:
- `chat_deployments.list/read/update/delete`, keyed on the deployment
  whose workspace is derived by joining its workflow. Creation stays
  `workflows.chat.deploy`, which is keyed on the workflow.
- The PATCH extraction, including the field-clearing matrix and the
  asynchronous-cutover invariant the route had hand-mirrored from
  `performChatDeploy`.
- One `buildChatDeploymentUrl`, replacing three constructions that had
  already drifted onto two different host helpers. There is no chat
  subdomain, so nothing publishes a host.
- Repository reads moved out of the use cases into
  `lib/chat-deployments/queries`.

Internal routes are now adapters over those use cases. `GET /api/chat`
is deliberately not migrated: it scopes by `chat.userId` while every
other chat operation authorizes by workspace admin, and reconciling the
two is a product decision. `PATCH` keeps its 400 for an identifier
collision through a typed `ChatIdentifierInUseError`; v2 reports the
409 the condition actually is.

v2 surface at `/api/v2/chat-deployments`: list, create, read, update,
delete. Workspace-scoped, keyset-paged, and a stored password is never
readable — reads carry `hasPassword` only, and the session-only reveal
endpoint deliberately has no v2 counterpart.

Also: an email- or SSO-gated chat with an empty allow-list is now
refused in the use case rather than only at the internal boundary, since
it is unenterable; and the doc comment on `processHostedKeyCost`
claiming a `usageLog` write is corrected — no such write exists.

Route ratchet 1160 -> 1165; OpenAPI operations 171 -> 176.

* fix(api): close three review findings, two of them caller-reachable

- Run output files are filtered to keys under the run's own execution
  prefix. The recording they came from is not a trustworthy key source:
  the start block copies every caller-supplied input field verbatim into
  its output and `collectUserFilesById` accepts anything carrying the
  `UserFile` shape, so a caller could name any storage key and have the
  download and base64 paths — neither of which authorizes per file — serve
  it back.
- `getBlock` reads own keys only. `BLOCK_REGISTRY` is an object literal,
  so `constructor`, `toString` and friends returned inherited functions
  that every consumer then treated as a block, turning a path segment into
  a 500. `getToolMetadata` already guarded this way.
- A folder-scoped log page no longer unions in every job run in the
  workspace. The guard read `filters.folderIds`, which the public surface
  never sets — it carries the folder filter in `folderScope` — so the page
  contradicted the contract's promise that job runs are dropped whenever a
  filter they cannot answer is set.

Also: the log cursor stamps `includeJobRuns` only when it is on, so its
`.default(false)` no longer puts a constant in every fingerprint and
rejects cursors minted before it existed; and the `folderName` subquery is
scoped to the workspace and to workflow folders instead of scanning the
whole `folder` table.

* fix(api): close two more review findings, one an authorization bypass

- `workflows.operations.apply` no longer admits a workspace API key. The
  use case authorizes against three per-user policies — the EE permission
  config, block visibility, and credential reachability — and all three
  take a human subject. An actorless key has none, and both substitutes
  fail open: attributing to the workspace billing owner evaluates the
  batch as the least-restricted account in the workspace, and passing no
  user makes `getUserPermissionConfig` return `null`, which every caller
  reads as unrestricted. Either way a workspace constrained by an
  allowlist was edited as though it were not. Personal keys keep the
  capability, so headless editing is unaffected for a credential that
  names a human.
- `GET /workflows/{id}/state` reads its variables through
  `parseWorkflowVariables`, and the stored variable response schema drops
  the two assertions the column cannot honour. The column has carried a
  JSON string and a legacy array as well as the current record, the
  realtime `variable.add` op types `type` as `z.any()`, and the parser
  writes `name` through verbatim — so the input bounds on the read turned
  a stored workflow into a 500 on the endpoint that opens it. The write
  schema keeps them, which is where they can still be honoured.
- `GET /workflows?scope=archived` projects folder paths tolerantly.
  Archiving a folder cascades onto the workflows inside it but leaves
  their `folderId` dangling — which is why restore has to null it — so the
  strict projector threw a bare `Error` and took the whole page down with
  no cursor able to step past the row.

* fix(files): bind Start-block file keys to the executing workspace

The Start block derived a file's storage key by parsing the caller's own
`url`, which `isInternalFileUrl` matches on any host and
`extractStorageKey` returns verbatim — so a request body could name any
tenant's bytes. The key is now accepted only when its own layout names
the workspace the execution runs in, and every file is dropped when the
execution carries no workspace.

Also bounds `includeFileBase64` with an aggregate response ceiling and a
worker pool instead of an unbounded `Promise.all`, scopes the bulk
download's authorization resource to the workspace when folder paths are
requested, makes the folder-restore selector mutually exclusive at the
type level, and names the bound in the `maxBytes` validation message.

* fix(api): close v2 log review findings

Cursor scope: `scope` on the workflow and table lists carries
`.default('active')`, so it entered every fingerprint as a constant and
refused every cursor minted before the param existed — with the
"cursor does not match the requested filters" 400, which is actively
misleading for a caller that changed nothing. Both now stamp the
default as absent, so only a caller who asked for `archived` gets a new
sequence.

Dashboard stats: `maxWorkflows` capped the response, not the
allocation. Segment series are now densified after the cut instead of
before, so returning 200 series no longer materializes one
`segmentCount`-length array per workflow in the window. The aggregate
still sums every workflow, now from the sparse per-workflow maps.

Cost keyset: `cost_total` is an unconstrained `numeric`, so its anchor
travelled through `Number()` and was compared back at full precision —
rows differing beyond float64 collapsed onto one anchor. Adds
`decimalKey`, which carries the digit string and binds it `::numeric`.

Run detail: `cost_total` is a backfilled projection, so a run predating
the backfill reported `cost: null` even with a real ledger, making
`items` unreachable for exactly the runs the ledger explains. Falls
back to the ledger total.

Also caps the log folder-path index reads at MAX_FOLDERS_PER_WORKSPACE
like every other reader, publishing the folder-tree 413 on the four log
operations; reverts a dead `status` widening in `v2CommaListSchema`;
drops an unread `executionData` select; corrects the segment-count and
searchLogs prose; and replaces the sort-cursor SQL-text assertions with
a two-page walk over a fixture with a null block.

* fix(api): close knowledge v2 review findings

- widen knowledge.list_archived to the delete/restore policy so a workspace
  API key can discover what it may restore
- escape LIKE wildcards on the now-public chunk search
- derive tag slot capacity from TAG_SLOT_CONFIG per field type
- type updateKnowledgeBase's chunkingConfig as ChunkingConfig and project
  every declared field explicitly
- attribute a restore to the calling surface instead of a literal 'api'
- gate 'knowledge chunks batch-update' behind --yes, since it can delete
- present the tag-cleanup action from the parsed request rather than
  faulting on the domain result after the delete committed
- unbind asserted-scope workspaceId from the nested knowledge cursors,
  matching the table-row lists
- add executed-SQL coverage for the chunk keyset

* fix(catalog): close the catalog and registry-boundary review findings

The module-graph ratchet treated an entry with no baseline row as
informational, so the six catalog routes and the projection barrel were
unratcheted while the summary still read "within their module-count
baseline". An unbaselined entry now fails --check, the summary counts only
what was actually compared, and the baseline is re-recorded.

The Copilot block-metadata tool — the reason the shared projection exists,
6,756 modules down to 1,321 — was in no guarded subtree. It is now an entry
source and a catalog boundary root.

Catalog behaviour:
- hostedApiKey is gated on the deployment, so a self-hosted install reports
  none instead of promising 127 tools' keys it will never supply
- block detail resolves an unversioned base type to its newest version and
  projects through the viewer's visibility, so it can no longer 404 a block
  the list contains or name it differently
- offset-cursor ordering compares code units rather than the process locale
- projections copy every array they publish instead of handing out the
  registries' own
- an options function returning a thenable throws rather than silently
  widening the providers-store substitution across the event loop
- a throwing block projection costs the Copilot tool one block, not all of them
- the trigger-kind log returns to debug: chat/manual/api are entry-point
  kinds, not authoring defects

Also sweeps the custom-block detail branch against its response schema,
guards each projection module rather than the dead barrel over them, and
drops a provably dead branch in processHostedKeyCost.

* fix(workflows): close v2 workflow-authoring review findings

- Read a blockless draft back as an empty graph. `PUT /state` of
  `{ blocks: {}, edges: [] }` — the contract's own published example —
  deletes every block row, and the loader answers `null` for a blockless
  workflow, so the following `GET /state` answered 404 while the list
  endpoint still showed the workflow. Existence is the workflow row's to
  decide; the null is now projected as an empty graph.
- Rewrite the `readWorkflowGraph` authorization test so it can fail. It
  called `authorize?.()` and asserted only a negative, so deleting
  `authorize` or replacing it with a no-op both passed — the invariant the
  head-safe `HEAD` path depends on.
- Route `setWorkflowBlockEnabled` through `replaceWorkflowNormalizedState`,
  the same door the other two graph writes use, instead of writing the
  normalized tables itself without state preparation or custom-tool
  extraction.
- Count applied operations directly. Enablement refusals landed in the same
  skipped-item array and were subtracted from the operation count, which
  `Math.max(applied, 0)` then masked when it went negative.
- Give a `disabled_ancestor` refusal its own member of the published skip
  enum instead of reporting it as `block_locked`.
- Refuse an `atomic` batch whose credential or hosted API key would be
  stripped, and carry the dropped inputs in the 409 details.
- Publish the whole lint report — `sources`, `sinks`, `orphanBlocks`,
  `emptyOutgoingPorts`, `invalidBranchPorts`, `invalidConnectionTargets`,
  `fieldIssues`, and the `kind` discriminator on unresolved references —
  rather than only free-text reference prose.
- Stop reporting unresolved lint references as `inputValidationErrors`.
  `collectUnresolvedReferences` is read-only, so those values stay
  persisted; they were double-reported, and falsely as dropped inputs.
- Replace two unfalsifiable negative-principal tests, which used a
  principal kind `Exclude`d from `PrincipalKind`, with a reachable one.
- Nits: drop a stranded TSDoc block; assert the membership predicate in the
  selector-validator admin test; make the HEAD test assert a representation;
  assert the sanitized graph is what `replaceWorkflowState` writes; add a
  route test rejecting `baseGraph` in a v2 body; carry
  `principalAuditSource` on restore/duplicate/moveBulk audit; unify the two
  `base64MaxBytes` ceilings on `MAX_INLINE_MATERIALIZATION_BYTES`.

* fix(api): close seven v2 review findings, one an authorization bypass

Raise mcp_servers.workflow_deployments.update_server to admin: its body
carries isPublic, and a public server executes with no Sim credential, so a
write member could remove authentication from every workflow it publishes.
create_server already grants the same visibility at admin.

Pin the widened operations in registry tests — the six workflow-MCP ones,
the four workflow widenings, and files.extract_archive.

Reject secret fields on a credential that has no rotatable secret instead of
dropping them behind a 200, classify a non-transient provider 4xx as caller
error rather than a retryable outage, and reconcile a provider outage to 503
with Retry-After on all three surfaces.

Give /v2/meta a declarative principal policy through a new defineOperation
factory, carry the key expiry on the auth context instead of reading the
api_key table from the application layer, and make the impossible principal
branch an invariant error rather than a codeless 403.

Enforce the rollout-gate exemption at definition time, against the one
contract path it is reserved for, and remove the gate parameter from the
exported admission helper so the builder is its only door.

* fix(tables): bound the run-state sidecar, and close six v2 review findings

Enforces the 2 MiB run-state ceiling INSIDE the sidecar drain rather than
over its materialized result, refuses the unbounded query form paired with
it, and normalizes the two stored blobs the v2 surface publishes from bare
`as` casts.

- The run-state budget now travels into `loadExecutionsByRow`, which drains
  row ids in bounded chunks and refuses before fetching the next one. The
  post-hoc `requireBoundedRunState` walk is gone: it measured a spike that
  had already happened, and re-serialized every entry to do it.
- Both row reads that accept `includeRunState` cap the page at
  `V2_MAX_RUN_STATE_ROW_LIMIT`, and `POST /tables/{id}/query` additionally
  refuses the flag paired with `limit: 0`.
- `runState.status` and the enrichment cascade blob are projected onto the
  published shape before presentation; both were caller-reachable 500s on a
  well-formed read.
- `sim tables bulk-delete` now gates behind `--yes`, and the CLI sweep that
  should have caught it covers destructive non-DELETE forms.
- `POST /tables/{id}/restore` is idempotent (200, no audit) like its
  knowledge sibling, and bulk folder selection deduplicates after resolution.
- The batch-update backstop keeps the looser Copilot ceiling and says so in
  TSDoc: it is a backstop no surface reaches, because the contracts stop a
  v2 caller at 1000 and the Copilot tool stops itself at 5000. Each caller
  sees the bound that actually applies to it; neither surface's cap moved.

* fix(chat-deployments): close v2 chat review findings

Fixes the chat-deployments slice of the v2 review, several of which are
regressions the application-operation extraction introduced.

- Stop a `500` on schemaless JSONB: the response now declares a stored
  shape without bounds and `toV2ChatDeployment` projects
  `customizations`, `outputConfigs`, and `allowedEmails` onto it. The
  request schemas keep `.strict()` and their bounds.
- Restore the specific validation message on `POST /api/chat` and
  `PATCH /api/chat/manage/[id]`, and the deleted test that pinned it.
- Restore `chat_deployments.read` to workspace `admin`; the detail read
  serves the visitor gate.
- Narrow the list projection so `chat_deployments.list` can stay a
  `read` operation reachable by a workspace API key: `allowedEmails`,
  `hasPassword`, and `customizations` are gone from the list entry and
  available only from the admin-gated detail read. Serialized field by
  field so a field added to the detail shape cannot reach the list by
  default.
- Classify create-path failures: `performChatDeploy` carries an
  `errorCode`, so an in-flight deployment is a `409` and an invariant
  failure a `500` instead of every refusal being a `400`.
- Delete the callerless `GET /api/chat`, which served the encrypted
  password column with no response contract.
- Propagate undeploy infrastructure failures instead of concealing them
  as `404`, and return `ChatDeploymentView` from both delete paths.
- Name `CHAT_AUTH_MODE_NOT_PERMITTED` on the create path.
- Guard `getBaseUrl` inside `buildChatDeploymentUrl`, which otherwise
  throws on a self-host with no `NEXT_PUBLIC_APP_URL`.
- Correct the published allow-list claim: a replacement `allowedEmails`
  is applied after the auth-type clear, so it does survive.
- Assert `workspaceId` on the v2 detail routes and reconcile the
  concealment TSDoc with what the error policy actually renders.
- Move `resolveActiveWorkspaceApplicationContext` to the workspaces
  domain so chat-deployments no longer imports workflow application code.

* test(credentials): pin the reconciled provider-outage status

The internal route alone answered 502 where the v2 surface, the shared
status helper and `PROVIDER_OUTAGE_CODES`' own TSDoc all say 503. The
test pinned the divergence; it now pins the reconciliation, including the
`Retry-After` a 503 carries. Corrects a stale comment that still named
502 as the value callers see.

* fix(executor): restore cloud-storage Start files, dropped by the key rule

The ownership check accepted a key only when it could be parsed out of an
internal `/api/files/serve/...` URL. But the server-side uploader for run
inputs returns a *presigned cloud* URL whenever object storage is
configured, whose path is the bucket key — so every chat-deployment
attachment, API `files[]` payload and generic-webhook file field resolved
no key, and because normalization is all-or-nothing the entire `files`
input was dropped with no error. It passed locally and under vitest only
because the uploader falls back to an internal URL when no object storage
is configured, which is exactly why no test caught it.

The test is ownership, not provenance: a key is accepted when its own
layout names the executing workspace, whether it arrives directly or is
parsed out of the URL. Neither field has to be trusted, since both are
caller-authored and both are held to the same check. A payload whose key
and URL disagree is refused rather than resolved in the caller's favour —
a genuine uploader writes the two consistently, so only a forged pairing
is turned away.

`context` is now derived from the accepted key rather than read from the
payload or the URL's `?context=`, so an owned key can no longer be
labelled with a bucket its bytes do not live in — the hardening the
previous comment claimed but did not perform.

* fix(api): close four defects the fix pass introduced

- `resolveLatest` built a `RegExp` from the caller's block id and read the
  registry with a bare lookup, so the catalog detail route — moved onto it
  by the version-alias fix — routed around the `ownBlock` guard added for
  exactly this. `GET /api/v2/blocks/%5B` was a `SyntaxError` 500 and
  `.../constructor` an inherited function. Matched by string comparison
  now, the way `tools/tool-ids.ts` resolves the same convention, and read
  through `ownBlock`.
- The run-state byte budget was applied inside `queryRows` rather than at
  the callers that publish it, so the first-party table grid — which reads
  run state at five times the row limit and publishes no ceiling — turned
  a large page into a hard failure, with an error naming a parameter it
  does not expose. The budget is now an explicit option the public reads
  pass and internal callers omit.
- Three graph-write CLI commands shipped ungated because the sweep meant
  to catch them matched only the names already enumerated, so it could
  never fail. It now forces every non-`GET` operation into a destructive
  or non-destructive list, and the three carry confirmations.
- Unbinding `workspaceId` from the knowledge-documents cursor was right on
  the merits and wrong in effect: the value is constant per sequence, so
  removing it changed the fingerprint and refused every cursor already in
  flight. Restored there; the chunks list is new in the same change and
  keeps the cleaner reading.

* fix(api): resolve a detail read to a version the viewer can see

`getLatestBlockForViewer` took the newest version and then hid it, which
inverted the contradiction it was written to close: `slack_v2` and
`table_v2` are preview-gated while their v1 deliberately stays in the
toolbar, so an unrevealed viewer got a `404` on a detail read for a type
`GET /api/v2/blocks` was listing in the same breath. It now walks versions
newest-first and answers with the first one visible to that viewer.

Also:
- The chat password guard ran after `performFullDeploy`, so a request that
  could never succeed burned a real workflow deployment version and then
  answered 400. Its two sibling gate guards already refuse ahead of the
  deploy; this one now does too.
- The Copilot sub-block serializer published the registry's own `options`
  and `dependsOn` arrays by reference. Pre-existing, but the catalog
  projection this parallels copies every array it publishes precisely
  because they are process-global and shared by every request.

* fix(api): restore the locked read-modify-write and the password validator

Two findings verified as real regressions against staging, out of ten
checked — the rest were pre-existing, latent, or false.

`setWorkflowBlockEnabled` read the graph outside the row lock and wrote it
back inside a later transaction. The editor's own save takes that same
lock, so an autosave committing in the window was silently discarded: this
operation writes a whole graph, not a delta. The persistence primitive now
accepts a reader that runs after the lock is taken, and the toggle
re-reads and re-decides there. Its lock predicate is also scoped to the
workspace and to a live row again, so a workflow archived mid-flight is
refused rather than written.

The v2 chat-deployment contracts inlined their own password rule twice
instead of using `chatDeploymentPasswordSchema`, losing the refusal of a
whitespace-only password — which the internal contract rejects precisely
because it strands the deployment behind a password the visitor form will
not submit. Both sites use the canonical validator now.

* fix(api): one folder projection, one dynamic-provider list, honest 413s

- `toV2Folder` existed twice, and the second copy had been written without
  the name/path invariant — so a row the list read refuses loudly would
  have been served with a mismatched pair by the restore read. One
  definition, guard included.
- The catalog projection restated `DYNAMIC_MODEL_PROVIDERS` and had
  drifted by one member. Derived from the canonical list instead.
- The tables reads documented a `413` for run state that they cannot emit
  — the budget became opt-in, and the row limit is the bound now — so the
  claim is removed rather than declared. The workflow run read has the
  opposite problem: it genuinely emits one, on a single file *or* the
  run's inlined total, and declared neither. Now declared, and the
  sentence covers both.
- Reclassifies the operations staging added into the destructive sweep, so
  the triage stays exhaustive.

* fix(v2): classify storage and uniqueness failures, drop permanent file delete

- remove the permanent file-delete endpoint; the platform offers no such
  action in the UI, and its manager wrote outside a transaction with no
  storage accounting
- extract a generated document's text from its compiled artifact rather than
  its generation source, matching the download path; a `.pdf` source was a
  500 and a `.docx` source returned generator JavaScript as clean content
- report a run file whose object retention has already swept as 404 rather
  than 500, on both the inline base64 read and the download stream
- report a knowledge tag that loses at a unique index as 409, naming whether
  the slot or the display name is taken
- gate `workflows versions revert` behind a CLI confirm; it overwrites the
  draft graph and was classified non-destructive

* feat(v2): report lint from both graph writes and add dry-run previews

- `PUT /workflows/{id}/state` now returns the same `lint` report as
  `POST /operations`; an agent authoring a graph from scratch needs the
  findings at least as much as one editing incrementally
- extract the report into one shared builder so the two writes cannot drift,
  and one shared presenter so the wire shape is identical
- skip the credential/tool reference pass when the caller has no human
  subject, rather than resolving it against the workspace billing owner:
  that would misreport what the workflow can reach and disclose another
  person's grants. `lint.notes` says when it was skipped
- add `?dryRun=true` to both graph writes: validates and lints, persists
  nothing, records no audit, notifies nobody. A query param, not a body
  field, since the body of a PUT is the resource itself
- CLI: a dry run no longer demands `--yes`; requiring confirmation to preview
  a change teaches callers to pass `--yes` reflexively
- CLI: name the graph commands for their verbs — `workflows state get`,
  `workflows state replace`, `workflows operations apply` — instead of the
  derived `state list` / `state update` / `operations create`
- document when to use `rollback` vs `versions/{version}/activate` on both

* chore(docs): sync generated docs manifest for the new CLI pages

* feat(v2): add the missing workflow-MCP reads and align bulk naming

- add `GET /workflow-mcp-servers/{serverId}` and
  `GET /workflow-mcp-servers/{serverId}/tools`. The resource could be
  PATCHed and DELETEd but never read, and its tools could be published and
  unpublished but never listed — the server list reports tool names only, so
  nothing published the `workflowId` that addresses a tool for deletion.
  Both mirror `mcp-servers` beside them, and carry that family's
  workspace-API-key denial rather than the wider `mcp_servers.read` policy
- rename `POST /tables/bulk-move` to `POST /tables/move`, so tables matches
  the shipped `files` resource exactly (`move` + `bulk-delete`)
- name the CLI commands for their operations instead of the derived
  `... create`: `tables move`, `workflows move`, `tables bulk-delete`, and
  `tables rows update-each` for the per-row batch, which sits beside the
  existing filter-based `tables rows batch-update`

`POST /tables/{id}/rows/batch-update` keeps its name: a distinct payload per
resource is precisely AIP-234 BatchUpdate, and `bulk-` would have collided
one word away from the filter form.

* fix(v2): correct documented statuses and a caller-reachable 500

- duplicating a workflow into a locked destination folder answered 500:
  `FolderLockedError` is a plain Error carrying `status = 423`, which the v2
  error policy does not classify. Converted to OrchestrationError('locked')
  at the application boundary, matching the bulk-move path
- restore workflow promised a 413 for an oversized folder tree that its
  response list never published; the cap is real, so the status now is too
- move workflows and apply variables documented 409/423 they cannot emit:
  every per-item lock and conflict is reported in `failed`, not thrown
- bulk download and delete knowledge tag can both 409 and did not say so;
  cleanup tag definitions cannot and did say so
- apply workflow operations denies workspace API keys but never documented it
- the dry-run responses are not byte-identical to a committed write:
  `needsRedeployment` describes the pre-write state and persistence warnings
  cannot appear. Reworded rather than overclaimed
- read file text and get file upload are head-safe, so the "HEAD skips the
  effect" sentence did not apply to them

* fix(v2): guard tag field-type changes and publish the 415 every body route can return

- `PATCH /knowledge/{id}/tags/{tagId}` accepted a `fieldType` incompatible
  with the slot the tag already occupies. Slots are enumerated per field
  type, so a text tag could be relabelled `number` and every later read
  would interpret its values as the wrong type. Create checked this; update
  now runs the same two checks
- derive `415` from the contract the way `413` already is: the JSON builder
  answers UNSUPPORTED_MEDIA_TYPE for any body under a content type it cannot
  read, so all 100 body routes could return a status none of them published
- give version activation its own result component instead of publishing it
  as `RollbackResult`; the shipped rollback keeps that name
- correct descriptions that promised behaviour the code does not have: a
  `processingStatus` field never returned, a `gmail_send` resolution example
  that short-circuits, bucket widths that overflow the window, a bulk tag
  save that relocates rather than overwrites, and per-server tool names
  actually gathered under a page-wide budget
- drop 409 from three knowledge and upload reads that cannot emit it

* docs(v2): correct the upload transfer contract and 16 other published claims

The upload transfer step was documented as Sim's own data plane on every
deployment: "success is 204" and "a failure is the v2 error envelope". That
holds only when Sim stores objects itself. With object storage configured the
URL is the provider's presigned URL, so S3 and GCS answer 200 and Azure 201,
and a failure is the provider's XML — a client written to the old text reads a
successful cloud upload as a failure. Also states that part ETags do not need
retaining: completion takes no body because Sim lists the parts from the
provider itself.

Other corrections, all to shipped descriptions rather than behaviour:
- DELETE table and bulk-delete files archive rather than erase, and neither
  said so; bulk delete also cannot emit the 409 it declared
- complete knowledge upload published a 402 only the create leg can raise
- billing status conceals a foreign workspace id as 404, not the 403 its
  TSDoc and description both claimed
- audit entries null a folder's resourceId and strip folder ids from metadata
  at every level; neither redaction was documented
- details=full adds the workflow summary to workflow runs only, never to job
  runs; GET /logs folderPaths covers a subtree like its two siblings; getLog
  now carries the retention sentence
- list secrets returns description too, and the logs and resources documents
  described only part of what they serve

* improvement(api): consolidate the v2 surface and close seven defects

Endpoint consolidation:
- Fold POST /logs/query into GET /logs; add sortBy/sortOrder, cap the
  comma lists, and move the list onto the shared keyset codec
- Fold GET /knowledge/archived into GET /knowledge?scope=archived,
  matching files, tables, and workflows
- Re-home chat deployments as a singleton under the workflow they
  belong to; keep the workspace-scoped discovery list
- Move the tag-definition writes off the document path onto
  /knowledge/{id}/tags, where they already acted
- Nest the table export and dispatch reads under their parent table

Defects:
- Publish isPublicApi on the deployment read; it was write-only, so a
  workflow could be opened to unauthenticated execution unauditably
- Stop publishing raw storage keys and an unusable URL in log files
- Classify a chat-identifier unique violation as 409 rather than 500
- Fall back to the root path instead of throwing when a knowledge
  base's folder is archived
- Cap bulk-download at the ceiling it actually enforces
- Normalize variables through one helper on both graph write paths
- Fix a folder-name log filter that matched workflow names

Naming and gaps:
- Rename /files/{id}/extract to /unarchive, /rows/find to /rows/search,
  /rows/batch-update to /rows/bulk-update, /columns/run to /dispatches
- Type the last six generic [id] path segments
- Add table folder restore and id-addressed dispatch cancel

* chore(audits): record the v2 catalog routes in the boundary baseline

* fix(api): accept a null chat password and correct three published claims

- performChatDeploy validated `password: null` as a password, so the
  replace-shaped chat PUT answered 400 for every mode that owns no
  password — public (the default), email, and sso. The declared payload
  type has always allowed null, and the stored value is cleared by
  authType regardless, so null needs no validation of its own. The route
  test could not catch it: it mocks the orchestration module and pinned
  the exact null the real guard refused.
- Redirect the two docs slugs this branch retired that were genuinely
  published: findTableRows and runTableColumns.
- The table folder restore described an idempotent no-op for an already
  active folder; it answers 404. Say so, and say where the path comes
  from, since the tables folder list cannot yet report archived folders.
- Name the customizations exception to the chat PUT's replace semantics.
- A cursor-binding case used status=error, which is a level and not a
  status, so it failed contract validation and never reached the cursor
  check. Use an accepted value and pin the reason, not just the status.

* chore(cli): classify the new v2 chat operation as non-destructive

* feat(cli): expose canonical resource URLs

* fix(api): close three caller-reachable failures found by the final probe

- GET /files/{fileId}/text called parseBuffer unguarded, and parseBuffer
  signals every failure as a bare Error that no v2 policy classifies. A
  zero-byte upload or a mislabelled archive was an unhandled 500. Empty
  bytes now answer empty text — a zero-length file has no text — and
  unparseable bytes answer 409, matching the rendered-artifact resolver.
- GET /workflows/{workflowId}/state asserted write-side bounds over
  stored data. workflow_blocks.name and .type are bare text() and the
  realtime rename op accepts z.string(), so a block renamed past 255
  characters made the workflow unreadable, and unrepairable, over v2.
  The read shape now takes the same input/stored split the variable
  schema already had. Stored subflow conditions are coerced in the
  loader beside the existing numeric guards.
- GET /knowledge stamped scope into the cursor fingerprint
  unconditionally. scope defaults to active and is new on that list, so
  every cursor the deployed build handed out would have been refused
  with a message saying the caller changed a filter they never sent.
  Its siblings already carry the guard and the comment.

Also: POST /workflow-mcp-servers answers 201 like every other v2 create;
GET /logs/stats reuses the log list's entry ceilings; the execute and
resume routes install the media-type-aware 415 they publish; and a
rationale citing an endpoint that never reached the wire is corrected.

* fix(tables): carry the dispatch terminal timestamps through the stale sweep

Staging's abandoned-dispatch recovery builds its own `DispatchRow`, and
this branch had added `completedAt`/`cancelledAt` to that shape for the
id-addressed dispatch read and cancel. The merge was textually clean and
left the new mapping short two fields.

* fix(workflows): deny workspace API keys on the graph replace

`PUT /workflows/{workflowId}/state` stores blocks and their tool wiring
wholesale, but the policies deciding which of those a member may add —
the EE permission config and block visibility — take a human subject.
A workspace API key has none, and both substitutes fail open: the
billing owner is a different, typically less-constrained person, and
passing no user makes the permission lookup return null, which every
caller reads as unrestricted.

That made the replace a second graph-write door storing what its sibling
`POST /workflows/{workflowId}/operations` refuses, which denies workspace
keys for exactly this reason. Both doors now agree. Personal keys keep
the capability, so headless authoring is unaffected for a credential
that names a human.

* chore(api): drop the enrichment catalog endpoint

GET /api/v2/enrichments listed the code-defined table enrichments. The
per-row enrichment run detail stays; only the catalog read goes.

Removes the route, contract, response and query schemas, the semantic
operation, the use case, the projection module, its registry-boundary
entry, and the CLI command. The "not found" and "blank search" cases it
covered are repointed at the connector-type sibling so the shared
behaviour stays tested rather than deleted with it.

* improvement(api): make the workflow operations endpoint self-describing

Two things stood between this endpoint and a caller who has only the
published spec.

The accepted `params` keys existed only in the edit engine's source. The
spec said "the accepted keys depend on the target block type", so a
caller reading it could create a nameless empty block and nothing more —
while the Copilot tool catalog, over the same engine, has always spelled
out the envelope. That guidance now lives in the contract, shared by the
add, edit, and insert_into_subflow parameter schemas so the two surfaces
cannot describe one engine differently: `inputs` keyed by sub-block id,
`retry`/`triggerMode`/`advancedMode` beside it rather than inside it,
`connections` keyed by source handle, and `removeEdges` for dropping one
edge without restating the rest.

A `block_id` that is not already a UUID is replaced with a minted one,
and the mapping was computed and then dropped. A caller could not
reference the block it had just created except by re-reading the graph
and matching on name. The engine now returns it and the response
publishes it as `mintedBlockIds`, with the in-batch versus cross-request
rule stated in the operation description.

* fix(api): close the pre-merge scan's blocking findings

Docs and public wire, all of it permanent surface once released.

- Two published tag groups, Catalog and Meta, had no sidebar entry in any
  locale, so six operations shipped unbrowsable. Added to all six, and a
  test now fails when a published tag has no entry.
- deleteWorkflowChatDeployment pointed callers at DELETE on /deployment;
  the undeploy verb is on /deploy.
- PUT /state still promised workspace API keys a degraded lint pass after
  the operation began rejecting them outright. It also lived in a
  single-quoted string, so the shared clause would not have interpolated.
- POST /tables/move took targetFolderPath as nullable-but-required, which
  rendered the CLI flag as a required `<json|@file>`: `--to /Archive`
  failed to parse and omitting it failed outright, while the docs said
  "omit for root". Now optional and a plain string, matching
  POST /files/move; the route supplies the null the use case wants.
- Table dispatch status and row run state published `cancelled` beside
  imports, exports, and job state publishing `canceled`, and the note
  explaining the split was wrong about its own sibling. Both new schemas
  now publish `canceled`; the stored column is unchanged and mapped at
  the presenter. The shipped `cancelled` count field is left alone.
- applyWorkflowVariables can answer 423 and both workflow-MCP deletes can
  answer 409; none declared it. Hand-assembled error lists replaced with
  the shared sets.
- /files/{fileId}/unarchive became /unzip. `extract` reads as "extract
  text" and `unarchive` reads as the inverse of restore on a resource
  where archived means soft-deleted; unzip collides with neither and is
  what the implementation calls itself.

* improvement(cli,docs): finish the naming and clear the enrichment leftovers

- Four single-record GETs derived to `list` while returning one thing:
  meta, a workflow's chat deployment, log stats, and file text. Renamed to
  `meta status`, `workflows chat status`, `logs stats`, `files read`,
  matching the `workflows deployment status` correction already in this
  branch. None of the old spellings shipped.
- Dropped five `renamedFrom` aliases pointing at spellings that never
  existed, each of which built a hidden command and a permanent
  deprecation warning for argv nobody could have typed. `tables rows find`
  keeps its alias — that one really shipped.
- Removed the enrichment catalog from three prose sites left behind when
  the endpoint went: the resources spec description, its Catalog tag, and
  the contract and pagination-test comments.
- Documented the six new command groups in the CLI index table. That page
  is a guide page, so the docs staleness check cannot flag it.
- Published the `customizations` exception to the chat replace semantics.
  It was in the route TSDoc and invisible to every caller reading the
  spec, which is where the claim "Replace, not merge" is made.

* improvement(cli): use batch- for the tables bulk delete, matching its siblings

The CLI renames a bulk form only when it would collide with its singular
sibling, and uses AWS's `batch-` prefix when it does — `files
batch-delete`, `tables rows batch-delete`, `knowledge chunks
batch-update`. `tables delete` exists, so `tables bulk-delete` was that
same rename reaching for the other word, and the only `bulk-` command on
the surface. No `bulk-` CLI command has ever shipped, so this costs
nothing now and would be permanent later.

`files bulk-download` keeps its name: there is no `files download` to
collide with, and it is one archive rather than N operations. Its config
block now says why it exists at all, since the command is never built —
the builder skips non-JSON response modes, but the contract sweeps still
read the entry and require the folder-path field to be marked.

* fix(workflows): allow operations on blockless drafts

* feat(workflows): add manual and run-from-block execution

* fix(cli): update workflow run description test

* fix(tests): align fixtures with current contracts

* fix(api): derive chat activity from workflow deployment

---------

Co-authored-by: Theodore Li <theo@sim.ai>
2026-08-25 04:19:34 -04:00

9956 lines
360 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"openapi": "3.1.0",
"info": {
"title": "Sim API v2 — Workflows",
"description": "Version 2 of the Sim REST API for workflow management, deployment versions, execution, run lifecycle, folders, and portable import and export.",
"version": "2.0.0",
"contact": {
"name": "Sim Support",
"email": "help@sim.ai",
"url": "https://www.sim.ai"
},
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"servers": [
{
"url": "https://www.sim.ai",
"description": "Production"
}
],
"tags": [
{
"name": "Workflows",
"description": "Manage and execute workflow definitions, folders, deployment versions, and portable imports and exports."
},
{
"name": "Workflow Runs",
"description": "Inspect, resume, and cancel workflow runs."
}
],
"security": [
{
"apiKey": []
}
],
"paths": {
"/api/v2/workflows": {
"get": {
"operationId": "listWorkflows",
"summary": "List Workflows",
"description": "List workflows in a workspace with lifecycle scope, folder and deployment filters, search, sorting, and opaque cursor pagination. `scope` defaults to `active`; pass `archived` to list workflows a `DELETE` archived. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"description": "Workspace whose workflows should be listed.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace whose workflows should be listed."
}
},
{
"name": "scope",
"in": "query",
"required": false,
"description": "Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too.",
"schema": {
"default": "active",
"description": "Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too.",
"type": "string",
"enum": ["active", "archived"]
}
},
{
"name": "folderPath",
"in": "query",
"required": false,
"description": "Restrict results to workflows in this folder path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
"schema": {
"description": "Restrict results to workflows in this folder path. A path that names no folder narrows the result to nothing, so the response is an empty page rather than an error.",
"$ref": "#/components/schemas/FolderPathInput"
}
},
{
"name": "deployedOnly",
"in": "query",
"required": false,
"description": "Return only workflows with an active deployment when true.",
"schema": {
"description": "Return only workflows with an active deployment when true.",
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum workflows to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"schema": {
"default": 50,
"description": "Maximum workflows to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"schema": {
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"type": "string",
"minLength": 1
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Case-insensitive substring match against the resource name.",
"schema": {
"description": "Case-insensitive substring match against the resource name.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "sortBy",
"in": "query",
"required": false,
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"schema": {
"default": "position",
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"type": "string",
"enum": ["position", "name", "createdAt", "updatedAt", "runCount"]
}
},
{
"name": "sortOrder",
"in": "query",
"required": false,
"description": "Sort direction.",
"schema": {
"default": "asc",
"description": "Sort direction.",
"type": "string",
"enum": ["asc", "desc"]
}
}
],
"responses": {
"200": {
"description": "A page of workflows.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"post": {
"operationId": "createWorkflowV2",
"summary": "Create Workflow",
"description": "Create a workflow in a workspace root or canonical workflow folder. The response carries the blocks the platform seeded the workflow with, so the start block's id is available without a second request — attach edges to it directly. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"requestBody": {
"required": true,
"description": "Name, description, workspace, and optional folder for a new workflow.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkflowRequest"
}
}
}
},
"responses": {
"201": {
"description": "The created workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/state": {
"get": {
"operationId": "getWorkflowState",
"summary": "Get Workflow State",
"description": "Get the editable draft graph of a workflow: blocks, edges, the loop and parallel containers derived from them, and variables. This is the pollable read — it records no audit event, and `HEAD` mirrors `GET`. The payload is **unsanitized**: it carries workspace-scoped `credentialId`, `knowledgeBaseId`, and `tableId` values verbatim, so it is not portable to another workspace. Use `GET /workflows/{workflowId}/export` for a portable, sanitized copy — and note that export is not a read-modify-write source, because sanitizing it drops every credential binding. Unknown members are stripped, so what this returns is exactly the set of keys `PUT /workflows/{workflowId}/state` accepts.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The workflow draft graph.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowStateResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"put": {
"operationId": "replaceWorkflowState",
"summary": "Replace Workflow State",
"description": "Replace a workflow’s editable draft graph wholesale. `loops` and `parallels` are accepted but ignored — both are recomputed from `blocks`. Omitting `variables` leaves the stored variables untouched.\n\nLast write wins: concurrent writers are serialized by a row lock, so each lands a complete self-consistent graph and the later one replaces the earlier entirely. There is no partially-written state and no conflict detection.\n\nThis does not change what the deployed endpoint serves. Deployments are immutable versioned snapshots, and no schedule or webhook registration is touched. The only visible consequence is that `needsRedeployment` becomes true; `POST /workflows/{workflowId}/deploy` publishes the draft.\n\n`lint` is advisory and never blocks the write. `lint.fieldIssues` is the most actionable part for a headless builder — it names blocks missing a required field, which fail at run time — and `lint.unresolvedReferences` names credential, resource, tool, and skill values that do not resolve. A workspace API key is rejected with `403`; use a personal API key.\n\nSet `?dryRun=true` to validate and lint without persisting: nothing is written, no audit entry is recorded, and collaborators are not notified. The response carries the same shape and the same validation and `lint` findings the committed write would, with `dryRun: true` — but `needsRedeployment` describes the state before the write, and warnings raised by persistence itself are necessarily absent.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "dryRun",
"in": "query",
"required": false,
"description": "Validate and lint without persisting. The response is identical to the committed write of the same body, so a caller can inspect `lint` and then re-send the request for real. Nothing is written, no audit entry is recorded, and collaborators are not notified.",
"schema": {
"description": "Validate and lint without persisting. The response is identical to the committed write of the same body, so a caller can inspect `lint` and then re-send the request for real. Nothing is written, no audit entry is recorded, and collaborators are not notified.",
"type": "boolean"
}
}
],
"requestBody": {
"required": true,
"description": "A complete replacement draft graph for a workflow.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceWorkflowStateRequest"
}
}
}
},
"responses": {
"200": {
"description": "The draft graph was replaced.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceWorkflowStateResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/operations": {
"post": {
"operationId": "applyWorkflowOperations",
"summary": "Apply Workflow Operations",
"description": "Apply a batch of semantic edits — add, edit, delete, and subflow membership changes — to a workflow graph, plus an optional set of block enable/disable changes.\n\nBest-effort per operation, atomic per write. The engine applies what it can to an in-memory graph and reports the rest in `skipped`, each with a machine-readable `type`; exactly one write of the fully-resolved graph then happens, so there is never a partially-applied graph. `deferred` is **not** a failure list: a forward-referencing edge is wired automatically once its target block exists, in this batch or a later one, so re-issuing a deferred edge is wrong.\n\nSet `atomic` to fail closed: any genuine skipped item, or any block input that would be dropped rather than persisted, then aborts before the write and answers `409` with `error.details.code: \"OPERATIONS_NOT_APPLIED\"`, the same `skipped` array, and a `droppedInputs` array, having persisted nothing.\n\nA `block_id` you supply on an `add` or `insert_into_subflow` is only a label unless it is already a UUID: the engine mints one and returns the pairing in `mintedBlockIds`. References between operations in the same batch are remapped for you, so `triage` can be wired up in the same call it is created in — but a later request must use the minted id. Send your own UUIDs when you want an id you chose to survive across requests.\n\nOperation `params` is an open object because the accepted inputs come from the block registry, not from this contract — see the per-operation schemas for the envelope: `inputs` keyed by sub-block id, with `retry`, `triggerMode` and `advancedMode` beside it rather than inside it, and `connections` keyed by source handle. `GET /blocks/{blockId}` publishes the inputs a given block type accepts.\n\n`lint` is advisory and never blocks the write. `lint.fieldIssues` is the most actionable part for a headless builder — it names blocks missing a required field, which fail at run time — and `lint.unresolvedReferences` names credential, resource, tool, and skill values that do not resolve. Those values stay persisted; only `inputValidationErrors` lists inputs that were actually dropped.\n\nAs with `PUT /workflows/{workflowId}/state`, this changes only the draft; deploy to publish it. A workspace API key is rejected with `403`; use a personal API key.\n\nSet `?dryRun=true` to validate and lint without persisting: nothing is written, no audit entry is recorded, and collaborators are not notified. The response carries the same shape and the same validation and `lint` findings the committed write would, with `dryRun: true` — but `needsRedeployment` describes the state before the write, and warnings raised by persistence itself are necessarily absent.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "dryRun",
"in": "query",
"required": false,
"description": "Validate and lint without persisting. The response is identical to the committed write of the same body, so a caller can inspect `lint` and then re-send the request for real. Nothing is written, no audit entry is recorded, and collaborators are not notified.",
"schema": {
"description": "Validate and lint without persisting. The response is identical to the committed write of the same body, so a caller can inspect `lint` and then re-send the request for real. Nothing is written, no audit entry is recorded, and collaborators are not notified.",
"type": "boolean"
}
}
],
"requestBody": {
"required": true,
"description": "A batch of semantic edits against a workflow graph.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyWorkflowOperationsRequest"
}
}
}
},
"responses": {
"200": {
"description": "The batch was applied.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyWorkflowOperationsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/variables": {
"patch": {
"operationId": "applyWorkflowVariables",
"summary": "Update Workflow Variables",
"description": "Add, edit, and delete a workflow’s variables. Operations are matched by variable `name` and applied in order; a batch that changes nothing answers `200` with `changed: false`. Values are coerced to the declared `type`, and a value that cannot be coerced is stored as supplied. Read the current set from `variables` on `GET /workflows/{workflowId}`.",
"tags": ["Workflows"],
"parameters": [
{
"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"]
}
}
],
"requestBody": {
"required": true,
"description": "Additions, edits, and deletions against a workflow’s variables.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyWorkflowVariablesRequest"
}
}
}
},
"responses": {
"200": {
"description": "The variable set after the batch.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyWorkflowVariablesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/duplicate": {
"post": {
"operationId": "duplicateWorkflow",
"summary": "Duplicate Workflow",
"description": "Copy a workflow, including its blocks, edges, subflows, and variables, into the same workspace. Omitting `name` reuses the source name; a collision inside the destination folder is deduplicated rather than refused. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"parameters": [
{
"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"]
}
}
],
"requestBody": {
"required": true,
"description": "Optional name and destination folder for the copy.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DuplicateWorkflowRequest"
}
}
}
},
"responses": {
"201": {
"description": "The created copy.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DuplicateWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/restore": {
"post": {
"operationId": "restoreWorkflow",
"summary": "Restore Workflow",
"description": "Bring an archived workflow back, along with the schedules, webhooks, MCP tools, and chats that were archived with it. A workflow that is not archived answers `409`. A workflow whose folder was archived is restored to the workspace root. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The restored workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestoreWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/move": {
"post": {
"operationId": "moveWorkflows",
"summary": "Move Workflows",
"description": "Relocate up to 100 workflows into one folder. Explicitly best-effort: each workflow moves in its own transaction, and one that is absent from the workspace, archived, or locked lands in `failed` while the rest still move. Duplicate ids are collapsed. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"requestBody": {
"required": true,
"description": "Workflows to relocate and the folder to relocate them into.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MoveWorkflowsRequest"
}
}
}
},
"responses": {
"200": {
"description": "Which workflows moved and which did not.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MoveWorkflowsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}": {
"get": {
"operationId": "getWorkflow",
"summary": "Get Workflow",
"description": "Get a workflow with its variables and deployed API-trigger inputs. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The requested workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowDetailResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"patch": {
"operationId": "updateWorkflowV2",
"summary": "Update Workflow",
"description": "Rename, describe, or move a workflow to a canonical folder path. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"parameters": [
{
"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"]
}
}
],
"requestBody": {
"required": true,
"description": "Fields to update on an existing workflow.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The updated workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteWorkflowV2",
"summary": "Delete Workflow",
"description": "Archive a workflow. Despite the verb, this is not an erasure: the workflow, and the schedules, webhooks, MCP tools, and chats attached to it, are stamped archived and stop running, and `POST /workflows/{workflowId}/restore` brings all of them back. An archived workflow disappears from the default list and is reachable with `scope=archived`. The `deleted` field is retained for shipped clients; `archived` states what actually happened.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The workflow was archived.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/versions": {
"get": {
"operationId": "listWorkflowVersionsV2",
"summary": "List Workflow Versions",
"description": "List immutable deployment versions of a workflow, newest first.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum deployment versions to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"schema": {
"default": 50,
"description": "Maximum deployment versions to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"schema": {
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "A page of deployment versions.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowVersionListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/versions/{version}": {
"get": {
"operationId": "getWorkflowVersionV2",
"summary": "Get Workflow Version",
"description": "Get an immutable deployment version and its pinned workflow graph snapshot.",
"tags": ["Workflows"],
"parameters": [
{
"name": "version",
"in": "path",
"required": true,
"description": "Numeric deployment version.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483647,
"description": "Numeric deployment version.",
"examples": [3]
}
},
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
}
],
"responses": {
"200": {
"description": "The requested deployment version.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowVersionDetailResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"patch": {
"operationId": "updateWorkflowVersionV2",
"summary": "Update Workflow Version",
"description": "Relabel a deployment version. Merge-patch shaped: an omitted key is unchanged and `description: null` clears the release note. Metadata only — the pinned graph is immutable, and this never changes which version is live. Promote a version with `POST /workflows/{workflowId}/versions/{version}/activate`.",
"tags": ["Workflows"],
"parameters": [
{
"name": "version",
"in": "path",
"required": true,
"description": "Numeric deployment version.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483647,
"description": "Numeric deployment version.",
"examples": [3]
}
},
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
}
],
"requestBody": {
"required": true,
"description": "Merge-patch body for the mutable metadata of a deployment version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The updated version metadata.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowVersionResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/versions/{version}/activate": {
"post": {
"operationId": "activateWorkflowVersion",
"summary": "Activate Workflow Version",
"description": "Promote an existing deployment version to live. Activation is asynchronous; inspect `isDeployed` and `latestDeploymentAttempt` for current state. Unlike `rollback`, the target is named by the path and the workflow need not already be deployed. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"name": "version",
"in": "path",
"required": true,
"description": "Numeric deployment version.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483647,
"description": "Numeric deployment version.",
"examples": [3]
}
},
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
}
],
"requestBody": {
"required": false,
"description": "No body. The version to promote is named by the request path.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivateWorkflowVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The accepted activation attempt.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivateWorkflowVersionResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/versions/{version}/revert": {
"post": {
"operationId": "revertWorkflowVersion",
"summary": "Revert Workflow To Version",
"description": "Overwrite the editable draft with the graph pinned by a deployment version, discarding every unsaved edit. This is the most destructive operation in the deployment family and it does **not** change what is live — to move production, use `activate` or `rollback`, both of which leave the draft alone. Pass `active` as the version to discard draft edits and return to the live graph. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"name": "version",
"in": "path",
"required": true,
"description": "Numeric deployment version, or `active` for the currently live version.",
"schema": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483647
},
{
"type": "string",
"const": "active"
}
],
"description": "Numeric deployment version, or `active` for the currently live version.",
"examples": [3, "active"]
}
},
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
}
],
"requestBody": {
"required": false,
"description": "No body. The version to load into the draft is named by the request path.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevertWorkflowVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The draft after it was overwritten.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevertWorkflowVersionResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/deployment": {
"get": {
"operationId": "getWorkflowDeployment",
"summary": "Get Workflow Deployment",
"description": "Read the current deployment state of a workflow: whether a version is live, when it went live, the most recent deployment attempt with its readiness and failure payload, and whether the editable draft has since diverged from the live version. This is the only operation that publishes `needsRedeployment` and `isPublicApi`.\n\n`isPublicApi` is the security-relevant one: while it is `true` the deployed workflow executes without an API key, so anyone holding the execution URL can run it — and consume the workspace’s billed usage — anonymously. It is set through `PATCH /workflows/{workflowId}/deployment`, and this read is the only way to audit whether it is on.\n\nNot to be confused with `/workflows/{workflowId}/deployments/chat`, which is the hosted chat the workflow is published as. This path governs whether the workflow is executable at all; that one governs one surface it is served on. A workflow can be deployed with no chat, and removing its chat leaves it deployed and executable.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The current deployment state.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowDeploymentResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"patch": {
"operationId": "updateWorkflowPublicApi",
"summary": "Update Workflow Public API Access",
"description": "Enable or disable unauthenticated public execution of the deployed workflow. While enabled, anyone holding the execution URL can run the workflow without an API key. An organization that forbids public sharing refuses this with `403` and `PUBLIC_SHARING_NOT_ALLOWED`. Not to be confused with `/workflows/{workflowId}/deployments/chat`, which is the hosted chat the workflow is published as. This path governs whether the workflow is executable at all; that one governs one surface it is served on. A workflow can be deployed with no chat, and removing its chat leaves it deployed and executable. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"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"]
}
}
],
"requestBody": {
"required": true,
"description": "Enable or disable unauthenticated public execution of the deployed workflow.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowPublicApiRequest"
}
}
}
},
"responses": {
"200": {
"description": "The updated public API setting.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowPublicApiResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/deploy": {
"post": {
"operationId": "deployWorkflow",
"summary": "Deploy Workflow",
"description": "Create and asynchronously activate a deployment version. Not idempotent: every call mints a new version, so a retry after a timeout creates a second one. A deployment that would conflict with an existing webhook path is a `409`. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"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"]
}
}
],
"requestBody": {
"required": false,
"description": "Optional metadata for the new deployment version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeployWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The accepted deployment attempt.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeployWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "undeployWorkflow",
"summary": "Undeploy Workflow",
"description": "Deactivate the currently serving workflow version. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The workflow was undeployed.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UndeployWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/rollback": {
"post": {
"operationId": "rollbackWorkflow",
"summary": "Rollback Workflow",
"description": "Asynchronously reactivate a previous deployment version, selecting the preceding active version when no version is supplied. Use this to step back from the currently live version; to make a specific version live by naming it in the path — including when the workflow is not currently deployed — use `POST /workflows/{workflowId}/versions/{version}/activate`. Neither touches the draft. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"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"]
}
}
],
"requestBody": {
"required": false,
"description": "Optional deployment version to reactivate.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RollbackWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The accepted rollback attempt.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RollbackWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/export": {
"get": {
"operationId": "exportWorkflow",
"summary": "Export Workflow",
"description": "Export a portable, secret-sanitized workflow. Workspace-scoped bindings must be selected again after import. Exporting records an audit event, so it is not a safe read. A `HEAD` skips the effect but is authorized exactly as the `GET` is, so it answers `400`, `401`, `403`, or `404` wherever the `GET` would and an empty `200` otherwise. Skipping the effect means skipping the read that produces the payload, so that `200` carries none of the response headers documented below — it answers whether the `GET` would be allowed, not what the `GET` would return. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The workflow export payload.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/import": {
"post": {
"operationId": "importWorkflow",
"summary": "Import Workflow",
"description": "Create a workflow from a portable export object, bare state, or JSON string. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"requestBody": {
"required": true,
"description": "Portable workflow data and destination metadata for an import.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportWorkflowRequest"
}
}
}
},
"responses": {
"201": {
"description": "The imported workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/chat-deployments": {
"get": {
"operationId": "listChatDeployments",
"summary": "List Chat Deployments",
"description": "List the workflows a workspace has published as hosted chats. Each entry carries the public `url` a visitor uses — there is no chat subdomain, the identifier is a path segment.\n\nThis is the only chat path not addressed under a workflow, and deliberately so: every chat is a singleton of the workflow it publishes, but \"what does this workspace serve\" is a question no per-workflow path can answer. Filter by `workflowId` to resolve one workflow's chat without holding its id.\n\nEntries are deliberately narrower than the singleton read: `allowedEmails`, `hasPassword`, and `customizations` are available only from `GET /api/v2/workflows/{workflowId}/deployments/chat`, which requires workspace `admin`. That is what keeps this list callable at workspace `read` and by a workspace API key. A stored password is never returned by either.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"description": "Workspace whose chat deployments to list.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace whose chat deployments to list."
}
},
{
"name": "workflowId",
"in": "query",
"required": false,
"description": "Restrict to deployments of one workflow.",
"schema": {
"description": "Restrict to deployments of one workflow.",
"type": "string",
"minLength": 1
}
},
{
"name": "isActive",
"in": "query",
"required": false,
"description": "Restrict to active or inactive deployments.",
"schema": {
"description": "Restrict to active or inactive deployments.",
"type": "boolean"
}
},
{
"name": "sortBy",
"in": "query",
"required": false,
"description": "Field used to sort the result.",
"schema": {
"default": "createdAt",
"description": "Field used to sort the result.",
"type": "string",
"enum": ["identifier", "createdAt", "updatedAt"]
}
},
{
"name": "sortOrder",
"in": "query",
"required": false,
"description": "Sort direction.",
"schema": {
"default": "desc",
"description": "Sort direction.",
"type": "string",
"enum": ["asc", "desc"]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum chat deployments to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"schema": {
"default": 50,
"description": "Maximum chat deployments to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"schema": {
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "A page of chat deployments.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatDeploymentListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/deployments/chat": {
"get": {
"operationId": "getWorkflowChatDeployment",
"summary": "Get Workflow Chat Deployment",
"description": "Read the hosted chat a workflow is published as. Answers `404` when the workflow publishes no chat. Not to be confused with `/workflows/{workflowId}/deployment` (singular), which is the workflow's own API deployment — its live version and whether the draft has drifted. That path governs whether the workflow is executable at all; this one governs the hosted chat it is served on. The chat is a singleton of its workflow, so it has no id of its own in any path and no separate create verb: `PUT` is create-or-replace and is the only write. The stored password is never returned — `hasPassword` reports only whether one is set. This carries the visitor gate — `authType`, `hasPassword`, and the `allowedEmails` allow-list — so it requires workspace `admin`, unlike the workspace-wide list. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The workflow's chat deployment.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetWorkflowChatDeploymentResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"put": {
"operationId": "replaceWorkflowChatDeployment",
"summary": "Create or Replace Workflow Chat Deployment",
"description": "Publish a workflow as a hosted chat, or replace the chat it already publishes. Not to be confused with `/workflows/{workflowId}/deployment` (singular), which is the workflow's own API deployment — its live version and whether the draft has drifted. That path governs whether the workflow is executable at all; this one governs the hosted chat it is served on. The chat is a singleton of its workflow, so it has no id of its own in any path and no separate create verb: `PUT` is create-or-replace and is the only write.\n\n**Replace, not merge.** The chat ends up as exactly what the body describes: an omitted optional field takes its platform default rather than whatever the previous chat carried, so sending the same body twice leaves the same result. `password` is therefore required whenever `authType` is `\"password\"` and rejected otherwise — it is write-only and never readable back, so carrying one over implicitly is the one place a replace would quietly stop meaning replace. `allowedEmails` follows the same rule: required and non-empty for `\"email\"` and `\"sso\"`, rejected for the modes that admit no allow-list. `customizations` is the one documented exception: it merges per field, so an omitted `imageUrl` keeps the stored one rather than clearing it, and customization keys this surface does not declare do not survive the write. That behaviour is shared with the in-app editor and the Copilot deploy tool, which both send partial objects.\n\nThis also deploys the workflow, because a chat serves the live version: a draft that has drifted is republished as part of the call. Two conditions answer `409` — an `identifier` another live chat already holds, and a workflow deployment attempt still preparing, which the caller can retry once it becomes active. `authType: \"public\"` leaves the chat open to anyone holding the URL. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"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"]
}
}
],
"requestBody": {
"required": true,
"description": "The complete desired state of a workflow's chat.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceChatDeploymentRequest"
}
}
}
},
"responses": {
"200": {
"description": "The published chat deployment.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceWorkflowChatDeploymentResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteWorkflowChatDeployment",
"summary": "Delete Workflow Chat Deployment",
"description": "Stop serving a workflow's hosted chat. Its URL stops answering and the identifier becomes free again. The workflow's own deployment is untouched and stays executable through the workflow API — to undeploy that, use `DELETE /workflows/{workflowId}/deploy`. A workspace API key is rejected with `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"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": {
"description": "The chat deployment was removed.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteWorkflowChatDeploymentResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/execute": {
"post": {
"operationId": "executeWorkflowV2",
"summary": "Execute Workflow",
"description": "Execute the active deployment by default, or select manual execution of the current saved workflow state with `run.source: \"manual\"`. Manual runs require a personal API key with current write access and support synchronous or Server-Sent Event execution only; workspace keys, anonymous public access, and async manual runs are rejected. A manual run can enter through one runnable trigger (including external integration/webhook triggers) or resume at a named block from the exact same-workflow run identified by `sourceRunId`; the server loads that run's persisted snapshot, which is never accepted from the request. Omit a trigger block id only when the saved workflow has exactly one runnable trigger. Public deployed workflows permit anonymous synchronous and streaming execution, while asynchronous deployed execution requires an API key. A synchronous run that exceeds its execution timeout returns HTTP 200 with `status: \"failed\"` and `error.code: \"TIMEOUT\"` rather than an HTTP error, so branch on `status`. Each option carries the modes it requires and the modes that reject it; a violated combination is a 400.",
"tags": ["Workflows"],
"security": [
{
"apiKey": []
},
{}
],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "x-run-id",
"in": "header",
"required": false,
"description": "Caller-supplied run identifier, available only to API-key callers. A one-shot uniqueness claim, NOT an idempotency key: reusing a value fails with `409` and `error.details.code: \"RUN_ID_CONFLICT\"` rather than replaying the original result. To retry safely, send a fresh value per attempt, or omit the header and let the server allocate one.",
"schema": {
"description": "Caller-supplied run identifier, available only to API-key callers. A one-shot uniqueness claim, NOT an idempotency key: reusing a value fails with `409` and `error.details.code: \"RUN_ID_CONFLICT\"` rather than replaying the original result. To retry safely, send a fresh value per attempt, or omit the header and let the server allocate one.",
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
},
{
"name": "x-sim-via",
"in": "header",
"required": false,
"description": "Comma-separated workflow identifiers naming the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically; supply it yourself only when relaying an existing chain. A chain at the maximum depth is rejected with `409` and `error.details.code: \"CALL_CHAIN_DEPTH_EXCEEDED\"`.",
"schema": {
"description": "Comma-separated workflow identifiers naming the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically; supply it yourself only when relaying an existing chain. A chain at the maximum depth is rejected with `409` and `error.details.code: \"CALL_CHAIN_DEPTH_EXCEEDED\"`.",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "Input, workflow-state selection, and execution-mode options. Each option carries the modes it requires and the modes that reject it; a violated combination is a 400.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "A synchronous run result or Server-Sent Event stream.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteWorkflowSyncResponse"
}
},
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "The asynchronous run was queued.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteWorkflowQueuedResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/UsageLimitExceeded"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/RunIdConflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"499": {
"$ref": "#/components/responses/ClientClosedRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/runs": {
"get": {
"operationId": "listWorkflowRunsV2",
"summary": "List Workflow Runs",
"description": "List recorded runs of a workflow with filtering and opaque cursor pagination. Runs are hard-deleted once they pass the payer's log retention window, so an older run is simply absent rather than reported as removed. The window is 30 days from run start on the free plan, unbounded on Pro and Team, and set per organization on Enterprise with an optional per-workspace override.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Filter by run status.",
"schema": {
"description": "Filter by run status.",
"type": "string",
"enum": ["pending", "running", "completed", "failed", "cancelled", "paused"]
}
},
{
"name": "trigger",
"in": "query",
"required": false,
"description": "Filter by trigger type.",
"schema": {
"description": "Filter by trigger type.",
"type": "string",
"minLength": 1
}
},
{
"name": "startDate",
"in": "query",
"required": false,
"description": "Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.",
"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))$",
"description": "Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant."
}
},
{
"name": "endDate",
"in": "query",
"required": false,
"description": "Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.",
"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))$",
"description": "Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum workflow runs to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"schema": {
"default": 50,
"description": "Maximum workflow runs to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"schema": {
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
"type": "string",
"minLength": 1
}
},
{
"name": "order",
"in": "query",
"required": false,
"description": "Sort direction by run start time. This list is sortable only by run start time, so it takes `order` in place of `sortBy`/`sortOrder`, which it rejects.",
"schema": {
"default": "desc",
"description": "Sort direction by run start time. This list is sortable only by run start time, so it takes `order` in place of `sortBy`/`sortOrder`, which it rejects.",
"type": "string",
"enum": ["asc", "desc"]
}
}
],
"responses": {
"200": {
"description": "A page of workflow runs.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowRunListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/runs/{runId}": {
"get": {
"operationId": "getWorkflowRunV2",
"summary": "Get Workflow Run",
"description": "Get current workflow run state, optionally including final and block outputs. With `includeOutput`, `files` lists the files the run produced, each with a `downloadPath`; add `includeFileBase64` to inline their bytes, which answers `413` naming the download path when a single file, or the run's inlined total, exceeds the 16 MiB ceiling. Because inlining reads object storage, this `GET` is not a safe read. A `HEAD` skips the effect but is authorized exactly as the `GET` is, so it answers `400`, `401`, `403`, or `404` wherever the `GET` would and an empty `200` otherwise. Skipping the effect means skipping the read that produces the payload, so that `200` carries none of the response headers documented below — it answers whether the `GET` would be allowed, not what the `GET` would return.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "runId",
"in": "path",
"required": true,
"description": "Unique workflow run identifier.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
},
{
"name": "includeOutput",
"in": "query",
"required": false,
"description": "Include the final workflow output when true. It does not gate `blockOutputs`, which `selectedOutputs` selects on its own.",
"schema": {
"description": "Include the final workflow output when true. It does not gate `blockOutputs`, which `selectedOutputs` selects on its own.",
"type": "boolean"
}
},
{
"name": "selectedOutputs",
"in": "query",
"required": false,
"description": "Comma-separated block output references to include, as `blockId` or `blockId.path`. Block *names* are not resolved here — unlike the execute request, this resource reads a recorded run and matches ids only, so a name selects nothing and yields an empty `blockOutputs`.",
"schema": {
"description": "Comma-separated block output references to include, as `blockId` or `blockId.path`. Block *names* are not resolved here — unlike the execute request, this resource reads a recorded run and matches ids only, so a name selects nothing and yields an empty `blockOutputs`.",
"type": "string"
}
},
{
"name": "includeFileBase64",
"in": "query",
"required": false,
"description": "Inline each produced file's bytes as base64. Requires `includeOutput`. A file above the inline ceiling answers `413` naming its download path; fetch large files from `downloadPath` instead.",
"schema": {
"description": "Inline each produced file's bytes as base64. Requires `includeOutput`. A file above the inline ceiling answers `413` naming its download path; fetch large files from `downloadPath` instead.",
"type": "boolean"
}
},
{
"name": "base64MaxBytes",
"in": "query",
"required": false,
"description": "Per-file inline ceiling, lowering but never raising the server limit of 16 MiB.",
"schema": {
"description": "Per-file inline ceiling, lowering but never raising the server limit of 16 MiB.",
"type": "integer",
"minimum": 1,
"maximum": 16777216
}
}
],
"responses": {
"200": {
"description": "The workflow run status.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowRunStatusResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/runs/{runId}/files/{fileId}": {
"get": {
"operationId": "downloadWorkflowRunFileV2",
"summary": "Download Workflow Run File",
"description": "Download one file a run produced. The run resource reports the files a run emitted; address one of them by its `id` here. Run output carries `/api/files/serve/...` URLs that reject API keys, so this is the byte path out of a run for an API-key caller. Execution objects are not retained indefinitely, so a `404` for a file an older run produced is expected rather than a fault. Runs are hard-deleted once they pass the payer's log retention window, so an older run is simply absent rather than reported as removed. The window is 30 days from run start on the free plan, unbounded on Pro and Team, and set per organization on Enterprise with an optional per-workspace override. Downloading records an audit event, so it is not a safe read. A `HEAD` skips the effect but is authorized exactly as the `GET` is, so it answers `400`, `401`, `403`, or `404` wherever the `GET` would and an empty `200` otherwise. Skipping the effect means skipping the read that produces the payload, so that `200` carries none of the response headers documented below — it answers whether the `GET` would be allowed, not what the `GET` would return. In particular a `HEAD` does not report `Content-Length`, so it cannot be used to size a download in advance; read the size from the file resource instead.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "runId",
"in": "path",
"required": true,
"description": "Unique workflow run identifier.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
},
{
"name": "fileId",
"in": "path",
"required": true,
"description": "Identifier of a file the run produced, as reported by the run resource.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"description": "Identifier of a file the run produced, as reported by the run resource."
}
}
],
"responses": {
"200": {
"description": "The run file bytes.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
},
"Content-Type": {
"$ref": "#/components/headers/Content-Type"
},
"Content-Disposition": {
"$ref": "#/components/headers/Content-Disposition"
},
"Content-Length": {
"$ref": "#/components/headers/Content-Length"
}
},
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/runs/{runId}/resume": {
"post": {
"operationId": "resumeWorkflowRunV2",
"summary": "Resume Workflow Run",
"description": "Resume one human-in-the-loop pause context. The resumed attempt receives a new run identifier and may complete synchronously or return a queue receipt.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "runId",
"in": "path",
"required": true,
"description": "Unique workflow run identifier.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
}
],
"requestBody": {
"required": true,
"description": "Pause context and optional input used to resume a workflow run.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResumeWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The resumed workflow attempt completed synchronously.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResumeWorkflowSyncResponse"
}
}
}
},
"202": {
"description": "The resumed workflow attempt was queued.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResumeWorkflowQueuedResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/UsageLimitExceeded"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{workflowId}/runs/{runId}/cancel": {
"post": {
"operationId": "cancelRunV2",
"summary": "Cancel Workflow Run",
"description": "Request cancellation of a running, queued, or paused workflow run. Cancelling a run already in a terminal state succeeds with no effect. A run produced by a table workflow group is a `409` when its cell can no longer accept the cancellation.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "workflowId",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "runId",
"in": "path",
"required": true,
"description": "Unique workflow run identifier.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
}
],
"responses": {
"200": {
"description": "The cancellation outcome.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelWorkflowRunResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/folders": {
"get": {
"operationId": "listWorkflowsFolders",
"summary": "List Workflow Folders",
"description": "List canonical workflow folders in a workspace. The bounded set is returned in one page; `nextCursor` is always null. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"description": "Workspace whose folders should be listed.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace whose folders should be listed."
}
},
{
"name": "parentPath",
"in": "query",
"required": false,
"description": "Restrict results to direct children of this parent path.",
"schema": {
"description": "Restrict results to direct children of this parent path.",
"$ref": "#/components/schemas/FolderPathInput"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Case-insensitive substring match against the folder name.",
"schema": {
"description": "Case-insensitive substring match against the folder name.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "sortBy",
"in": "query",
"required": false,
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"schema": {
"default": "name",
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
"type": "string",
"enum": ["name", "createdAt", "updatedAt"]
}
},
{
"name": "sortOrder",
"in": "query",
"required": false,
"description": "Sort direction.",
"schema": {
"default": "asc",
"description": "Sort direction.",
"type": "string",
"enum": ["asc", "desc"]
}
}
],
"responses": {
"200": {
"description": "A list of workflow folders.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowFolderListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"post": {
"operationId": "createWorkflowsFolder",
"summary": "Create Workflow Folder",
"description": "Create a canonical workflow folder in a workspace. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"requestBody": {
"required": true,
"description": "Workspace and canonical path for a new workflow folder.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkflowFolderRequest"
}
}
}
},
"responses": {
"201": {
"description": "The created workflow folder.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkflowFolderResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"patch": {
"operationId": "relocateWorkflowsFolder",
"summary": "Rename or Move Workflow Folder",
"description": "Rename or move a workflow folder and its descendants to a canonical path. A workspace folder tree over 10,000 folders is a `413`.",
"tags": ["Workflows"],
"requestBody": {
"required": true,
"description": "Current and destination paths for a workflow folder.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelocateWorkflowFolderRequest"
}
}
}
},
"responses": {
"200": {
"description": "The relocated workflow folder.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelocateWorkflowFolderResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"415": {
"$ref": "#/components/responses/UnsupportedMediaType"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteWorkflowsFolder",
"summary": "Delete Workflow Folder",
"description": "Delete a workflow folder, optionally including its descendants and workflows.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"description": "Workspace containing the folder.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace containing the folder."
}
},
{
"name": "path",
"in": "query",
"required": true,
"description": "Path of the folder to delete.",
"schema": {
"description": "Path of the folder to delete.",
"$ref": "#/components/schemas/NonRootFolderPathInput"
}
},
{
"name": "recursive",
"in": "query",
"required": false,
"description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
"schema": {
"description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
"enum": [
"true",
"1",
"yes",
"on",
"y",
"enabled",
"false",
"0",
"no",
"off",
"n",
"disabled"
],
"default": "false",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The workflow folder was deleted.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteWorkflowFolderResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
}
},
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description."
}
},
"headers": {
"Content-Type": {
"description": "MIME type of the file, defaulting to application/octet-stream when the stored type is unavailable.",
"schema": {
"type": "string",
"title": "Content type",
"description": "MIME type of the file, defaulting to application/octet-stream when the stored type is unavailable."
}
},
"Content-Disposition": {
"description": "Attachment disposition containing sanitized and RFC 5987 encoded filenames.",
"schema": {
"type": "string",
"title": "Content disposition",
"description": "Attachment disposition containing sanitized and RFC 5987 encoded filenames."
}
},
"Content-Length": {
"description": "File size in bytes.",
"schema": {
"type": "string",
"pattern": "^(0|[1-9]\\d*)$",
"title": "Content length",
"description": "File size in bytes."
}
},
"X-RateLimit-Limit": {
"description": "Maximum requests allowed in the current window.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"title": "Rate limit",
"description": "Maximum requests allowed in the current window."
}
},
"X-RateLimit-Remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"title": "Rate limit remaining",
"description": "Requests remaining in the current window."
}
},
"X-RateLimit-Reset": {
"description": "ISO 8601 timestamp when the current rate-limit window resets.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"title": "Rate limit reset",
"description": "ISO 8601 timestamp when the current rate-limit window resets."
}
},
"Retry-After": {
"description": "Seconds to wait before retrying, 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."
}
},
"X-Run-Id": {
"description": "Identifier assigned to the workflow run.",
"schema": {
"type": "string",
"minLength": 1,
"title": "Run identifier",
"description": "Identifier assigned to the workflow run."
}
}
},
"responses": {
"BadRequest": {
"description": "The request is invalid. 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"
}
}
}
}
},
"Unauthorized": {
"description": "The API key is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "UNAUTHORIZED",
"message": "API key required"
}
}
}
}
},
"UsageLimitExceeded": {
"description": "The workspace has exceeded its usage or billing limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Usage limit exceeded. Please upgrade your plan to continue."
}
}
}
}
},
"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"
}
}
}
}
}
},
"NotFound": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "NOT_FOUND",
"message": "Not found"
}
}
}
}
},
"Conflict": {
"description": "The request conflicts with current resource state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "CONFLICT",
"message": "Webhook path already in use"
}
}
}
}
},
"RunIdConflict": {
"description": "The run cannot be started, for one of two causes named by `error.details.code`: `RUN_ID_CONFLICT` when the supplied `X-Run-Id` is already claimed, and `CALL_CHAIN_DEPTH_EXCEEDED` when the incoming `X-Sim-Via` chain has reached the maximum workflow-to-workflow call depth.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "CONFLICT",
"message": "Run ID has already been used",
"details": {
"code": "RUN_ID_CONFLICT",
"runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
}
}
}
}
}
},
"PayloadTooLarge": {
"description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "PAYLOAD_TOO_LARGE",
"message": "Request body is too large"
}
}
}
}
},
"UnsupportedMediaType": {
"description": "The request uses an unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Request body must be sent as application/json"
}
}
}
}
},
"Locked": {
"description": "The resource is locked and cannot be modified.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "LOCKED",
"message": "Workflow is locked"
}
}
}
}
},
"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"
}
}
}
}
}
},
"ClientClosedRequest": {
"description": "The client closed the connection before the response was produced. An abort can leave the run going, so `error.details.runId` carries the run id — reconcile against the runs resource rather than starting another run.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "CLIENT_CLOSED_REQUEST",
"message": "Client cancelled request",
"details": {
"runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
}
}
}
}
}
},
"InternalError": {
"description": "An unexpected server error occurred.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
},
"example": {
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
}
}
}
}
},
"ServiceUnavailable": {
"description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
"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"
}
}
}
}
}
},
"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 details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `ORGANIZATION_PLAN_REQUIRED` — The organization has no active organization subscription (Pro for Teams, Max for Teams, or Enterprise).\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address.\n- `WORKSPACE_PLAN_CAPABILITY_REQUIRED` — The workspace's plan does not include a capability this request depends on. The message names the capability; upgrading the workspace's plan is the remedy.\n- `CHAT_AUTH_MODE_NOT_PERMITTED` — The workspace's permission group does not allow the chat authentication mode the request selected. A mode already saved on the deployment may still be re-saved; changing to a disallowed one cannot.\n- `CONNECTOR_MANAGED_RESOURCE_READ_ONLY` — This resource is managed by a knowledge base connector and cannot be edited directly. Change it at the source and re-sync, or exclude the document from the connector."
}
},
"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."
}
}
]
},
"FolderPathInput": {
"title": "Folder path input",
"description": "Folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
"maxLength": 4096,
"type": "string"
},
"WorkflowListItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"webUrl": {
"type": "string",
"format": "uri",
"description": "Canonical absolute URL for opening this resource in the Sim web application."
},
"name": {
"type": "string",
"description": "Workflow name.",
"examples": ["Customer support triage"]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Workflow description, or null when none is set."
},
"folderPath": {
"type": "string",
"title": "Folder path",
"description": "Canonical containing-folder path; `/` is the workspace root.",
"maxLength": 4096,
"examples": ["/Operations"]
},
"workspaceId": {
"type": "string",
"description": "Workspace that owns the workflow."
},
"isDeployed": {
"type": "boolean",
"description": "Whether the workflow has an active deployment."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 activation timestamp, or null when not deployed.",
"format": "date-time"
},
"runCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Runs that finished successfully. Failed, cancelled, and paused runs are not counted, and the counter is never reduced when a run ages out of log retention — so it does not match the size of `GET /api/v2/workflows/{workflowId}/runs`, in either direction."
},
"lastRunAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp of the latest run counted by `runCount`, or null when none has been. Stamped by the same successful-run path, so a workflow whose only runs failed reports null here.",
"format": "date-time"
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was last updated.",
"format": "date-time"
}
},
"required": [
"id",
"webUrl",
"name",
"description",
"folderPath",
"workspaceId",
"isDeployed",
"deployedAt",
"runCount",
"lastRunAt",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"title": "Workflow summary",
"description": "Summary of a workflow and its deployment and run state."
},
"WorkflowListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowListItem"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false,
"title": "Workflow list response",
"description": "A cursor-paginated page of workflow summaries.",
"examples": [
{
"data": [
{
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
],
"nextCursor": null
}
]
},
"SeededWorkflowBlock": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Block identifier."
},
"type": {
"type": "string",
"description": "Registered block type."
},
"name": {
"type": "string",
"description": "Block display name."
}
},
"required": ["id", "type", "name"],
"additionalProperties": false,
"title": "Seeded workflow block",
"description": "A block the platform placed in a newly created workflow."
},
"CreateWorkflowResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"webUrl": {
"type": "string",
"format": "uri",
"description": "Canonical absolute URL for opening this resource in the Sim web application."
},
"name": {
"type": "string",
"description": "Workflow name.",
"examples": ["Customer support triage"]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Workflow description, or null when none is set."
},
"folderPath": {
"type": "string",
"title": "Folder path",
"description": "Canonical containing-folder path; `/` is the workspace root.",
"maxLength": 4096,
"examples": ["/Operations"]
},
"workspaceId": {
"type": "string",
"description": "Workspace that owns the workflow."
},
"isDeployed": {
"type": "boolean",
"description": "Whether the workflow has an active deployment."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 activation timestamp, or null when not deployed.",
"format": "date-time"
},
"runCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Runs that finished successfully. Failed, cancelled, and paused runs are not counted, and the counter is never reduced when a run ages out of log retention — so it does not match the size of `GET /api/v2/workflows/{workflowId}/runs`, in either direction."
},
"lastRunAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp of the latest run counted by `runCount`, or null when none has been. Stamped by the same successful-run path, so a workflow whose only runs failed reports null here.",
"format": "date-time"
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was last updated.",
"format": "date-time"
},
"blocks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SeededWorkflowBlock"
},
"description": "Blocks seeded into the new workflow. Contains the start block; attach edges to its `id`."
}
},
"required": [
"id",
"webUrl",
"name",
"description",
"folderPath",
"workspaceId",
"isDeployed",
"deployedAt",
"runCount",
"lastRunAt",
"createdAt",
"updatedAt",
"blocks"
],
"additionalProperties": false,
"title": "Create workflow result",
"description": "The created workflow and the blocks it was seeded with."
},
"CreateWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/CreateWorkflowResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Create workflow response",
"description": "The created workflow and the blocks it was seeded with.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": false,
"deployedAt": null,
"runCount": 0,
"lastRunAt": null,
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z",
"blocks": [
{
"id": "start-1",
"type": "starter",
"name": "Start"
}
]
}
}
]
},
"CreateWorkflowRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace in which to create the workflow."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Workflow name."
},
"description": {
"description": "Optional workflow description.",
"anyOf": [
{
"type": "string",
"maxLength": 50000
},
{
"type": "null"
}
]
},
"folderPath": {
"$ref": "#/components/schemas/FolderPathInput"
}
},
"required": ["workspaceId", "name"],
"additionalProperties": false,
"title": "Create workflow request",
"description": "Name, description, workspace, and optional folder for a new workflow."
},
"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."
},
"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."
},
"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."
},
"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."
},
"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."
},
"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": "The editable draft graph of a workflow: blocks, edges, derived loop and parallel containers, and variables."
},
"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": {}
}
}
]
},
"WorkflowLintReport": {
"type": "object",
"properties": {
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block the finding is about."
},
"blockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the block, when it has one."
},
"blockType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Registered type of the block, when it has one."
}
},
"required": ["blockId", "blockName", "blockType"],
"additionalProperties": false
},
"description": "Blocks with no incoming edge. A trigger block is naturally a source; anything else here is unreachable."
},
"sinks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block the finding is about."
},
"blockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the block, when it has one."
},
"blockType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Registered type of the block, when it has one."
}
},
"required": ["blockId", "blockName", "blockType"],
"additionalProperties": false
},
"description": "Blocks with no outgoing edge."
},
"orphanBlocks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block the finding is about."
},
"blockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the block, when it has one."
},
"blockType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Registered type of the block, when it has one."
}
},
"required": ["blockId", "blockName", "blockType"],
"additionalProperties": false
},
"description": "Blocks with neither an incoming nor an outgoing edge."
},
"emptyOutgoingPorts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block the finding is about."
},
"blockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the block, when it has one."
},
"blockType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Registered type of the block, when it has one."
},
"handle": {
"type": "string",
"description": "Source handle with nothing connected to it."
},
"label": {
"type": "string",
"description": "Human-readable name of the port."
}
},
"required": ["blockId", "blockName", "blockType", "handle", "label"],
"additionalProperties": false
},
"description": "Branch and container ports that lead nowhere."
},
"invalidBranchPorts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block the finding is about."
},
"blockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the block, when it has one."
},
"blockType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Registered type of the block, when it has one."
},
"sourceHandle": {
"type": "string",
"description": "Source handle that does not match the block."
},
"reason": {
"type": "string",
"description": "Why the handle is not valid for this block."
}
},
"required": ["blockId", "blockName", "blockType", "sourceHandle", "reason"],
"additionalProperties": false
},
"description": "Condition and router edges whose source handle names no real branch."
},
"invalidConnectionTargets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sourceBlockId": {
"type": "string",
"description": "Block the edge leaves."
},
"sourceBlockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the source block."
},
"sourceHandle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Handle the edge leaves from."
},
"targetBlockId": {
"type": "string",
"description": "Block the edge points at."
},
"reason": {
"type": "string",
"description": "Why the target is not a legal destination."
}
},
"required": [
"sourceBlockId",
"sourceBlockName",
"sourceHandle",
"targetBlockId",
"reason"
],
"additionalProperties": false
},
"description": "Edges pointing at a block that cannot legally receive them."
},
"fieldIssues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block the finding is about."
},
"blockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the block, when it has one."
},
"blockType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Registered type of the block, when it has one."
},
"missingRequiredFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Required sub-block fields that resolve empty in the active mode."
},
"inactiveModeValues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"canonicalId": {
"type": "string",
"description": "Canonical parameter the two sub-block modes share."
},
"activeMemberId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sub-block the runtime reads, where the value should live."
},
"inactiveMemberId": {
"type": "string",
"description": "Sub-block holding the stranded value, which the runtime ignores."
},
"kind": {
"type": "string",
"enum": ["credential", "resource", "other"],
"description": "What kind of value is stranded."
}
},
"required": ["canonicalId", "activeMemberId", "inactiveMemberId", "kind"],
"additionalProperties": false
},
"description": "Values stranded on the inactive member of a canonical pair."
}
},
"required": [
"blockId",
"blockName",
"blockType",
"missingRequiredFields",
"inactiveModeValues"
],
"additionalProperties": false
},
"description": "Per-block configuration problems. The most actionable part of the report for a headless graph builder: a block missing a required field will fail at run time."
},
"unresolvedReferences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block the finding is about."
},
"blockName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the block, when it has one."
},
"blockType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Registered type of the block, when it has one."
},
"field": {
"type": "string",
"description": "Sub-block field holding the reference."
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "The reference, or references, that did not resolve."
},
"kind": {
"type": "string",
"enum": ["credential", "resource", "custom-tool", "mcp-tool", "skill"],
"description": "What kind of entity the reference was expected to name."
},
"reason": {
"type": "string",
"description": "Why the reference does not resolve."
}
},
"required": ["blockId", "blockName", "blockType", "field", "value", "kind", "reason"],
"additionalProperties": false
},
"description": "Credential, resource, tool, and skill references that do not resolve. These values are still persisted; they are reported, not dropped."
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory notes about the report itself."
}
},
"required": [
"sources",
"sinks",
"orphanBlocks",
"emptyOutgoingPorts",
"invalidBranchPorts",
"invalidConnectionTargets",
"fieldIssues",
"unresolvedReferences",
"notes"
],
"additionalProperties": false,
"title": "Workflow lint report",
"description": "Advisory findings about the saved graph. Findings never block the write; they tell a caller what will misbehave at run time."
},
"ReplaceWorkflowStateResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the workflow whose draft graph was written."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal notes about blocks and edges that were normalized or dropped before persistence. Empty when there was nothing to report."
},
"needsRedeployment": {
"type": "boolean",
"description": "Whether the live deployment now differs from the draft. A graph write never changes what the deployed endpoint serves; deploy to publish it."
},
"lint": {
"$ref": "#/components/schemas/WorkflowLintReport"
},
"dryRun": {
"type": "boolean",
"description": "Whether this request only validated. `true` means nothing was persisted; the findings describe what a committed write of the same body would produce."
}
},
"required": ["id", "warnings", "needsRedeployment", "lint", "dryRun"],
"additionalProperties": false,
"title": "Replace workflow state result",
"description": "Outcome of replacing a workflow draft graph, with its advisory findings."
},
"ReplaceWorkflowStateResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/ReplaceWorkflowStateResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Replace workflow state response",
"description": "Outcome of replacing a workflow draft graph.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"warnings": [],
"needsRedeployment": true,
"dryRun": false,
"lint": {
"sources": [],
"sinks": [],
"orphanBlocks": [],
"emptyOutgoingPorts": [],
"invalidBranchPorts": [],
"invalidConnectionTargets": [],
"fieldIssues": [],
"unresolvedReferences": [],
"notes": []
}
}
}
]
},
"WorkflowBlockInput": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Block identifier, unique within the workflow."
},
"type": {
"type": "string",
"minLength": 1,
"description": "Registered block type."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"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"],
"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"],
"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"],
"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"]
}
}
},
"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"],
"title": "Workflow block",
"description": "One node of a workflow graph and its configuration."
},
"WorkflowEdgeInput": {
"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"],
"title": "Workflow edge",
"description": "A directed connection between two blocks."
},
"WorkflowLoopInput": {
"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"],
"title": "Workflow loop",
"description": "A loop container derived from the workflow blocks."
},
"WorkflowParallelInput": {
"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"],
"title": "Workflow parallel",
"description": "A parallel container derived from the workflow blocks."
},
"WorkflowVariableInput": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Variable identifier."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Variable name, referenced from block inputs."
},
"type": {
"type": "string",
"enum": ["string", "number", "boolean", "object", "array", "plain"],
"description": "Declared variable type."
},
"value": {
"description": "Variable value; free-form and validated per `type` at use time."
}
},
"required": ["id", "name", "type", "value"],
"title": "Workflow variable",
"description": "A workflow-scoped variable."
},
"ReplaceWorkflowStateRequest": {
"type": "object",
"properties": {
"blocks": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/components/schemas/WorkflowBlockInput"
},
"description": "Blocks keyed by block id."
},
"edges": {
"maxItems": 10000,
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowEdgeInput"
},
"description": "Directed connections between blocks."
},
"loops": {
"description": "Ignored on write: loop containers are recomputed from `blocks`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/components/schemas/WorkflowLoopInput"
}
},
"parallels": {
"description": "Ignored on write: parallel containers are recomputed from `blocks`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/components/schemas/WorkflowParallelInput"
}
},
"variables": {
"description": "Replacement variable set. Omit to leave the stored variables untouched.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/components/schemas/WorkflowVariableInput"
}
}
},
"required": ["blocks", "edges"],
"additionalProperties": false,
"title": "Replace workflow state request",
"description": "A complete replacement draft graph for a workflow.",
"examples": [
{
"blocks": {},
"edges": []
}
]
},
"WorkflowSkippedItem": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"block_not_found",
"invalid_block_type",
"block_not_allowed",
"block_locked",
"tool_not_allowed",
"invalid_edge_target",
"invalid_edge_source",
"invalid_edge_scope",
"invalid_source_handle",
"invalid_target_handle",
"invalid_subblock_field",
"missing_required_params",
"invalid_subflow_parent",
"nested_subflow_not_allowed",
"duplicate_block_name",
"reserved_block_name",
"retry_not_supported",
"duplicate_trigger",
"duplicate_single_instance_block",
"disabled_ancestor"
],
"description": "Machine-readable reason the engine declined an operation."
},
"operationType": {
"type": "string",
"description": "The `operation_type` that was declined."
},
"blockId": {
"type": "string",
"description": "Block the declined operation targeted."
},
"reason": {
"type": "string",
"description": "Human-readable explanation."
},
"details": {
"description": "Additional context for the reason; keys depend on `type`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "One piece of engine-supplied context for the reason."
}
}
},
"required": ["type", "operationType", "blockId", "reason"],
"additionalProperties": false,
"title": "Workflow skipped item",
"description": "One operation the edit engine did not apply."
},
"WorkflowInputValidationError": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block whose input was rejected."
},
"blockType": {
"type": "string",
"description": "Type of the block whose input was rejected."
},
"field": {
"type": "string",
"description": "Sub-block field that was rejected."
},
"error": {
"type": "string",
"description": "Why the value was rejected."
}
},
"required": ["blockId", "blockType", "field", "error"],
"additionalProperties": false,
"title": "Workflow input validation error",
"description": "One block input that was dropped rather than persisted."
},
"ApplyWorkflowOperationsResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the workflow whose draft graph was written."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal notes about blocks and edges that were normalized or dropped before persistence. Empty when there was nothing to report."
},
"needsRedeployment": {
"type": "boolean",
"description": "Whether the live deployment now differs from the draft. A graph write never changes what the deployed endpoint serves; deploy to publish it."
},
"applied": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Operations the engine applied."
},
"skipped": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowSkippedItem"
},
"description": "Operations the engine declined. Empty when everything applied."
},
"deferred": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowSkippedItem"
},
"description": "Forward-referencing edges the engine recorded rather than applied. These are NOT failures: the engine wires each one as soon as its target block exists, in this batch or a later one. Do not re-issue them."
},
"inputValidationErrors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowInputValidationError"
},
"description": "Block inputs that were dropped rather than persisted, and only those. The rest of the operation still applied. References that merely fail to resolve stay persisted and are reported in `lint.unresolvedReferences` instead."
},
"mintedBlockIds": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"description": "The id the block was actually given."
},
"description": "The id each newly created block was actually given, keyed by the `block_id` you asked for, and present only for the ones that differ. A `block_id` on an `add` or `insert_into_subflow` that is not already a UUID is replaced with a minted one, so this is how you learn what to reference afterwards. Within a single batch you can keep using your own ids — references between operations are remapped for you — but a later request must use the minted id, so send your own UUIDs when you want an id you chose to survive."
},
"lint": {
"$ref": "#/components/schemas/WorkflowLintReport"
},
"dryRun": {
"type": "boolean",
"description": "Whether this request only evaluated. `true` means nothing was persisted; the outcome describes what a committed apply of the same body would produce."
}
},
"required": [
"id",
"warnings",
"needsRedeployment",
"applied",
"skipped",
"deferred",
"inputValidationErrors",
"mintedBlockIds",
"lint",
"dryRun"
],
"additionalProperties": false,
"title": "Apply workflow operations result",
"description": "Outcome of a batch of semantic edits against a workflow graph."
},
"ApplyWorkflowOperationsResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/ApplyWorkflowOperationsResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Apply workflow operations response",
"description": "Outcome of a batch of semantic edits.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"applied": 1,
"skipped": [],
"deferred": [],
"inputValidationErrors": [],
"mintedBlockIds": {
"triage": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77"
},
"lint": {
"sources": [],
"sinks": [],
"orphanBlocks": [],
"emptyOutgoingPorts": [],
"invalidBranchPorts": [],
"invalidConnectionTargets": [],
"fieldIssues": [
{
"blockId": "agent-1",
"blockName": "Triage",
"blockType": "agent",
"missingRequiredFields": ["systemPrompt"],
"inactiveModeValues": []
}
],
"unresolvedReferences": [],
"notes": []
},
"warnings": [],
"needsRedeployment": true,
"dryRun": false
}
}
]
},
"WorkflowEditOperation": {
"oneOf": [
{
"type": "object",
"properties": {
"operation_type": {
"type": "string",
"const": "add",
"description": "Create a new block."
},
"block_id": {
"type": "string",
"minLength": 1,
"description": "Block the operation targets. For `add`, the id the new block will be given."
},
"params": {
"type": "object",
"properties": {
"type": {
"type": "string",
"minLength": 1,
"description": "Registered block type."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Block display name."
}
},
"required": ["type", "name"],
"additionalProperties": {
"description": "One block-specific input or connection descriptor."
},
"description": "Block type and name, plus any block-specific configuration. Beyond `type` and `name` the accepted keys are `inputs`, `connections`, `retry`, `triggerMode`, and `advancedMode`. `inputs` carries the block's own configuration keyed by sub-block id, for example `inputs: { model: \"gpt-4o\", systemPrompt: \"...\" }` — never wrapped in `subBlocks`. Block-level settings sit beside `inputs`, never inside it: `retry`, `triggerMode`, `advancedMode`. `connections` is keyed by source handle and each value is a target block id, `{ block, handle }`, or an array of either; `success` is accepted as an alias for the `source` handle."
}
},
"required": ["operation_type", "block_id", "params"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation_type": {
"type": "string",
"const": "edit",
"description": "Change an existing block: its inputs, name, or connections."
},
"block_id": {
"type": "string",
"minLength": 1,
"description": "Block the operation targets. For `add`, the id the new block will be given."
},
"params": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "One operation parameter; see the description for the accepted keys."
},
"description": "Fields to change on the target block. Send only what changes. Accepted keys: `inputs`, `name`, `connections`, `removeEdges`, `nestedNodes`, `retry`, `triggerMode`, `advancedMode`. `inputs` carries the block's own configuration keyed by sub-block id, for example `inputs: { model: \"gpt-4o\", systemPrompt: \"...\" }` — never wrapped in `subBlocks`. Block-level settings sit beside `inputs`, never inside it: `retry`, `triggerMode`, `advancedMode`. `connections` is keyed by source handle and each value is a target block id, `{ block, handle }`, or an array of either; `success` is accepted as an alias for the `source` handle. Re-sending `connections` replaces that block's outgoing edges, so use `removeEdges` — `[{ targetBlockId, sourceHandle? }]`, `sourceHandle` defaulting to `source` — to drop one edge without restating the rest."
}
},
"required": ["operation_type", "block_id", "params"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation_type": {
"type": "string",
"const": "delete",
"description": "Remove a block and every edge touching it."
},
"block_id": {
"type": "string",
"minLength": 1,
"description": "Block the operation targets. For `add`, the id the new block will be given."
}
},
"required": ["operation_type", "block_id"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation_type": {
"type": "string",
"const": "insert_into_subflow",
"description": "Create a block inside a loop or parallel container."
},
"block_id": {
"type": "string",
"minLength": 1,
"description": "Block the operation targets. For `add`, the id the new block will be given."
},
"params": {
"type": "object",
"properties": {
"subflowId": {
"type": "string",
"minLength": 1,
"description": "Loop or parallel container to insert the block into."
},
"type": {
"type": "string",
"minLength": 1,
"description": "Registered block type."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Block display name."
}
},
"required": ["subflowId", "type", "name"],
"additionalProperties": {
"description": "One block-specific input or connection descriptor."
},
"description": "Container, block type and name, plus any block-specific configuration. Takes the same keys as an `add`: `inputs`, `connections`, `retry`, `triggerMode`, `advancedMode`. `inputs` carries the block's own configuration keyed by sub-block id, for example `inputs: { model: \"gpt-4o\", systemPrompt: \"...\" }` — never wrapped in `subBlocks`. Block-level settings sit beside `inputs`, never inside it: `retry`, `triggerMode`, `advancedMode`. `connections` is keyed by source handle and each value is a target block id, `{ block, handle }`, or an array of either; `success` is accepted as an alias for the `source` handle."
}
},
"required": ["operation_type", "block_id", "params"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation_type": {
"type": "string",
"const": "extract_from_subflow",
"description": "Move a block out of its loop or parallel container."
},
"block_id": {
"type": "string",
"minLength": 1,
"description": "Block the operation targets. For `add`, the id the new block will be given."
},
"params": {
"type": "object",
"properties": {
"subflowId": {
"type": "string",
"minLength": 1,
"description": "Loop or parallel container the block moves into or out of."
}
},
"required": ["subflowId"],
"additionalProperties": {
"description": "One block-specific input."
},
"description": "Container identifier, plus any block-specific inputs."
}
},
"required": ["operation_type", "block_id", "params"],
"additionalProperties": false
}
],
"title": "Workflow edit operation",
"description": "One semantic edit against a workflow graph."
},
"ApplyWorkflowOperationsRequest": {
"type": "object",
"properties": {
"operations": {
"minItems": 1,
"maxItems": 200,
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowEditOperation"
},
"description": "Edits to apply, in a single batch."
},
"atomic": {
"default": false,
"description": "Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead.",
"type": "boolean"
},
"layout": {
"default": "targeted",
"description": "Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied.",
"type": "string",
"enum": ["targeted", "none"]
},
"setBlockEnabled": {
"description": "Blocks to enable or disable, applied after `operations`. Disabling a loop or parallel cascades to its unlocked descendants; enabling a block whose container is disabled is declined.",
"maxItems": 200,
"type": "array",
"items": {
"type": "object",
"properties": {
"block_id": {
"type": "string",
"minLength": 1,
"description": "Block the operation targets. For `add`, the id the new block will be given."
},
"enabled": {
"type": "boolean",
"description": "Whether the block should run."
}
},
"required": ["block_id", "enabled"],
"additionalProperties": false
}
}
},
"required": ["operations"],
"additionalProperties": false,
"title": "Apply workflow operations request",
"description": "A batch of semantic edits against a workflow graph.",
"examples": [
{
"operations": [
{
"operation_type": "add",
"block_id": "agent-1",
"params": {
"type": "agent",
"name": "Triage"
}
}
]
}
]
},
"ApplyWorkflowVariablesResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the workflow whose variables were updated."
},
"variableCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Variables the workflow now holds."
},
"changed": {
"type": "boolean",
"description": "Whether anything actually changed. A no-op batch answers `200` with `false`."
}
},
"required": ["id", "variableCount", "changed"],
"additionalProperties": false,
"title": "Apply workflow variables result",
"description": "Outcome of a workflow variable update."
},
"ApplyWorkflowVariablesResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/ApplyWorkflowVariablesResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Apply workflow variables response",
"description": "Outcome of a workflow variable update.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"variableCount": 3,
"changed": true
}
}
]
},
"ApplyWorkflowVariablesRequest": {
"type": "object",
"properties": {
"operations": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"const": "add",
"description": "Create a variable with this name."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Variable name."
},
"type": {
"type": "string",
"enum": ["string", "number", "boolean", "object", "array", "plain"],
"description": "Declared variable type."
},
"value": {
"description": "Variable value, coerced to `type`."
}
},
"required": ["operation", "name", "type", "value"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"const": "edit",
"description": "Replace the value, and optionally the type, of an existing variable."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the variable to update."
},
"type": {
"description": "Replacement type; the stored type is kept when omitted.",
"type": "string",
"enum": ["string", "number", "boolean", "object", "array", "plain"]
},
"value": {
"description": "Replacement value, coerced to the effective type."
}
},
"required": ["operation", "name", "value"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"operation": {
"type": "string",
"const": "delete",
"description": "Remove the variable with this name."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Name of the variable to remove."
}
},
"required": ["operation", "name"],
"additionalProperties": false
}
],
"description": "One variable change."
},
"description": "Variable changes to apply, in order."
}
},
"required": ["operations"],
"additionalProperties": false,
"title": "Apply workflow variables request",
"description": "Additions, edits, and deletions against a workflow’s variables."
},
"DuplicateWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowListItem"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Duplicate workflow response",
"description": "The created copy.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage (copy)",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": false,
"deployedAt": null,
"runCount": 0,
"lastRunAt": null,
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
}
]
},
"DuplicateWorkflowRequest": {
"type": "object",
"properties": {
"name": {
"description": "Name for the copy. Defaults to the source name, deduplicated within the folder.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"folderPath": {
"description": "Destination folder path. Defaults to the source workflow's folder.",
"$ref": "#/components/schemas/FolderPathInput"
}
},
"additionalProperties": false,
"title": "Duplicate workflow request",
"description": "Optional name and destination folder for the copy."
},
"RestoreWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowListItem"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Restore workflow response",
"description": "The restored workflow.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
}
]
},
"MoveWorkflowsResult": {
"type": "object",
"properties": {
"moved": {
"type": "array",
"items": {
"type": "string"
},
"description": "Workflows that were relocated."
},
"failed": {
"type": "array",
"items": {
"type": "string"
},
"description": "Workflows that were not relocated — absent from the workspace, archived, or locked. Best-effort by design: the rest of the batch still moved."
},
"folderPath": {
"type": "string",
"title": "Folder path",
"description": "Canonical destination folder path.",
"maxLength": 4096
}
},
"required": ["moved", "failed", "folderPath"],
"additionalProperties": false,
"title": "Move workflows result",
"description": "Which workflows moved and which did not."
},
"MoveWorkflowsResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/MoveWorkflowsResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Move workflows response",
"description": "Which workflows moved and which did not.",
"examples": [
{
"data": {
"moved": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"],
"failed": [],
"folderPath": "/Operations"
}
}
]
},
"MoveWorkflowsRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace holding every workflow in the batch."
},
"workflowIds": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "Workflows to move. Duplicates are collapsed."
},
"folderPath": {
"description": "Destination folder path; `/` moves the workflows to the workspace root.",
"$ref": "#/components/schemas/FolderPathInput"
}
},
"required": ["workspaceId", "workflowIds", "folderPath"],
"additionalProperties": false,
"title": "Move workflows request",
"description": "Workflows to relocate and the folder to relocate them into."
},
"WorkflowInputField": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Input field name."
},
"type": {
"type": "string",
"description": "Input field type."
},
"description": {
"description": "Optional input field description.",
"type": "string"
}
},
"required": ["name", "type"],
"additionalProperties": false,
"title": "Workflow input field",
"description": "A deployed API trigger input exposed by a workflow."
},
"WorkflowDetail": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"webUrl": {
"type": "string",
"format": "uri",
"description": "Canonical absolute URL for opening this resource in the Sim web application."
},
"name": {
"type": "string",
"description": "Workflow name.",
"examples": ["Customer support triage"]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Workflow description, or null when none is set."
},
"folderPath": {
"type": "string",
"title": "Folder path",
"description": "Canonical containing-folder path; `/` is the workspace root.",
"maxLength": 4096,
"examples": ["/Operations"]
},
"workspaceId": {
"type": "string",
"description": "Workspace that owns the workflow."
},
"isDeployed": {
"type": "boolean",
"description": "Whether the workflow has an active deployment."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 activation timestamp, or null when not deployed.",
"format": "date-time"
},
"runCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Runs that finished successfully. Failed, cancelled, and paused runs are not counted, and the counter is never reduced when a run ages out of log retention — so it does not match the size of `GET /api/v2/workflows/{workflowId}/runs`, in either direction."
},
"lastRunAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp of the latest run counted by `runCount`, or null when none has been. Stamped by the same successful-run path, so a workflow whose only runs failed reports null here.",
"format": "date-time"
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was last updated.",
"format": "date-time"
},
"variables": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "Structured workflow variable value."
},
"description": "Workflow-scoped variables keyed by variable identifier."
},
"inputs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowInputField"
},
"description": "Input fields exposed by the workflow API trigger."
}
},
"required": [
"id",
"webUrl",
"name",
"description",
"folderPath",
"workspaceId",
"isDeployed",
"deployedAt",
"runCount",
"lastRunAt",
"createdAt",
"updatedAt",
"variables",
"inputs"
],
"additionalProperties": false,
"title": "Workflow detail",
"description": "Full workflow summary with variables and API-trigger input fields."
},
"WorkflowDetailResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowDetail"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Workflow detail response",
"description": "Detailed workflow metadata, variables, and trigger inputs.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z",
"variables": {},
"inputs": []
}
}
]
},
"UpdateWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowListItem"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Update workflow response",
"description": "The updated workflow summary.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
}
]
},
"UpdateWorkflowRequest": {
"type": "object",
"properties": {
"name": {
"description": "Replacement workflow name.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"description": "Replacement workflow description; null clears it.",
"anyOf": [
{
"type": "string",
"maxLength": 50000
},
{
"type": "null"
}
]
},
"folderPath": {
"description": "Destination folder path; `/` moves the workflow to the workspace root.",
"$ref": "#/components/schemas/FolderPathInput"
}
},
"additionalProperties": false,
"title": "Update workflow request",
"description": "Fields to update on an existing workflow."
},
"DeleteWorkflowResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the archived workflow."
},
"deleted": {
"type": "boolean",
"const": true,
"description": "Confirms that the workflow is no longer live."
},
"archived": {
"type": "boolean",
"const": true,
"description": "The workflow was archived, not erased. Its schedules, webhooks, MCP tools, and chats were archived with it, and `POST /workflows/{workflowId}/restore` brings all of them back."
}
},
"required": ["id", "deleted", "archived"],
"additionalProperties": false,
"title": "Delete workflow result",
"description": "Confirmation that a workflow was archived."
},
"DeleteWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/DeleteWorkflowResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Delete workflow response",
"description": "Confirmation that the workflow was archived.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"deleted": true,
"archived": true
}
}
]
},
"WorkflowVersion": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique deployment-version identifier."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Monotonically increasing deployment version number."
},
"name": {
"description": "Optional deployment-version label.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"description": "Optional deployment-version release note.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"isActive": {
"type": "boolean",
"description": "Whether this version is currently serving executions."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when this version was created.",
"format": "date-time"
},
"deployedBy": {
"description": "Display name of the user who created the deployment, when available.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"latestOperationStatus": {
"description": "Latest lifecycle-operation status for this version.",
"anyOf": [
{
"type": "string",
"enum": ["preparing", "activating", "active", "failed", "superseded"]
},
{
"type": "null"
}
]
}
},
"required": ["id", "version", "isActive", "createdAt"],
"additionalProperties": false,
"title": "Workflow version",
"description": "A saved deployment version of a workflow."
},
"WorkflowVersionListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowVersion"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false,
"title": "Workflow version list response",
"description": "A cursor-paginated page of deployment versions.",
"examples": [
{
"data": [
{
"id": "version_3",
"version": 3,
"name": "Escalation routing",
"description": "Adds the priority escalation branch.",
"isActive": true,
"createdAt": "2026-06-12T10:30:00.000Z",
"deployedBy": "Jane Smith",
"latestOperationStatus": "active"
}
],
"nextCursor": null
}
]
},
"DeployedWorkflowState": {
"title": "Deployed workflow state",
"description": "Workflow graph snapshot pinned by a deployment version.",
"type": "object",
"additionalProperties": true
},
"WorkflowVersionDetail": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique deployment-version identifier."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Monotonically increasing deployment version number."
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Version label, or null when unset."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Version release note, or null when unset."
},
"isActive": {
"type": "boolean",
"description": "Whether this version is currently serving executions."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when this version was created.",
"format": "date-time"
},
"state": {
"description": "Deployed workflow graph snapshot pinned by this version, with credential-bearing values redacted to null: `oauth-input`, `password: true`, table sub-block values, sensitive nested tool parameters, and any parameter without authoritative codec metadata.",
"$ref": "#/components/schemas/DeployedWorkflowState"
}
},
"required": ["id", "version", "name", "description", "isActive", "createdAt", "state"],
"additionalProperties": false,
"title": "Workflow version detail",
"description": "A deployment version together with the workflow state it pins."
},
"WorkflowVersionDetailResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowVersionDetail"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Workflow version detail response",
"description": "The deployment version and its pinned workflow graph.",
"examples": [
{
"data": {
"id": "version_3",
"version": 3,
"name": "Escalation routing",
"description": "Adds the priority escalation branch.",
"isActive": true,
"createdAt": "2026-06-12T10:30:00.000Z",
"state": {
"blocks": {},
"edges": []
}
}
}
]
},
"WorkflowVersionMetadata": {
"type": "object",
"properties": {
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Monotonically increasing deployment version number."
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Version label, or null when unset."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Version release note, or null when unset."
}
},
"required": ["version", "name", "description"],
"additionalProperties": false,
"title": "Workflow version metadata",
"description": "Mutable label and release note of a deployment version."
},
"UpdateWorkflowVersionResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowVersionMetadata"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Update workflow version response",
"description": "The deployment version metadata after the update.",
"examples": [
{
"data": {
"version": 3,
"name": "Escalation routing",
"description": "Adds the priority escalation branch."
}
}
]
},
"UpdateWorkflowVersionRequest": {
"type": "object",
"properties": {
"name": {
"description": "New label for the deployment version.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"description": "New release note for the deployment version, or null to clear it.",
"anyOf": [
{
"type": "string",
"maxLength": 50000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"title": "Update workflow version request",
"description": "Merge-patch body for the mutable metadata of a deployment version.",
"examples": [
{
"name": "Escalation routing",
"description": "Adds the priority escalation branch."
}
]
},
"ActiveDeploymentSummary": {
"type": "object",
"properties": {
"deploymentVersionId": {
"type": "string",
"description": "Identifier of the active deployment version."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Numeric active deployment version."
},
"deployedAt": {
"type": "string",
"description": "ISO 8601 timestamp when this version became active.",
"format": "date-time"
}
},
"required": ["deploymentVersionId", "version", "deployedAt"],
"additionalProperties": false,
"title": "Active deployment",
"description": "Summary of the workflow version currently serving API executions."
},
"DeploymentOperationSummary": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique deployment operation identifier."
},
"deploymentVersionId": {
"type": "string",
"description": "Deployment version targeted by this operation."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Numeric deployment version."
},
"action": {
"type": "string",
"enum": ["deploy", "activate"],
"description": "Operation being performed on the deployment version."
},
"status": {
"type": "string",
"enum": ["preparing", "activating", "active", "failed", "superseded"],
"description": "Current deployment lifecycle status."
},
"isCurrent": {
"default": true,
"description": "Whether this operation still describes the current deployment attempt.",
"type": "boolean"
},
"readiness": {
"$ref": "#/components/schemas/DeploymentReadiness"
},
"requestedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the deployment operation was requested.",
"format": "date-time"
},
"activatedAt": {
"description": "ISO 8601 activation timestamp, or null before activation completes.",
"format": "date-time",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"description": "Deployment failure details, or null when no failure occurred.",
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationError"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"deploymentVersionId",
"version",
"action",
"status",
"isCurrent",
"readiness",
"requestedAt"
],
"additionalProperties": false,
"title": "Deployment operation",
"description": "Lifecycle state of a deployment or version-activation attempt."
},
"DeploymentReadiness": {
"type": "object",
"properties": {
"webhooks": {
"type": "string",
"enum": ["pending", "ready", "not_applicable"],
"description": "Webhook synchronization readiness."
},
"schedules": {
"type": "string",
"enum": ["pending", "ready", "not_applicable"],
"description": "Schedule synchronization readiness."
},
"mcp": {
"type": "string",
"enum": ["pending", "ready", "not_applicable"],
"description": "MCP synchronization readiness."
}
},
"required": ["webhooks", "schedules", "mcp"],
"additionalProperties": false,
"title": "Deployment readiness",
"description": "Readiness of the side effects required to activate a deployment."
},
"DeploymentOperationError": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable deployment failure code."
},
"message": {
"type": "string",
"description": "Human-readable deployment failure message."
},
"retryable": {
"type": "boolean",
"description": "Whether retrying the deployment may succeed."
}
},
"required": ["code", "message", "retryable"],
"additionalProperties": false,
"title": "Deployment operation error",
"description": "Failure details for a deployment lifecycle operation."
},
"VersionActivationResult": {
"title": "Version activation result",
"description": "Activation attempt accepted for processing. Activation is asynchronous; inspect `isDeployed` and `latestDeploymentAttempt` for current state.",
"$ref": "#/components/schemas/RollbackResult"
},
"RollbackResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"isDeployed": {
"type": "boolean",
"description": "Whether a workflow version is currently live and available for API execution."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.",
"format": "date-time",
"examples": ["2026-06-12T10:30:00.000Z"]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal synchronization warnings. Empty when there is nothing to report."
},
"activeDeployment": {
"anyOf": [
{
"$ref": "#/components/schemas/ActiveDeploymentSummary"
},
{
"type": "null"
}
],
"description": "Currently live deployment version, or null while no version is active."
},
"latestDeploymentAttempt": {
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationSummary"
},
{
"type": "null"
}
],
"description": "Most recent deployment lifecycle attempt, or null when none is available."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Deployment version selected for re-activation."
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt",
"version"
],
"additionalProperties": false,
"title": "Rollback result",
"description": "Rollback attempt accepted for processing. Activation is asynchronous; inspect `isDeployed` and `latestDeploymentAttempt` for current state."
},
"ActivateWorkflowVersionResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"isDeployed": {
"type": "boolean",
"description": "Whether a workflow version is currently live and available for API execution."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.",
"format": "date-time",
"examples": ["2026-06-12T10:30:00.000Z"]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal synchronization warnings. Empty when there is nothing to report."
},
"activeDeployment": {
"anyOf": [
{
"$ref": "#/components/schemas/ActiveDeploymentSummary"
},
{
"type": "null"
}
],
"description": "Currently live deployment version, or null while no version is active."
},
"latestDeploymentAttempt": {
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationSummary"
},
{
"type": "null"
}
],
"description": "Most recent deployment lifecycle attempt, or null when none is available."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Deployment version selected for re-activation."
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt",
"version"
],
"additionalProperties": false,
"description": "Response data.",
"$ref": "#/components/schemas/VersionActivationResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Activate workflow version response",
"description": "Current deployment state after accepting the activation attempt.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": false,
"deployedAt": null,
"warnings": [],
"activeDeployment": null,
"latestDeploymentAttempt": {
"id": "depop_01J8ZK4RX5N7Y3S0U8D6E1W2",
"deploymentVersionId": "depver_01J8ZK4RX5N7Y3S0U8D6E1W3",
"version": 3,
"action": "activate",
"status": "activating",
"isCurrent": true,
"readiness": {
"webhooks": "ready",
"schedules": "ready",
"mcp": "not_applicable"
},
"requestedAt": "2026-06-12T10:30:00.000Z",
"activatedAt": null,
"error": null
},
"version": 3
}
}
]
},
"ActivateWorkflowVersionRequest": {
"default": {},
"title": "Activate workflow version request",
"description": "No body. The version to promote is named by the request path.",
"examples": [{}],
"type": "object",
"properties": {},
"additionalProperties": false
},
"RevertWorkflowVersionResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier."
},
"version": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "string",
"const": "active"
}
],
"description": "Deployment version loaded into the draft, or `active` for the live version."
},
"lastSaved": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Epoch milliseconds at which the overwritten draft was saved."
}
},
"required": ["id", "version", "lastSaved"],
"additionalProperties": false,
"title": "Revert workflow version result",
"description": "The draft after it was overwritten by a deployment version."
},
"RevertWorkflowVersionResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/RevertWorkflowVersionResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Revert workflow version response",
"description": "The draft after it was overwritten by the deployment version.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"version": 3,
"lastSaved": 1765535400000
}
}
]
},
"RevertWorkflowVersionRequest": {
"default": {},
"title": "Revert workflow version request",
"description": "No body. The version to load into the draft is named by the request path.",
"examples": [{}],
"type": "object",
"properties": {},
"additionalProperties": false
},
"WorkflowDeployment": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"isDeployed": {
"type": "boolean",
"description": "Whether a workflow version is currently live and available for API execution."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.",
"format": "date-time",
"examples": ["2026-06-12T10:30:00.000Z"]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal synchronization warnings. Empty when there is nothing to report."
},
"activeDeployment": {
"anyOf": [
{
"$ref": "#/components/schemas/ActiveDeploymentSummary"
},
{
"type": "null"
}
],
"description": "Currently live deployment version, or null while no version is active."
},
"latestDeploymentAttempt": {
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationSummary"
},
{
"type": "null"
}
],
"description": "Most recent deployment lifecycle attempt, or null when none is available."
},
"needsRedeployment": {
"type": "boolean",
"description": "Whether the editable draft has diverged from the live deployment version. False while a deployment attempt is still preparing or activating, and false when nothing is deployed."
},
"isPublicApi": {
"type": "boolean",
"description": "Whether the deployed workflow accepts unauthenticated public API execution. While true, anyone holding the execution URL can run the workflow — and be billed for it — without an API key, so this is the field an audit of what a deployment exposes reads. Changed with `PATCH /workflows/{workflowId}/deployment`."
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt",
"needsRedeployment",
"isPublicApi"
],
"additionalProperties": false,
"title": "Workflow deployment",
"description": "Current deployment state of a workflow, including draft-versus-live drift and the most recent deployment attempt."
},
"WorkflowDeploymentResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowDeployment"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Workflow deployment response",
"description": "Current deployment state, including draft-versus-live drift and whether the deployment is publicly executable.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": true,
"needsRedeployment": true,
"isPublicApi": false,
"deployedAt": "2026-06-12T10:30:00.000Z",
"warnings": [],
"activeDeployment": {
"deploymentVersionId": "depver_01J8ZK3QW4M6X2R9T7B5C0V2",
"version": 3,
"deployedAt": "2026-06-12T10:30:00.000Z"
},
"latestDeploymentAttempt": {
"id": "depop_01J8ZK3QW4M6X2R9T7B5C0V1",
"deploymentVersionId": "depver_01J8ZK3QW4M6X2R9T7B5C0V2",
"version": 3,
"action": "deploy",
"status": "active",
"isCurrent": true,
"readiness": {
"webhooks": "ready",
"schedules": "ready",
"mcp": "not_applicable"
},
"requestedAt": "2026-06-12T10:29:58.000Z",
"activatedAt": "2026-06-12T10:30:00.000Z",
"error": null
}
}
}
]
},
"WorkflowPublicApiSettings": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier."
},
"isPublicApi": {
"type": "boolean",
"description": "Whether the deployed workflow accepts unauthenticated public API execution."
}
},
"required": ["id", "isPublicApi"],
"additionalProperties": false,
"title": "Workflow public API settings",
"description": "Whether a deployed workflow is executable without an API key."
},
"UpdateWorkflowPublicApiResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowPublicApiSettings"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Update workflow public API response",
"description": "Public API access after the update.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isPublicApi": true
}
}
]
},
"UpdateWorkflowPublicApiRequest": {
"type": "object",
"properties": {
"isPublicApi": {
"type": "boolean",
"description": "Whether the deployed workflow should accept unauthenticated public API execution."
}
},
"required": ["isPublicApi"],
"additionalProperties": false,
"title": "Update workflow public API request",
"description": "Enable or disable unauthenticated public execution of the deployed workflow.",
"examples": [
{
"isPublicApi": true
}
]
},
"DeployResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"isDeployed": {
"type": "boolean",
"description": "Whether a workflow version is currently live and available for API execution."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.",
"format": "date-time",
"examples": ["2026-06-12T10:30:00.000Z"]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal synchronization warnings. Empty when there is nothing to report."
},
"activeDeployment": {
"anyOf": [
{
"$ref": "#/components/schemas/ActiveDeploymentSummary"
},
{
"type": "null"
}
],
"description": "Currently live deployment version, or null while no version is active."
},
"latestDeploymentAttempt": {
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationSummary"
},
{
"type": "null"
}
],
"description": "Most recent deployment lifecycle attempt, or null when none is available."
},
"version": {
"description": "Deployment version created for this attempt, when available.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt"
],
"additionalProperties": false,
"title": "Deploy result",
"description": "Deployment attempt accepted for processing. Activation is asynchronous, and `latestDeploymentAttempt` is the attempt handle — returned by every deployment mutation as well as this read. Poll activation with `isDeployed` and `deployedAt` on the workflow, or `isActive` on `GET /workflows/{workflowId}/versions`."
},
"DeployWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/DeployResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Deploy workflow response",
"description": "Current deployment state after accepting the attempt.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": false,
"deployedAt": null,
"warnings": [],
"activeDeployment": null,
"latestDeploymentAttempt": {
"id": "depop_01J8ZK3QW4M6X2R9T7B5C0V1",
"deploymentVersionId": "depver_01J8ZK3QW4M6X2R9T7B5C0V2",
"version": 3,
"action": "deploy",
"status": "preparing",
"isCurrent": true,
"readiness": {
"webhooks": "pending",
"schedules": "ready",
"mcp": "not_applicable"
},
"requestedAt": "2026-06-12T10:30:00.000Z",
"activatedAt": null,
"error": null
},
"version": 3
}
}
]
},
"DeployWorkflowRequest": {
"default": {},
"title": "Deploy workflow request",
"description": "Optional metadata for the new deployment version.",
"examples": [
{
"name": "Escalation routing",
"description": "Adds the priority escalation branch."
}
],
"type": "object",
"properties": {
"name": {
"description": "Optional label for the deployment version.",
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"description": "Optional release note for the deployment version.",
"anyOf": [
{
"type": "string",
"maxLength": 50000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"UndeployResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"isDeployed": {
"type": "boolean",
"description": "Whether a workflow version is currently live and available for API execution."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.",
"format": "date-time",
"examples": ["2026-06-12T10:30:00.000Z"]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal synchronization warnings. Empty when there is nothing to report."
},
"activeDeployment": {
"anyOf": [
{
"$ref": "#/components/schemas/ActiveDeploymentSummary"
},
{
"type": "null"
}
],
"description": "Currently live deployment version, or null while no version is active."
},
"latestDeploymentAttempt": {
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationSummary"
},
{
"type": "null"
}
],
"description": "Most recent deployment lifecycle attempt, or null when none is available."
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt"
],
"additionalProperties": false,
"title": "Undeploy result",
"description": "Deployment state after a successful undeploy. `isDeployed` is false and no workflow version is active."
},
"UndeployWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/UndeployResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Undeploy workflow response",
"description": "Deployment state after deactivating the active version.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": false,
"deployedAt": null,
"warnings": [],
"activeDeployment": null,
"latestDeploymentAttempt": null
}
}
]
},
"RollbackWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/RollbackResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Rollback workflow response",
"description": "Current deployment state after accepting the rollback attempt.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": false,
"deployedAt": null,
"warnings": [],
"activeDeployment": null,
"latestDeploymentAttempt": {
"id": "depop_01J8ZK4RX5N7Y3S0U8D6E1W2",
"deploymentVersionId": "depver_01J8ZK4RX5N7Y3S0U8D6E1W3",
"version": 2,
"action": "activate",
"status": "activating",
"isCurrent": true,
"readiness": {
"webhooks": "ready",
"schedules": "ready",
"mcp": "not_applicable"
},
"requestedAt": "2026-06-12T10:30:00.000Z",
"activatedAt": null,
"error": null
},
"version": 2
}
}
]
},
"RollbackWorkflowRequest": {
"default": {},
"title": "Rollback workflow request",
"description": "Optional deployment version to reactivate.",
"examples": [
{
"version": 2
}
],
"type": "object",
"properties": {
"version": {
"description": "Deployment version to reactivate. Omit to select the previous active version.",
"type": "integer",
"minimum": 1,
"maximum": 2147483647
}
},
"additionalProperties": false
},
"WorkflowExportPayload": {
"type": "object",
"properties": {
"version": {
"type": "string",
"const": "1.0",
"description": "Workflow export format version."
},
"exportedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the export was created.",
"format": "date-time"
},
"workflow": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the source workflow."
},
"name": {
"type": "string",
"description": "Name of the exported workflow."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description of the exported workflow, or null when unset."
},
"workspaceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identifier of the source workspace, or null for legacy exports."
},
"folderPath": {
"type": "string",
"title": "Folder path",
"description": "Canonical containing-folder path; `/` is the workspace root.",
"maxLength": 4096
}
},
"required": ["id", "name", "description", "workspaceId", "folderPath"],
"additionalProperties": false,
"description": "Source workflow metadata."
},
"state": {
"type": "object",
"additionalProperties": true,
"description": "Secret-sanitized workflow graph, edges, loops, parallels, metadata, and variables."
}
},
"required": ["version", "exportedAt", "workflow", "state"],
"additionalProperties": false,
"title": "Workflow export payload",
"description": "Portable, secret-sanitized workflow export. Workspace-scoped bindings must be selected again after import."
},
"ExportWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowExportPayload"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Export workflow response",
"description": "Portable, secret-sanitized workflow data.",
"examples": [
{
"data": {
"version": "1.0",
"exportedAt": "2026-08-09T18:04:11.000Z",
"workflow": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"folderPath": "/Operations"
},
"state": {
"blocks": {},
"edges": []
}
}
}
]
},
"ImportedWorkflow": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the imported workflow."
},
"name": {
"type": "string",
"description": "Imported workflow name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Imported workflow description."
},
"workspaceId": {
"type": "string",
"description": "Workspace that owns the imported workflow."
},
"folderPath": {
"type": "string",
"title": "Folder path",
"description": "Canonical containing-folder path.",
"maxLength": 4096
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was imported.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was last updated.",
"format": "date-time"
}
},
"required": [
"id",
"name",
"description",
"workspaceId",
"folderPath",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"title": "Imported workflow",
"description": "Workflow created by an import operation."
},
"ImportWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/ImportedWorkflow"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Import workflow response",
"description": "The workflow created by the import.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"folderPath": "/Operations",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
}
]
},
"ImportWorkflowRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace in which to import the workflow."
},
"workflow": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"description": "JSON string containing a workflow export object or bare workflow state."
},
{
"type": "object",
"additionalProperties": true,
"description": "Workflow export object or bare workflow state."
}
],
"description": "Workflow export object, bare workflow state, or JSON string containing either form."
},
"folderPath": {
"description": "Destination folder path; omit for the workspace root.",
"$ref": "#/components/schemas/FolderPathInput"
},
"name": {
"description": "Override for the imported workflow name.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": {
"description": "Override for the imported workflow description.",
"type": "string",
"maxLength": 2000
}
},
"required": ["workspaceId", "workflow"],
"additionalProperties": false,
"title": "Import workflow request",
"description": "Portable workflow data and destination metadata for an import."
},
"ChatDeploymentListItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique chat deployment identifier."
},
"workflowId": {
"type": "string",
"description": "Workflow this deployment publishes."
},
"workspaceId": {
"type": "string",
"description": "Workspace the deployment belongs to, derived from its workflow."
},
"identifier": {
"type": "string",
"description": "URL slug the deployed chat answers on. Unique across live deployments."
},
"url": {
"type": "string",
"description": "Public URL of the deployed chat. There is no chat subdomain — the identifier is a path segment.",
"examples": ["https://sim.ai/chat/support"]
},
"title": {
"type": "string",
"description": "Title shown to visitors."
},
"description": {
"type": "string",
"description": "Description shown to visitors. Empty when unset."
},
"isActive": {
"type": "boolean",
"description": "Whether the deployment answers requests."
},
"authType": {
"type": "string",
"enum": ["public", "password", "email", "sso"],
"description": "How visitors are gated: `public` (no gate), `password`, `email`, or `sso`."
},
"outputConfigs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoredChatDeploymentOutputConfig"
},
"description": "Block outputs surfaced to visitors."
},
"includeThinking": {
"type": "boolean",
"description": "Whether visitors may receive provider thinking events. They must also opt into the streaming protocol."
},
"includeToolCalls": {
"type": "boolean",
"description": "Whether visitors may receive tool lifecycle events. They must also opt into the streaming protocol."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the deployment was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the deployment was last modified.",
"format": "date-time"
}
},
"required": [
"id",
"workflowId",
"workspaceId",
"identifier",
"url",
"title",
"description",
"isActive",
"authType",
"outputConfigs",
"includeThinking",
"includeToolCalls",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"title": "Chat deployment list entry",
"description": "A workflow published as a hosted chat, without the fields the detail read gates."
},
"StoredChatDeploymentOutputConfig": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"description": "Block whose output the chat streams."
},
"path": {
"type": "string",
"description": "Path within that block output. Empty means the whole output."
}
},
"required": ["blockId", "path"],
"additionalProperties": false,
"title": "Stored chat deployment output config",
"description": "One block output currently surfaced to chat visitors."
},
"ChatDeploymentListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatDeploymentListItem"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false,
"title": "Chat deployment list response",
"description": "A cursor-paginated page of chat deployments.",
"examples": [
{
"data": [
{
"id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
"identifier": "support",
"url": "https://sim.ai/chat/support",
"title": "Support chat",
"description": "Ask about billing, onboarding, or outages.",
"isActive": true,
"authType": "public",
"outputConfigs": [
{
"blockId": "block_01J8ZK3QW4M6X2R9T7B5C0V4",
"path": "content"
}
],
"includeThinking": false,
"includeToolCalls": false,
"createdAt": "2026-06-12T10:30:00.000Z",
"updatedAt": "2026-06-12T10:30:00.000Z"
}
],
"nextCursor": null
}
]
},
"StoredChatDeploymentCustomizations": {
"type": "object",
"properties": {
"primaryColor": {
"description": "CSS color used for the chat accent.",
"type": "string"
},
"welcomeMessage": {
"description": "First message shown to a visitor.",
"type": "string"
},
"imageUrl": {
"description": "Avatar image shown beside assistant messages.",
"type": "string"
}
},
"additionalProperties": false,
"title": "Stored chat deployment customizations",
"description": "Presentation overrides currently stored on the deployed chat."
},
"ChatDeployment": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique chat deployment identifier."
},
"workflowId": {
"type": "string",
"description": "Workflow this deployment publishes."
},
"workspaceId": {
"type": "string",
"description": "Workspace the deployment belongs to, derived from its workflow."
},
"identifier": {
"type": "string",
"description": "URL slug the deployed chat answers on. Unique across live deployments."
},
"url": {
"type": "string",
"description": "Public URL of the deployed chat. There is no chat subdomain — the identifier is a path segment.",
"examples": ["https://sim.ai/chat/support"]
},
"title": {
"type": "string",
"description": "Title shown to visitors."
},
"description": {
"type": "string",
"description": "Description shown to visitors. Empty when unset."
},
"isActive": {
"type": "boolean",
"description": "Whether the deployment answers requests."
},
"authType": {
"type": "string",
"enum": ["public", "password", "email", "sso"],
"description": "How visitors are gated: `public` (no gate), `password`, `email`, or `sso`."
},
"hasPassword": {
"type": "boolean",
"description": "Whether a password is stored. The password itself is never readable."
},
"allowedEmails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Email addresses or domains admitted under `email` and `sso` gating. Empty otherwise."
},
"customizations": {
"description": "Presentation overrides. Unset fields fall back to platform defaults.",
"$ref": "#/components/schemas/StoredChatDeploymentCustomizations"
},
"outputConfigs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoredChatDeploymentOutputConfig"
},
"description": "Block outputs surfaced to visitors."
},
"includeThinking": {
"type": "boolean",
"description": "Whether visitors may receive provider thinking events. They must also opt into the streaming protocol."
},
"includeToolCalls": {
"type": "boolean",
"description": "Whether visitors may receive tool lifecycle events. They must also opt into the streaming protocol."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the deployment was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the deployment was last modified.",
"format": "date-time"
}
},
"required": [
"id",
"workflowId",
"workspaceId",
"identifier",
"url",
"title",
"description",
"isActive",
"authType",
"hasPassword",
"allowedEmails",
"customizations",
"outputConfigs",
"includeThinking",
"includeToolCalls",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"title": "Chat deployment",
"description": "A workflow published as a hosted chat."
},
"GetWorkflowChatDeploymentResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/ChatDeployment"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Get workflow chat deployment response",
"description": "The workflow's chat deployment.",
"examples": [
{
"data": {
"id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
"identifier": "support",
"url": "https://sim.ai/chat/support",
"title": "Support chat",
"description": "Ask about billing, onboarding, or outages.",
"isActive": true,
"authType": "public",
"hasPassword": false,
"allowedEmails": [],
"customizations": {
"primaryColor": "#6F3DFA",
"welcomeMessage": "Hi there! How can I help?"
},
"outputConfigs": [
{
"blockId": "block_01J8ZK3QW4M6X2R9T7B5C0V4",
"path": "content"
}
],
"includeThinking": false,
"includeToolCalls": false,
"createdAt": "2026-06-12T10:30:00.000Z",
"updatedAt": "2026-06-12T10:30:00.000Z"
}
}
]
},
"ReplaceWorkflowChatDeploymentResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/ChatDeployment"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Replace workflow chat deployment response",
"description": "The chat deployment as stored after the replace.",
"examples": [
{
"data": {
"id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
"identifier": "support",
"url": "https://sim.ai/chat/support",
"title": "Support chat",
"description": "Ask about billing, onboarding, or outages.",
"isActive": true,
"authType": "public",
"hasPassword": false,
"allowedEmails": [],
"customizations": {
"primaryColor": "#6F3DFA",
"welcomeMessage": "Hi there! How can I help?"
},
"outputConfigs": [
{
"blockId": "block_01J8ZK3QW4M6X2R9T7B5C0V4",
"path": "content"
}
],
"includeThinking": false,
"includeToolCalls": false,
"createdAt": "2026-06-12T10:30:00.000Z",
"updatedAt": "2026-06-12T10:30:00.000Z"
}
}
]
},
"ChatDeploymentCustomizations": {
"type": "object",
"properties": {
"primaryColor": {
"description": "CSS color used for the chat accent.",
"type": "string",
"minLength": 1,
"maxLength": 64
},
"welcomeMessage": {
"description": "First message shown to a visitor.",
"type": "string",
"maxLength": 2000
},
"imageUrl": {
"description": "Avatar image shown beside assistant messages.",
"type": "string",
"maxLength": 2048
}
},
"additionalProperties": false,
"title": "Chat deployment customizations",
"description": "Presentation overrides for the deployed chat."
},
"ChatDeploymentOutputConfig": {
"type": "object",
"properties": {
"blockId": {
"type": "string",
"minLength": 1,
"description": "Block whose output the chat streams."
},
"path": {
"type": "string",
"minLength": 1,
"description": "Path within that block output."
}
},
"required": ["blockId", "path"],
"additionalProperties": false,
"title": "Chat deployment output config",
"description": "One block output surfaced to chat visitors."
},
"ReplaceChatDeploymentRequest": {
"type": "object",
"properties": {
"identifier": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[a-z0-9-]+$",
"description": "URL slug the deployed chat answers on. Must be free across live deployments."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Title shown to visitors."
},
"description": {
"description": "Description shown to visitors. Omitted clears it.",
"type": "string",
"maxLength": 2000
},
"customizations": {
"description": "Presentation overrides. Omitted fields take platform defaults.",
"$ref": "#/components/schemas/ChatDeploymentCustomizations"
},
"authType": {
"description": "How visitors are gated. `public` leaves the chat open to anyone holding the URL.",
"default": "public",
"type": "string",
"enum": ["public", "password", "email", "sso"]
},
"password": {
"description": "Write-only password. Required whenever `authType` is `password`, and rejected otherwise. Never readable back.",
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"allowedEmails": {
"description": "Email addresses or domains admitted under `email` and `sso` gating. At least one is required for those modes.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"outputConfigs": {
"description": "Block outputs to surface to visitors. Omitted surfaces none.",
"maxItems": 100,
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatDeploymentOutputConfig"
}
},
"includeThinking": {
"description": "Allow visitors to receive provider thinking events.",
"default": false,
"type": "boolean"
},
"includeToolCalls": {
"description": "Allow visitors to receive tool lifecycle events.",
"default": false,
"type": "boolean"
}
},
"required": ["identifier", "title"],
"additionalProperties": false,
"title": "Replace chat deployment request",
"description": "The complete desired state of a workflow's chat.",
"examples": [
{
"identifier": "support",
"title": "Support chat"
}
]
},
"DeleteChatDeploymentResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the removed chat deployment."
},
"deleted": {
"type": "boolean",
"const": true,
"description": "Whether the deployment was removed."
}
},
"required": ["id", "deleted"],
"additionalProperties": false,
"title": "Delete chat deployment result",
"description": "Chat deployment removal acknowledgement."
},
"DeleteWorkflowChatDeploymentResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/DeleteChatDeploymentResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Delete workflow chat deployment response",
"description": "Acknowledgement that the chat deployment was removed.",
"examples": [
{
"data": {
"id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
"deleted": true
}
}
]
},
"ExecutionError": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Human-readable workflow execution failure message."
},
"code": {
"type": "string",
"enum": [
"TIMEOUT",
"CANCELLED",
"USAGE_LIMIT_EXCEEDED",
"INVALID_INPUT",
"BLOCK_EXECUTION_FAILED",
"CHILD_WORKFLOW_FAILED",
"EXECUTION_FAILED"
],
"description": "Stable machine-readable execution failure code. `BLOCK_EXECUTION_FAILED` and `CHILD_WORKFLOW_FAILED` are reported only where block attribution is available; elsewhere a block-level failure is reported as `EXECUTION_FAILED`."
},
"blockId": {
"description": "Identifier of the failing block. Present on the synchronous execute response only; the polled run resource and the resume response cannot attribute a block.",
"type": "string"
},
"blockName": {
"description": "Display name of the failing block. Present on the synchronous execute response only.",
"type": "string"
},
"blockType": {
"description": "Integration or block type that failed. Present on the synchronous execute response only.",
"type": "string"
}
},
"required": ["message", "code"],
"additionalProperties": false,
"title": "Execution error",
"description": "Structured in-band failure details for a workflow run."
},
"WorkflowRunResult": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"workflowId": {
"type": "string",
"description": "Workflow that produced the run."
},
"status": {
"type": "string",
"enum": ["completed", "failed", "paused", "cancelled"],
"description": "Terminal or paused run status."
},
"output": {
"description": "Workflow output, including partial output on failure."
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ExecutionError"
},
{
"type": "null"
}
],
"description": "Structured execution failure, or null when none occurred."
},
"startedAt": {
"description": "ISO 8601 timestamp when execution started.",
"format": "date-time",
"type": "string"
},
"endedAt": {
"description": "ISO 8601 timestamp when execution ended.",
"format": "date-time",
"type": "string"
},
"durationMs": {
"description": "Execution duration in milliseconds.",
"type": "number",
"minimum": 0
}
},
"required": ["runId", "workflowId", "status", "output", "error"],
"additionalProperties": false,
"title": "Workflow run result",
"description": "Synchronous workflow run output and in-band execution status. Run failures are reported in band, not as HTTP errors — a run that exceeds its execution timeout returns HTTP 200 with `status: \"failed\"` and `error.code: \"TIMEOUT\"`, so branch on `status`."
},
"ExecuteWorkflowSyncResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowRunResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Synchronous workflow execution response",
"description": "Completed, failed, paused, or cancelled synchronous workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"status": "completed",
"output": {
"result": "Ticket routed to Support"
},
"error": null,
"startedAt": "2026-08-09T18:04:10.000Z",
"endedAt": "2026-08-09T18:04:11.000Z",
"durationMs": 1000
}
}
]
},
"QueuedWorkflowRun": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"statusUrl": {
"type": "string",
"format": "uri",
"description": "Absolute URL of the workflow run resource."
}
},
"required": ["runId", "statusUrl"],
"additionalProperties": false,
"title": "Queued workflow run",
"description": "Receipt returned when a workflow run is queued."
},
"ExecuteWorkflowQueuedResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/QueuedWorkflowRun"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Queued workflow execution response",
"description": "Receipt returned for an asynchronous workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
}
}
]
},
"ExecuteWorkflowRequest": {
"type": "object",
"properties": {
"input": {
"description": "Workflow input keyed by the selected trigger input-field name.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "Value supplied for one workflow input field."
}
},
"run": {
"description": "Workflow state and entry point to execute. Omit for the active deployment. Manual execution requires a personal API key with write access and supports synchronous or streamed runs only.",
"oneOf": [
{
"type": "object",
"properties": {
"source": {
"type": "string",
"const": "deployment",
"description": "Execute the active deployed workflow state."
}
},
"required": ["source"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"source": {
"type": "string",
"const": "manual",
"description": "Execute the current saved workflow state manually."
},
"entry": {
"description": "Manual entry mode. Omit to enter through the workflow trigger; a block entry requires an exact source run.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "trigger",
"description": "Enter the manual run through a runnable trigger."
},
"blockId": {
"description": "Runnable trigger block to enter through. Omit only when the saved workflow has exactly one runnable trigger.",
"type": "string",
"minLength": 1
},
"useMockPayload": {
"description": "Use the selected trigger's server-derived mock payload. Cannot be combined with `input`.",
"type": "boolean"
}
},
"required": ["type"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "block",
"description": "Resume manual execution at a block using persisted upstream state."
},
"blockId": {
"type": "string",
"minLength": 1,
"description": "Saved workflow block at which manual execution should resume."
},
"sourceRunId": {
"type": "string",
"minLength": 1,
"description": "Exact prior run whose persisted execution snapshot supplies upstream block state."
}
},
"required": ["type", "blockId", "sourceRunId"],
"additionalProperties": false
}
]
}
},
"required": ["source"],
"additionalProperties": false
}
]
},
"async": {
"default": false,
"description": "Queue the run and return a 202 receipt when true. Requires an API key, cannot be combined with `stream`, and rejects all streaming and output-shaping options (`selectedOutputs`, `includeThinking`, `includeToolCalls`, `includeFileBase64`, `base64MaxBytes`).",
"type": "boolean"
},
"executionTimeoutSeconds": {
"description": "Requested server-side timeout for an asynchronous run, in seconds. An upper bound, not the effective timeout: the run uses the smaller of this value and the plan's execution timeout, so requesting more than the plan allows silently yields the plan timeout. Rejected with `400` unless `async` is true.",
"type": "integer",
"minimum": 1,
"maximum": 604800
},
"stream": {
"default": false,
"description": "Return Server-Sent Events instead of JSON when true. Cannot be combined with `async`.",
"type": "boolean"
},
"selectedOutputs": {
"description": "Block output references to include in a streamed response. Rejected when `async` is true.",
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"includeThinking": {
"default": false,
"description": "Include model reasoning events in an agent-event stream. Requires `stream: true` and the `X-Sim-Stream-Protocol: agent-events-v1` request header, and is rejected when `async` is true.",
"type": "boolean"
},
"includeToolCalls": {
"default": false,
"description": "Include tool-call events in an agent-event stream. Requires `stream: true` and the `X-Sim-Stream-Protocol: agent-events-v1` request header, and is rejected when `async` is true.",
"type": "boolean"
},
"includeFileBase64": {
"description": "Inline eligible output files as base64 content. Rejected when `async` is true.",
"type": "boolean"
},
"base64MaxBytes": {
"description": "Maximum total bytes of file content to inline as base64, lowering but never raising the server limit of 16 MiB. Rejected when `async` is true.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 16777216
}
},
"additionalProperties": false,
"title": "Execute workflow request",
"description": "Input, workflow-state selection, and execution-mode options. Each option carries the modes it requires and the modes that reject it; a violated combination is a 400.",
"examples": [
{
"input": {
"ticketId": "ticket_123"
}
},
{
"input": {
"ticketId": "ticket_123"
},
"async": true
},
{
"input": {
"ticketId": "ticket_123"
},
"stream": true
},
{
"run": {
"source": "manual"
}
},
{
"run": {
"source": "manual",
"entry": {
"type": "block",
"blockId": "block_123",
"sourceRunId": "run_123"
}
}
}
]
},
"WorkflowRunListItem": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"workflowId": {
"type": "string",
"description": "Workflow that produced the run."
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"paused",
"redacting",
"completed",
"failed",
"cancelled"
],
"description": "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting to be resumed — either held at a human-in-the-loop pause point, or left paused by a resume attempt that did not complete. Only the single-run response distinguishes the two, through `paused.automaticResumeWaitingReason`."
},
"trigger": {
"type": "string",
"description": "Trigger type that started the run."
},
"startedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the run started.",
"format": "date-time"
},
"endedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp when the run ended, or null while active.",
"format": "date-time"
},
"durationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Run duration in milliseconds, or null while active."
},
"cost": {
"anyOf": [
{
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total credits consumed by the run."
}
},
"required": ["total"],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Credit cost, or null when unavailable."
}
},
"required": [
"runId",
"workflowId",
"status",
"trigger",
"startedAt",
"endedAt",
"durationMs",
"cost"
],
"additionalProperties": false,
"title": "Workflow run summary",
"description": "Summary of a recorded workflow run."
},
"WorkflowRunListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowRunListItem"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false,
"title": "Workflow run list response",
"description": "A cursor-paginated page of workflow run summaries.",
"examples": [
{
"data": [
{
"runId": "run_8f14e45f-ceea-467f-a",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"status": "completed",
"trigger": "api",
"startedAt": "2026-08-09T18:04:10.000Z",
"endedAt": "2026-08-09T18:04:11.000Z",
"durationMs": 1000,
"cost": {
"total": 12
}
}
],
"nextCursor": null
}
]
},
"V2RunFile": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier to address this file by on the download endpoint."
},
"name": {
"type": "string",
"description": "File name, including its extension."
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "File size in bytes."
},
"type": {
"type": "string",
"description": "MIME type recorded for the file."
},
"downloadPath": {
"type": "string",
"description": "Path to fetch this file's bytes from, relative to the API host."
},
"base64": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Base64-encoded contents when `includeFileBase64` was requested and the file fits the inline ceiling, otherwise null."
}
},
"required": ["id", "name", "size", "type", "downloadPath", "base64"],
"additionalProperties": false,
"title": "Workflow run file",
"description": "A file produced by a workflow run."
},
"WorkflowRunStatus": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"workflowId": {
"type": "string",
"description": "Workflow that produced the run."
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"paused",
"redacting",
"completed",
"failed",
"cancelled",
"queued"
],
"description": "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting to be resumed — either held at a human-in-the-loop pause point, or left paused by a resume attempt that did not complete. Only the single-run response distinguishes the two, through `paused.automaticResumeWaitingReason`."
},
"trigger": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Trigger type that started the run. Backfilled as `api` for a run that is still queued, so it is populated from the first poll."
},
"startedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 start timestamp. A queued run reports the time it was enqueued, so it is populated from the first poll.",
"format": "date-time"
},
"endedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 end timestamp, or null while nonterminal.",
"format": "date-time"
},
"durationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Run duration in milliseconds, or null while active."
},
"paused": {
"anyOf": [
{
"type": "object",
"properties": {
"contextId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Resume context identifier, or null while every pause point is mid-resume."
},
"pausedAt": {
"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))$",
"description": "ISO 8601 timestamp when the execution entered the paused state."
},
"resumeAt": {
"anyOf": [
{
"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))$"
},
{
"type": "null"
}
],
"description": "ISO 8601 scheduled automatic-resume timestamp, or null when no resume time is set."
},
"pauseKind": {
"anyOf": [
{
"type": "string",
"enum": ["time", "human"]
},
{
"type": "null"
}
],
"description": "Whether the pause waits for time or human input, or null when unspecified."
},
"blockedOnBlockId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Workflow block awaiting resume, or null when no block is identified."
},
"automaticResumeWaitingReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Why automatic resume is waiting, or null when it is not — on a paused run, null means it is waiting on human input. Recorded whenever a resume attempt fails and cleared once one succeeds. A non-retryable or exhausted failure is prefixed `Automatic resume requires manual intervention: `."
},
"pausePointCount": {
"type": "number",
"description": "Number of pause points tracked for the execution."
},
"resumedCount": {
"type": "number",
"description": "Number of pause points that have resumed."
}
},
"required": [
"contextId",
"pausedAt",
"resumeAt",
"pauseKind",
"blockedOnBlockId",
"automaticResumeWaitingReason",
"pausePointCount",
"resumedCount"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Current pause details, or null when the run is not paused."
},
"cost": {
"anyOf": [
{
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total credits consumed by the run."
}
},
"required": ["total"],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Credit cost, or null when unavailable."
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ExecutionError"
},
{
"type": "null"
}
],
"description": "Structured execution failure, or null when none occurred. Reclassified from the persisted error message, so `blockId`/`blockName`/`blockType` are absent and a block-level failure reports `EXECUTION_FAILED` here even when the same run reported `BLOCK_EXECUTION_FAILED` on its synchronous execute response."
},
"output": {
"anyOf": [
{
"description": "Final workflow output value."
},
{
"type": "null"
}
],
"description": "Final workflow output when requested, otherwise null."
},
"blockOutputs": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "Output value produced by one workflow block."
}
},
{
"type": "null"
}
],
"description": "Outputs of the blocks named by `selectedOutputs`, or null when none were requested. Gated by `selectedOutputs` alone — `includeOutput` governs `output` only."
},
"files": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/V2RunFile"
}
},
{
"type": "null"
}
],
"description": "Files this run produced, or null when `includeOutput` is false. Matches the nullability of `output`."
}
},
"required": [
"runId",
"workflowId",
"status",
"trigger",
"startedAt",
"endedAt",
"durationMs",
"paused",
"cost",
"error",
"output",
"blockOutputs",
"files"
],
"additionalProperties": false,
"title": "Workflow run status",
"description": "Detailed current state of a workflow run."
},
"WorkflowRunStatusResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowRunStatus"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Workflow run status response",
"description": "Detailed current state of a workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"status": "completed",
"trigger": "api",
"startedAt": "2026-08-09T18:04:10.000Z",
"endedAt": "2026-08-09T18:04:11.000Z",
"durationMs": 1000,
"paused": null,
"cost": {
"total": 12
},
"error": null,
"output": {
"result": "Ticket routed to Support"
},
"blockOutputs": null,
"files": [
{
"id": "file_1a2b3c",
"name": "summary.pdf",
"size": 20480,
"type": "application/pdf",
"downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a/files/file_1a2b3c",
"base64": null
}
]
}
}
]
},
"ResumeWorkflowSyncResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowRunResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Synchronous workflow resume response",
"description": "Completed, failed, paused, or cancelled resumed workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"status": "completed",
"output": {
"result": "Ticket routed to Support"
},
"error": null,
"startedAt": "2026-08-09T18:04:10.000Z",
"endedAt": "2026-08-09T18:04:11.000Z",
"durationMs": 1000
}
}
]
},
"QueuedWorkflowResume": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"statusUrl": {
"type": "string",
"format": "uri",
"description": "Absolute URL of the workflow run resource."
},
"queuePosition": {
"description": "Current queue position, when available.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["runId", "statusUrl"],
"additionalProperties": false,
"title": "Queued workflow resume",
"description": "Receipt returned when a resumed workflow attempt is queued."
},
"ResumeWorkflowQueuedResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/QueuedWorkflowResume"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Queued workflow resume response",
"description": "Receipt returned when a resumed workflow attempt is queued.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
}
}
]
},
"ResumeWorkflowRequest": {
"type": "object",
"properties": {
"contextId": {
"type": "string",
"minLength": 1,
"description": "Human-in-the-loop pause-context identifier."
},
"input": {
"description": "Input supplied to the paused workflow block."
}
},
"required": ["contextId"],
"additionalProperties": false,
"title": "Resume workflow request",
"description": "Pause context and optional input used to resume a workflow run.",
"examples": [
{
"contextId": "ctx_123",
"input": {
"approved": true
}
}
]
},
"CancelWorkflowRunResult": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether cancellation was accepted."
},
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"redisAvailable": {
"type": "boolean",
"description": "Whether the distributed cancellation channel was available."
},
"durablyRecorded": {
"type": "boolean",
"description": "Whether this request durably recorded a cancellation. Always false for a run that was already terminal, where the request is satisfied but nothing was written."
},
"locallyAborted": {
"type": "boolean",
"description": "Whether an in-process execution was aborted."
},
"pausedCancelled": {
"type": "boolean",
"description": "Whether a paused execution was cancelled."
},
"reason": {
"description": "Machine-readable cancellation outcome, present on every cancellation including full successes. `recorded` is the success value. `already_cancelled`, `already_completed`, and `already_failed` mean the run had already reached that terminal state, so nothing was cancelled and `durablyRecorded` is false. `redis_unavailable` and `redis_write_failed` mean the distributed cancellation signal was not written, so an already-running execution may not observe the cancellation. `paused_event_publish_failed` and `paused_database_cancel_failed` name the failing step for a paused run.",
"type": "string",
"enum": [
"recorded",
"already_cancelled",
"already_completed",
"already_failed",
"redis_unavailable",
"redis_write_failed",
"paused_event_publish_failed",
"paused_database_cancel_failed"
]
}
},
"required": [
"success",
"runId",
"redisAvailable",
"durablyRecorded",
"locallyAborted",
"pausedCancelled"
],
"additionalProperties": false,
"title": "Cancel workflow run result",
"description": "Outcome of a workflow run cancellation request. Cancellation is best-effort: a run already in a terminal state succeeds with no effect, reported as `durablyRecorded: false` with an `already_*` reason naming the state observed."
},
"CancelWorkflowRunResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/CancelWorkflowRunResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Cancel workflow run response",
"description": "Outcome of the cancellation request.",
"examples": [
{
"data": {
"success": true,
"runId": "run_8f14e45f-ceea-467f-a",
"redisAvailable": true,
"durablyRecorded": true,
"locallyAborted": true,
"pausedCancelled": false,
"reason": "recorded"
}
}
]
},
"WorkflowFolder": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Folder name."
},
"path": {
"type": "string",
"title": "Non-root folder path",
"description": "Canonical folder path used as the public folder identifier.",
"maxLength": 4096
},
"parentPath": {
"type": "string",
"title": "Folder path",
"description": "Canonical parent path; `/` is the root.",
"maxLength": 4096
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the folder was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the folder was last updated.",
"format": "date-time"
},
"locked": {
"type": "boolean",
"description": "Whether the folder is currently locked for mutation."
}
},
"required": ["name", "path", "parentPath", "createdAt", "updatedAt", "locked"],
"additionalProperties": false,
"title": "Workflow folder",
"description": "A canonical workflow folder and its mutation lock state."
},
"WorkflowFolderListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowFolder"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
}
},
"required": ["data", "nextCursor"],
"additionalProperties": false,
"title": "Workflow folder list response",
"description": "A list of canonical workflow folders.",
"examples": [
{
"data": [
{
"name": "Operations",
"path": "/Operations",
"parentPath": "/",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-05-01T09:00:00.000Z",
"locked": false
}
],
"nextCursor": null
}
]
},
"CreateWorkflowFolderResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowFolder"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Create workflow folder response",
"description": "The created workflow folder.",
"examples": [
{
"data": {
"name": "Operations",
"path": "/Operations",
"parentPath": "/",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-05-01T09:00:00.000Z",
"locked": false
}
}
]
},
"NonRootFolderPathInput": {
"title": "Non-root folder path input",
"description": "Non-root folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
"maxLength": 4096,
"type": "string"
},
"CreateWorkflowFolderRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace in which to create the folder."
},
"path": {
"description": "Path of the folder to create.",
"$ref": "#/components/schemas/NonRootFolderPathInput"
}
},
"required": ["workspaceId", "path"],
"additionalProperties": false,
"title": "Create workflow folder request",
"description": "Workspace and canonical path for a new workflow folder."
},
"RelocateWorkflowFolderResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowFolder"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Relocate workflow folder response",
"description": "The relocated workflow folder.",
"examples": [
{
"data": {
"name": "Support",
"path": "/Support",
"parentPath": "/",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-05-01T09:00:00.000Z",
"locked": false
}
}
]
},
"RelocateWorkflowFolderRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Workspace containing the folder."
},
"path": {
"description": "Current folder path.",
"$ref": "#/components/schemas/NonRootFolderPathInput"
},
"destinationPath": {
"description": "New full path for the folder and its descendants.",
"$ref": "#/components/schemas/NonRootFolderPathInput"
}
},
"required": ["workspaceId", "path", "destinationPath"],
"additionalProperties": false,
"title": "Relocate workflow folder request",
"description": "Current and destination paths for a workflow folder."
},
"DeleteWorkflowFolderResult": {
"type": "object",
"properties": {
"path": {
"type": "string",
"title": "Folder path",
"description": "Path of the deleted workflow folder.",
"maxLength": 4096
},
"deleted": {
"type": "boolean",
"const": true,
"description": "Confirms that the folder was deleted."
},
"deletedItems": {
"type": "object",
"properties": {
"folders": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of folders deleted."
},
"workflows": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of workflows deleted."
}
},
"required": ["folders", "workflows"],
"additionalProperties": false,
"description": "Resources removed by the deletion."
}
},
"required": ["path", "deleted", "deletedItems"],
"additionalProperties": false,
"title": "Delete workflow folder result",
"description": "Confirmation and deletion counts for a workflow folder."
},
"DeleteWorkflowFolderResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/DeleteWorkflowFolderResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Delete workflow folder response",
"description": "Confirmation and counts for the deleted folder.",
"examples": [
{
"data": {
"path": "/Operations",
"deleted": true,
"deletedItems": {
"folders": 1,
"workflows": 0
}
}
}
]
}
}
},
"x-generated-by": "scripts/generate-openapi.ts"
}
Reference in New Issue View Git Blame Copy Permalink