opensource/sim
3
0
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-10-31 20:53:15 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
b98ef9b70aa28c7cf2bcd5d5cb215dddbd17b7cf
sim/apps/docs/openapi-v2-workflows.json
T
Waleed 1fa40b8118 feat(v2): complete and align the v2 API surface (#6643) 
* fix(v2): close four validation holes in the logs and billing surfaces

Each of these answered a caller-supplied value with a 500 or a silently
wrong result instead of a 400.

- `GET /api/v2/logs` accepted any string as `startDate`/`endDate`. The
  route constructs a `Date` from it, so `?startDate=abc` reached the
  driver's timestamp mapper as an `Invalid Date` and 500'd. Both bounds
  now carry `.datetime()`, matching the sibling run list so one timestamp
  works on both collections. This narrows the accepted set: a date without
  a time and an offset-bearing timestamp are now rejected, and the field
  descriptions say "UTC ISO 8601" rather than overpromising "ISO 8601".

- `v2BillingStatusQuerySchema` was the only non-strict query schema in its
  family, so a mis-cased `workspaceID` was stripped and the caller got
  account-scope billing in place of the workspace scope it asked for — a
  wrong answer about money, served as a 200.

- An unresolvable `cursor` on `/api/v2/billing/logs` applied no cursor
  condition and restarted the sequence at page 1 while still reporting
  `hasMore`, so a pager holding a cursor across a deploy loops over the
  first page and counts the same credits on every lap. It is now a 400.
  The message does not reuse `INVALID_CURSOR_MESSAGE`, which names
  `sortBy`/`sortOrder` params this collection does not accept.

- The logs `status` field disagrees with the run resources for the same
  run: the run projection overlays `paused` from `paused_executions`,
  so an ordinary human-in-the-loop pause reads `paused` there and
  `pending` here. Reconciling would mean joining `paused_executions` in
  this read and silently moving live runs between two buckets of a
  shipped field, so the divergence is documented on the contract instead.

* feat(v2): expose the MCP tool plane and page the MCP server list

Registering an MCP server through v2 dead-ended: nothing on the public
surface ever ran tool discovery, so connectionStatus, toolCount, lastError,
and lastToolsRefresh stayed at their registration defaults and there was no
way to read a server's tools without opening the UI.

Adds GET /api/v2/mcp-servers/{id}/tools over a thin use case composed from
the existing mcp_servers.tools.discover operation, resolveServerContext, and
mcpService.discoverServerTools. It is personal-API-key-only — discovery
resolves the acting user's own OAuth credentials, which a workspace key
cannot supply — and the contract says so rather than letting callers meet an
unexplained 403. Discovery failures are classified instead of collapsing
into a 500: an unreachable or cooling-down server is a retryable 503, a
stale OAuth grant is a 401.

Also pages GET /api/v2/mcp-servers. It was the one unbounded list on the v2
surface, classified full-set on a bounded-by-construction rationale that
only holds for folder lists; nothing caps how many servers a workspace
registers.

* feat(v2/tables): strict row bodies, a filtered row count, and round-trippable required columns

Three tables gaps from the v2 capability evaluation.

Strictness. Every v2 tables request body is now `.strict()`. The row family
was the whole hole: `POST /query` sent v1's `filter` key answered 200 with a
fully unfiltered page, because Zod strips unknown keys unless told not to. The
same laxity covered the row create/update/delete/upsert/find bodies, the
run and cancel-runs bodies, the enrichment body, and — outside the row family
but the same class — the column delete, view create/update, and export bodies.
A contract sweep now walks every body-bearing tables contract and fails if one
of them stops rejecting an unrecognized key.

Filtered row count. `POST /api/v2/tables/{tableId}/query/count` answers the
question v1's `includeTotal`/`totalCount` answered and the `{data, nextCursor}`
envelope has nowhere to put: how many rows a predicate matches. It binds the
existing `queryTableRows` use case with `includeTotal: true, limit: 1` — no new
domain logic and the same `tables.rows.query` read policy. The use case types
`totalCount` as nullable because paged callers can decline it; this route always
asks for it, so a null is treated as a broken invariant rather than presented as
a fabricated zero.

Required columns. `required` is accepted on create-table, add-column, and
update-column, matching v1. v2 emitted the flag on every read while stripping it
from every write, so a column could not round-trip. Enforcement was already
complete: turning it on over rows with null, missing, or empty cells is rejected
by the domain.

* test(skills): pin the workspace-API-key split as structural, not accidental

A workspace API key can create a skill it can then never update or delete,
which no sibling resource does — so the asymmetry reads like an oversight
worth widening. It is not. Skill edits are authorized by the per-skill
editor row belonging to the acting user, which is why update/upsert/delete
declare a 'read' floor rather than 'write': workspace role is not the
authority. A workspace key carries no user subject, so allowing one replaces
a 403 with an unclassified PrincipalSubjectUserRequiredError that the v2
surface renders as a caller-reachable 500.

Records the reason on the registry and pins it, so the next reader finds the
argument instead of flipping the flag.

* feat(v2): read deployment state, and undo a file delete

Two v2 reads that existed only as a side effect of a mutation.

`GET /api/v2/workflows/{id}/deployment` publishes the state the deploy,
undeploy, and rollback responses carry, plus `needsRedeployment` — which
those responses structurally cannot carry, because they answer at the
moment the draft and the live version are equal. A caller that lost the
mutation response, or that polls from another process, had no way to ask.
Reuses `readWorkflowDeploymentStatus` behind `workflows.read`, the same
use case the internal status and deploy GETs already adapt.

`DELETE /api/v2/files/{fileId}` was a soft delete with no way to see what
it archived and no way to reverse it. `GET /api/v2/files?scope=archived`
pages the archived set and `deletedAt` on the file resource dates each
one; `POST /api/v2/files/{fileId}/restore` reverses the delete through
the existing `files.restore` operation. Restore is not a pure undo — it
returns the file to the root and renames it on a collision — so the use
case now reads the file back and both the response and the OpenAPI
description say what actually came back rather than what was deleted.

`scope=all` is rejected on the list for the reason the internal contract
already gives: it drops the `deleted_at` predicate and cannot use the
partial index. `scope=archived` combined with `folderPath` 404s when the
containing folder was archived too, which the contract documents.

* fix(v2): keep the unresolvable-cursor rejection a 400 on every surface

The cursor rejection lived in shared billing core but was an OrchestrationError
only, which the session-only GET /api/users/me/usage-logs cannot project: that
route is raw withRouteHandler and readTypedError matches instanceof HttpError,
so any signed-in caller typing ?cursor=x got a 500. UnknownUsageCursorError is
an HttpError carrying the OrchestrationError as its cause, so the v2 route still
renders BAD_REQUEST off the cause chain and the internal route answers 400.

Also closes the other half of the run-list parity: an inverted window on
GET /api/v2/logs is now a 400 instead of a silently empty page.

* fix(v2/tables): sweep union bodies per member and name the shapes on a rows 400

Review follow-ups on the strictness work.

The sweep was vacuous on the one union body it covers. Parsing
`{ notAContractField: true }` against `v2CreateTableRowsBodySchema` and looking
for `unrecognized_keys` anywhere in the issue tree is satisfied by either member
alone, so dropping `.strict()` from the single-row branch shipped green —
reproduced, 36/36 passing with the regression in place. The sweep now flattens a
union body into its members and asserts each one separately; removing `.strict()`
from either branch now fails a case that names it.

`POST /rows` answered an unknown key with `Invalid input`, the exact message the
v2 conventions name as failing the actionable-error rule, because a union
surfaces `invalid_union` first. The union now carries a message naming both
accepted shapes; the per-member failures still ride along in `details`.

Two TSDoc corrections. The `required` docstring claimed the domain rejects
turning the flag on over rows with empty cells — true of the update path, false
of add-column, which applies the flag as given (the same shape `unique` already
had here). And `.strict()` binds the top level only, so the view `config` object
and the shared sort-spec elements still strip unknown keys; both docstrings now
say so instead of implying full coverage.

* fix(v2): classify MCP discovery failures by type, not by substring

The tool-discovery error policy consumed categorizeError's status, whose
fallback is a substring match on the upstream message. Three consequences,
all caller-visible:

- A ZodError from the builder's own response `.parse` contains `invalid_type`,
  so a Sim-side response-schema defect answered 400 "Invalid request
  parameters" and suppressed the builder's 500 and its unhandled-error log.
- An upstream `Invalid params` or `not found` became the caller's 400/404 on a
  request the contract had already validated.
- A stale OAuth grant to the third-party server answered 401, the status this
  surface reserves for a missing or invalid Sim API key, so a client would
  rotate a credential that was never the problem.

The policy now dispatches on the MCP error families and returns null for
anything else. Reauthorization is a 409 carrying
`details.code: MCP_SERVER_REAUTHORIZATION_REQUIRED`; an unreachable, slow, or
cooling-down server is a 503 with a constant message.

Also: widen the shared server path-param description now that it covers tool
listing, map the list query explicitly so no undeclared `cursor` reaches the
use-case input, and document the endpoint's write side effects.

* merge: bring in the MCP tool plane workstream

* feat(v2): make knowledge tags usable and let documents be updated

v2 accepted tag slots on upload and filtered search by tag display name,
but no response ever returned a tag value and nothing listed the
vocabulary, so a shipped feature dead-ended in the public API. A document
that failed processing could only be deleted and re-uploaded, and
retiring 500 documents cost 500 requests.

- GET /api/v2/knowledge/{id}/tags returns the vocabulary (display name,
  slot, field type) as a full-set list.
- Document list and detail responses carry `tags`, keyed by display name
  exactly as search keys its result metadata. Writes stay slot-keyed; the
  tags endpoint is the mapping and the contract documents the split.
- PATCH /api/v2/knowledge/{id}/documents/{documentId} renames, enables,
  disables, retags, or requeues processing. Derived indexing state is not
  writable: asserting `processingStatus` on an unindexed document would
  corrupt search. A retry may not ride along with field updates.
- PATCH /api/v2/knowledge/{id}/documents bulk-enables or bulk-disables.
  Bulk delete is deliberately absent — that operation records no semantic
  audit, and a public bulk delete would empty a knowledge base leaving no
  DOCUMENT_DELETED entries.
- The document list accepts the same name-based `tagFilters` as search;
  the name-to-slot resolver moves out of search into a shared helper, and
  the filters are stamped into the offset cursor scope so a replayed
  cursor cannot cross a filter change.
- Search accepts `rerankerEnabled`, `rerankerModel`, `rerankerInputCount`
  and returns `rerankerScore`; `rerankerApiKey` and `skipUsageBilling`
  stay unexposed. Every result now names its `knowledgeBaseId`.

knowledge.tags.list flips from workspaceApiKey 'deny' to 'allow' (and
gains the workspace_api_key principal kind) so it matches the sibling
reads knowledge.documents.list / read / search. The vocabulary is
required input for two operations a workspace key can already perform.
Every tag write stays human-delegated.

* fix(v2): name every 403 cause, unfork boolean params, close nested strictness holes

Four cross-cutting consistency gaps on the v2 public surface.

**403s now carry a machine-readable cause.** The conventions skill mandated
`error.details.code` on 403 and nothing emitted one, so a client had to
string-match prose to tell "raise this member's role" from "this workspace
refuses personal keys" from "buy an enterprise plan" — four different
remedies behind one status, and every message reword a silent break. The
vocabulary is a closed set, `FORBIDDEN_DETAIL_CODES`, with a `Record` of
descriptions beside it that the generated OpenAPI 403 description is built
from, so a code cannot reach the wire unpublished. Refusals throw
`ForbiddenOperationError` in the domain and `v2CaughtOrchestrationError` —
the function every v2 error policy falls through to — attaches the code, so a
route cannot forget it. The audit-log resolver distinguished four causes and
collapsed them into one; it now names each.

Cross-tenant refusals deliberately get no code: they are concealed as 404 and
naming their cause would hand back the existence signal the concealment
withholds.

**Two boolean query params rejoin the majority.** `?includeDeparted` and
`?includeOutput` were `'true'`/`'false'` string enums inherited from the
internal shapes they reused, while four sibling params were real booleans.
Both move to `booleanQueryFlagSchema`, which still coerces both strings — a
strict widening, so an existing caller is unaffected, and the spec stops
telling callers to send a string.

**Two nested strictness holes close.** `.strict()` binds the top level only,
so `sort: [{ field, direction, nulls: 'last' }]` was answered 200 with the
null-ordering request dropped, and an unknown key inside a saved view's
`config` was accepted and discarded — the headline `filter` bug one level
down. `sortSpecSchema`'s element and both view-config schemas are now strict.
Safe on the read side because `normalizeStoredViewConfig` projects the
schemaless stored blob onto the declared keys first, so a legacy row cannot
turn into a 500.

The two sort dialects stay as they are. `/logs` and `/workflows/{id}/runs`
have one sortable column, so there is no `sortBy` to pair with; renaming
`order` breaks every caller and an alias is a second spelling of one thing
with undefined precedence. Both contracts and the skill now state the rule.

* style: format the files the workspace-scoped lint gate does not reach

`turbo run lint:check` runs `biome check .` per workspace, so `scripts/` at the
repo root is outside the graph and four changed files were unformatted — one of
them a merge artifact from reconciling the route baseline across branches.

* fix(v2): collapse the four knowledge document projections onto one null-tolerant summary

Extracts toV2DocumentSummary in app/api/v2/knowledge/utils.ts and composes the
list, upload-acknowledgement and detail presenters from it. toV2TaggedDocument
serialized uploadedAt with a bare .toISOString(), so a document with no upload
timestamp threw where every sibling returned null and the contract declares the
field nullable.

Also consolidates the two Zod strictness walkers onto one shared introspection
helper that unwraps wrappers and expands unions, closing the hole where a
union-shaped schema answered null and was skipped by the pagination sweep.

* fix(v2): stop HEAD driving MCP discovery, and unbreak the updatedAt keyset page

B1: Next aliases HEAD onto GET, which RFC 9110 permits only because GET is safe.
The MCP tool-discovery GET is not: it opens a live connection to the registered
endpoint and writes the outcome onto the server row. The v2 JSON builder gains a
headSafe option, default true, and the discovery route declares itself unsafe —
a HEAD is authenticated and rate-limited, then answered bodiless.

B2: a discovery status write stamped updatedAt, which this branch added as a
keyset sort, so any concurrent discovery duplicated and skipped servers across a
caller's pages. Discovery liveness already has lastConnected, lastToolsRefresh,
lastError and statusConfig.

B4: a public refresh now skips the positive cache but keeps the failure cooldown,
so it cannot be used to drive a connection attempt per request at a failing
endpoint. An explicit user action on their own server keeps the full bypass.

B6: the consecutive-failure counter is incremented SQL-side rather than read,
incremented and written back, and the success branch carries the same workspace,
liveness and staleness guard the failure branch already had.

* fix(v2): bound the bulk update echo, close the search leak, and make the docs true

B3: a selectAll bulk document update echoed every changed identifier, which the
request does not bound — a 100k-document knowledge base produced a multi-megabyte
array, materialized and then element-wise validated. The use case now reports
whether the selection was unbounded and the presenter omits the echo.

A1: the knowledge search presenter spread the whole use-case result, which also
carries userId, workspaceId, a cost breakdown and a live secret-trace registry.
Only Zod's default key-stripping kept them off the wire. Projected explicitly.

P1-a: GET /knowledge/{id}/tags advertised all 17 slots while the document PATCH
accepted only the seven text ones. The writer already coerces every slot type,
so the PATCH now takes all 17 in their declared types, with a 400 where a
malformed value used to silently clear the tag.

P1-b: both new PATCHes deny workspace API keys and now say so.
P1-c: the two table query reads declare maxBodyBytes and now document the 413.
P1-d: getWorkflowDeploymentV2 loses its legacy suffix.

C3: deletes two orchestration error mappers with no callers that mapped
'forbidden' with no details.
D2: a stored null in table_views.config survived the pick and failed the
response schema.

Also folds the six 'bounded set' paraphrases onto one FULL_SET_LIST constant,
shares the run-window date bound between the logs and runs lists so their
documented parity is enforced rather than asserted, adds the missing barrel
export for FORBIDDEN_DETAIL_CODE_DESCRIPTIONS, and strictens two response
schemas whose peers were already strict.

Migrates 40 v2 route tests onto the shared @sim/testing harness: 26 asserted a
rateLimitSubjectIds shape v2 auth never returns, 26 asserted the wrong
refillRate, 33 could not exercise their 401 path at all, and 6 hard-wired the
rollout gate to null.

* fix(mcp): bound the connect handshake, and stop the 403 description over-claiming

B5: the connect clamp was getMaxExecutionTimeout(), the workflow ceiling of
seven days, so the real bound became the server row's own timeout — which the
registration contract permits up to 300s — times the connect retries. A slow
server could hold a Node request for roughly twenty minutes. Connecting is not a
workflow run, so the handshake now shares the one-minute ceiling tools/list
already applies to itself.

C2: the generated 403 description asserted that error.details.code names the
cause on every 403. Nine domain refusals still throw a bare forbidden
OrchestrationError and reach the wire codeless, so the wording now says 'where
the cause is one a caller can act on'. Reparenting those throws is left as a
deliberate change: one of them is a cross-tenant refusal that belongs in the
codeless class and would change its status.

* chore: reconcile the route ratchet with staging

* style: sort imports and format the three files biome flagged

* fix(openapi): import the forbidden-code constants from their module, not the application barrel

The barrel also re-exports the authorized use-case layer, which loads
@sim/db at import time. That pulled a database connection into the
OpenAPI spec check, so check:audits failed wherever DATABASE_URL is
absent, including CI.
2026-08-12 15:04:24 -07:00

4936 lines
171 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 folder and deployment filters, search, sorting, and opaque cursor pagination. A workspace whose folder tree exceeds 10,000 folders is a 413, because the response needs the whole tree to render folder paths.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"description": "Workspace whose workflows should be listed.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Workspace whose workflows should be listed."
}
},
{
"name": "folderPath",
"in": "query",
"required": false,
"description": "Restrict results to workflows in this folder path.",
"schema": {
"description": "Restrict results to workflows in this folder path.",
"type": "string"
}
},
{
"name": "deployedOnly",
"in": "query",
"required": false,
"description": "Return only workflows with an active deployment when true.",
"schema": {
"description": "Return only workflows with an active deployment when true.",
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum workflows to return per page. 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 returned by the previous page.",
"schema": {
"description": "Opaque cursor returned by the previous page.",
"type": "string",
"minLength": 1
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Case-insensitive substring search on the resource name.",
"schema": {
"description": "Case-insensitive substring search on the resource name.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "sortBy",
"in": "query",
"required": false,
"description": "Field used to sort the result.",
"schema": {
"default": "position",
"description": "Field used to sort the result.",
"type": "string",
"enum": ["position", "name", "createdAt", "updatedAt", "runCount"]
}
},
{
"name": "sortOrder",
"in": "query",
"required": false,
"description": "Sort direction.",
"schema": {
"default": "asc",
"description": "Sort direction.",
"type": "string",
"enum": ["asc", "desc"]
}
}
],
"responses": {
"200": {
"description": "A page of workflows.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"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. A workspace whose folder tree exceeds 10,000 folders is a 413, because the response needs the whole tree to render folder paths.",
"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"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}": {
"get": {
"operationId": "getWorkflow",
"summary": "Get Workflow",
"description": "Get a workflow with its variables and deployed API-trigger inputs. A workspace whose folder tree exceeds 10,000 folders is a 413, because the response needs the whole tree to render folder paths.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"responses": {
"200": {
"description": "The requested workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowDetailResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"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 whose folder tree exceeds 10,000 folders is a 413, because the response needs the whole tree to render folder paths.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"requestBody": {
"required": true,
"description": "Fields to update on an existing workflow.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The updated workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteWorkflowV2",
"summary": "Delete Workflow",
"description": "Permanently delete a workflow and its associated mutable state.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"responses": {
"200": {
"description": "The workflow was deleted.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/versions": {
"get": {
"operationId": "listWorkflowVersionsV2",
"summary": "List Workflow Versions",
"description": "List immutable deployment versions of a workflow, newest first.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum deployment versions to return per page. 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 returned by the previous page.",
"schema": {
"description": "Opaque cursor returned by the previous page.",
"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/{id}/versions/{version}": {
"get": {
"operationId": "getWorkflowVersionV2",
"summary": "Get Workflow Version",
"description": "Get an immutable deployment version and its pinned workflow graph snapshot.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "version",
"in": "path",
"required": true,
"description": "Numeric deployment version.",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Numeric deployment version.",
"examples": [3]
}
}
],
"responses": {
"200": {
"description": "The requested deployment version.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowVersionDetailResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/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 place `needsRedeployment` is published — the deploy, undeploy, and rollback responses cannot carry it, because they answer at the moment the draft and the live version are equal.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"responses": {
"200": {
"description": "The 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"
}
}
}
},
"/api/v2/workflows/{id}/deploy": {
"post": {
"operationId": "deployWorkflow",
"summary": "Deploy Workflow",
"description": "Create and asynchronously activate a deployment version. This request is not idempotent: it accepts no idempotency key and every call mints a new deployment version, so retrying after a timeout creates a second version rather than returning the first. The response carries `latestDeploymentAttempt` for the accepted attempt, but `GET /workflows/{id}` does not expose that field — poll activation with `isDeployed` and `deployedAt` on the workflow, or with `isActive` on `GET /workflows/{id}/versions`. Returns 409 when the deployment would conflict with an existing webhook path. A workspace API key cannot call this operation. Because unauthorized resources are concealed, the rejection is reported as `404` rather than `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"requestBody": {
"required": false,
"description": "Optional metadata for the new deployment version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeployWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The accepted deployment attempt.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeployWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"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"
}
}
},
"delete": {
"operationId": "undeployWorkflow",
"summary": "Undeploy Workflow",
"description": "Deactivate the currently serving workflow version. A workspace API key cannot call this operation. Because unauthorized resources are concealed, the rejection is reported as `404` rather than `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"responses": {
"200": {
"description": "The workflow was undeployed.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UndeployWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/rollback": {
"post": {
"operationId": "rollbackWorkflow",
"summary": "Rollback Workflow",
"description": "Asynchronously reactivate a previous deployment version, selecting the preceding active version when no version is supplied. A workspace API key cannot call this operation. Because unauthorized resources are concealed, the rejection is reported as `404` rather than `403`; use a personal API key.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"requestBody": {
"required": false,
"description": "Optional deployment version to reactivate.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RollbackWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The accepted rollback attempt.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RollbackWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/export": {
"get": {
"operationId": "exportWorkflow",
"summary": "Export Workflow",
"description": "Export a portable, secret-sanitized workflow. Workspace-scoped bindings must be selected again after import. A workspace whose folder tree exceeds 10,000 folders is a 413, because the response needs the whole tree to render folder paths.",
"tags": ["Workflows"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
}
],
"responses": {
"200": {
"description": "The workflow export payload.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"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.",
"tags": ["Workflows"],
"requestBody": {
"required": true,
"description": "Portable workflow data and destination metadata for an import.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportWorkflowRequest"
}
}
}
},
"responses": {
"201": {
"description": "The imported workflow.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportWorkflowResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/execute": {
"post": {
"operationId": "executeWorkflowV2",
"summary": "Execute Workflow",
"description": "Execute a deployed workflow synchronously, asynchronously, or as Server-Sent Events. Public workflows permit anonymous synchronous and streaming execution; asynchronous execution requires an API key. 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`. The optional `X-Run-Id` header is a one-shot uniqueness claim, not an idempotency key: reusing a value returns 409 with `error.details.code: \"RUN_ID_CONFLICT\"` and never replays the earlier run. Option constraints — each is a 400: (1) `async: true` requires an API key; anonymous public-workflow callers may only execute synchronously or as a stream. (2) `async` and `stream` cannot both be true. (3) `executionTimeoutSeconds` is accepted only when `async: true`. (4) `async: true` rejects every streaming and output-shaping option — `selectedOutputs`, `includeThinking`, `includeToolCalls`, `includeFileBase64`, and `base64MaxBytes`. (5) `includeThinking` and `includeToolCalls` require `stream: true`. (6) `includeThinking` and `includeToolCalls` require the `X-Sim-Stream-Protocol: agent-events-v1` request header, which declares that the client understands agent-event frames.",
"tags": ["Workflows"],
"security": [
{
"apiKey": []
},
{}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "x-run-id",
"in": "header",
"required": false,
"description": "Caller-supplied run identifier, available only to API-key callers. This is a one-shot uniqueness claim, NOT an idempotency key: the first request to use a value starts a run, and any later request reusing it fails with 409 and `error.details.code: \"RUN_ID_CONFLICT\"` instead of replaying the original result. To retry safely, generate a fresh value per attempt and reconcile duplicates yourself, or omit the header and let the server allocate the run identifier.",
"schema": {
"description": "Caller-supplied run identifier, available only to API-key callers. This is a one-shot uniqueness claim, NOT an idempotency key: the first request to use a value starts a run, and any later request reusing it fails with 409 and `error.details.code: \"RUN_ID_CONFLICT\"` instead of replaying the original result. To retry safely, generate a fresh value per attempt and reconcile duplicates yourself, or omit the header and let the server allocate the run identifier.",
"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 describing the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically when one workflow calls another; supply it yourself only when relaying an existing chain. A chain already at the maximum depth is rejected with 409 and `error.details.code: \"CALL_CHAIN_DEPTH_EXCEEDED\"`, which is how runaway recursion between workflows is stopped.",
"schema": {
"description": "Comma-separated workflow identifiers describing the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically when one workflow calls another; supply it yourself only when relaying an existing chain. A chain already at the maximum depth is rejected with 409 and `error.details.code: \"CALL_CHAIN_DEPTH_EXCEEDED\"`, which is how runaway recursion between workflows is stopped.",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "Input and execution-mode options for a deployed workflow. Option constraints — each is a 400: (1) `async: true` requires an API key; anonymous public-workflow callers may only execute synchronously or as a stream. (2) `async` and `stream` cannot both be true. (3) `executionTimeoutSeconds` is accepted only when `async: true`. (4) `async: true` rejects every streaming and output-shaping option — `selectedOutputs`, `includeThinking`, `includeToolCalls`, `includeFileBase64`, and `base64MaxBytes`. (5) `includeThinking` and `includeToolCalls` require `stream: true`. (6) `includeThinking` and `includeToolCalls` require the `X-Sim-Stream-Protocol: agent-events-v1` request header, which declares that the client understands agent-event frames.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "A synchronous run result or Server-Sent Event stream.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteWorkflowSyncResponse"
}
},
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
"202": {
"description": "The asynchronous run was queued.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteWorkflowQueuedResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/UsageLimitExceeded"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/RunIdConflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"499": {
"$ref": "#/components/responses/ClientClosedRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/runs": {
"get": {
"operationId": "listWorkflowRunsV2",
"summary": "List Workflow Runs",
"description": "List recorded runs of a workflow with filtering and opaque cursor pagination. Ordering deviates from the v2 `sortBy` + `sortOrder` convention: runs are sortable only by start time, so direction is carried by the single `order` param.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Filter by run status.",
"schema": {
"description": "Filter by run status.",
"type": "string",
"enum": ["pending", "running", "completed", "failed", "cancelled", "paused"]
}
},
{
"name": "trigger",
"in": "query",
"required": false,
"description": "Filter by trigger type.",
"schema": {
"description": "Filter by trigger type.",
"type": "string",
"minLength": 1
}
},
{
"name": "startDate",
"in": "query",
"required": false,
"description": "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.",
"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."
}
},
{
"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.",
"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."
}
},
{
"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 returned by the previous page.",
"schema": {
"description": "Opaque cursor returned by the previous page.",
"type": "string",
"minLength": 1
}
},
{
"name": "order",
"in": "query",
"required": false,
"description": "Sort direction by run start time. This operation deviates from the v2 `sortBy` + `sortOrder` convention: runs are sortable only by start time, so the direction is carried by this single `order` param and `sortBy`/`sortOrder` are not accepted.",
"schema": {
"default": "desc",
"description": "Sort direction by run start time. This operation deviates from the v2 `sortBy` + `sortOrder` convention: runs are sortable only by start time, so the direction is carried by this single `order` param and `sortBy`/`sortOrder` are not accepted.",
"type": "string",
"enum": ["asc", "desc"]
}
}
],
"responses": {
"200": {
"description": "A page of workflow runs.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowRunListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/runs/{runId}": {
"get": {
"operationId": "getWorkflowRunV2",
"summary": "Get Workflow Run",
"description": "Get current workflow run state, optionally including final and block outputs.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "runId",
"in": "path",
"required": true,
"description": "Unique workflow run identifier.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
},
{
"name": "includeOutput",
"in": "query",
"required": false,
"description": "Include final and block outputs when true.",
"schema": {
"description": "Include final and block outputs when true.",
"type": "boolean"
}
},
{
"name": "selectedOutputs",
"in": "query",
"required": false,
"description": "Comma-separated block output references to include.",
"schema": {
"description": "Comma-separated block output references to include.",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The workflow run status.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowRunStatusResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/runs/{runId}/resume": {
"post": {
"operationId": "resumeWorkflowRunV2",
"summary": "Resume Workflow Run",
"description": "Resume one human-in-the-loop pause context. The resumed attempt receives a new run identifier and may complete synchronously or return a queue receipt.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "runId",
"in": "path",
"required": true,
"description": "Unique workflow run identifier.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
}
],
"requestBody": {
"required": true,
"description": "Pause context and optional input used to resume a workflow run.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResumeWorkflowRequest"
}
}
}
},
"responses": {
"200": {
"description": "The resumed workflow attempt completed synchronously.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResumeWorkflowSyncResponse"
}
}
}
},
"202": {
"description": "The resumed workflow attempt was queued.",
"headers": {
"X-Run-Id": {
"$ref": "#/components/headers/X-Run-Id"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResumeWorkflowQueuedResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/UsageLimitExceeded"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/api/v2/workflows/{id}/runs/{runId}/cancel": {
"post": {
"operationId": "cancelRunV2",
"summary": "Cancel Workflow Run",
"description": "Request cancellation of a running, queued, or paused workflow run. Cancelling a run that has already reached a terminal state succeeds with no effect rather than returning an error. The `reason` field is present on every response, including full successes — `recorded` is the success value; it is not a partial-failure marker. A run produced by a table workflow group is a 409 when its cell can no longer accept the cancellation, because the run and its cell must reach the cancelled state together.",
"tags": ["Workflow Runs"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Unique workflow identifier.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique workflow identifier."
}
},
{
"name": "runId",
"in": "path",
"required": true,
"description": "Unique workflow run identifier.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
}
}
],
"responses": {
"200": {
"description": "The cancellation outcome.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelWorkflowRunResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"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 with `nextCursor` always null; there is no second page to fetch.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"description": "Workspace whose folders should be listed.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Workspace whose folders should be listed."
}
},
{
"name": "parentPath",
"in": "query",
"required": false,
"description": "Restrict results to direct children of this parent path.",
"schema": {
"description": "Restrict results to direct children of this parent path.",
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Case-insensitive substring match against the folder name.",
"schema": {
"description": "Case-insensitive substring match against the folder name.",
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
{
"name": "sortBy",
"in": "query",
"required": false,
"description": "Field used to sort the result.",
"schema": {
"default": "name",
"description": "Field used to sort the result.",
"type": "string",
"enum": ["name", "createdAt", "updatedAt"]
}
},
{
"name": "sortOrder",
"in": "query",
"required": false,
"description": "Sort direction.",
"schema": {
"default": "asc",
"description": "Sort direction.",
"type": "string",
"enum": ["asc", "desc"]
}
}
],
"responses": {
"200": {
"description": "A list of workflow folders.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowFolderListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"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.",
"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"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"patch": {
"operationId": "relocateWorkflowsFolder",
"summary": "Rename or Move Workflow Folder",
"description": "Rename or move a workflow folder and its descendants to a canonical path.",
"tags": ["Workflows"],
"requestBody": {
"required": true,
"description": "Current and destination paths for a workflow folder.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelocateWorkflowFolderRequest"
}
}
}
},
"responses": {
"200": {
"description": "The relocated workflow folder.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelocateWorkflowFolderResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"413": {
"$ref": "#/components/responses/PayloadTooLarge"
},
"423": {
"$ref": "#/components/responses/Locked"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
},
"delete": {
"operationId": "deleteWorkflowsFolder",
"summary": "Delete Workflow Folder",
"description": "Delete a workflow folder, optionally including its descendants and workflows.",
"tags": ["Workflows"],
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"description": "Workspace containing the folder.",
"schema": {
"type": "string",
"minLength": 1,
"description": "Workspace containing the folder."
}
},
{
"name": "path",
"in": "query",
"required": true,
"description": "Path of the folder to delete.",
"schema": {
"description": "Path of the folder to delete.",
"type": "string"
}
},
{
"name": "recursive",
"in": "query",
"required": false,
"description": "Delete nested files and folders when true.",
"schema": {
"description": "Delete nested files and folders when true.",
"default": "false",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The workflow folder was deleted.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/X-RateLimit-Reset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteWorkflowFolderResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"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 from the Sim dashboard under Settings > API Keys. A workspace API key is not accepted everywhere: operations that act on behalf of a specific human — administrative reads, secret access, and irreversible or governance-affecting writes — always reject it, whatever role the key carries. Each such operation says so in its own description, and the rejection surfaces as `403` unless the operation conceals unauthorized resources, in which case it is reported as `404`. Use a personal API key for those."
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Maximum requests allowed in the current window.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"title": "Rate limit",
"description": "Maximum requests allowed in the current window."
}
},
"X-RateLimit-Remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"title": "Rate limit remaining",
"description": "Requests remaining in the current window."
}
},
"X-RateLimit-Reset": {
"description": "ISO 8601 timestamp when the current rate-limit window resets.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"title": "Rate limit reset",
"description": "ISO 8601 timestamp when the current rate-limit window resets."
}
},
"Retry-After": {
"description": "Seconds to wait before retrying. Sent on `429` (derived from the caller rate-limit window) and on `503` (a fixed transient-failure floor). 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` (derived from the caller rate-limit window) and on `503` (a fixed transient-failure floor). 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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"Unauthorized": {
"description": "The API key is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"UsageLimitExceeded": {
"description": "The workspace has exceeded its usage or billing limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"Forbidden": {
"description": "The caller lacks the rights this operation requires. Where the cause is one a caller can act on, `error.details.code` names it, drawn 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- `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- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address.\nA resource in a workspace the caller cannot reach at all answers `404`, not `403`, so absence and denial are indistinguishable to a caller who was never entitled to tell them apart.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"NotFound": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"Conflict": {
"description": "The request conflicts with current resource state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"RunIdConflict": {
"description": "The run cannot be started. Two causes share this status, distinguished by `error.details.code`: `RUN_ID_CONFLICT` when the supplied `X-Run-Id` is already associated with a different request, and `CALL_CHAIN_DEPTH_EXCEEDED` when the incoming `X-Sim-Via` chain has already 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"
}
}
}
},
"Gone": {
"description": "The requested generated resource has expired.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"PayloadTooLarge": {
"description": "The request, or a resource collection it must materialize, exceeds the allowed size. Besides an oversized request body, this covers a generated artifact that renders past the download ceiling and a workspace folder tree too large to load in full.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"UnsupportedMediaType": {
"description": "The request uses an unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"Locked": {
"description": "The resource is locked and cannot be modified.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"RateLimited": {
"description": "The caller exceeded the request rate limit.",
"headers": {
"Retry-After": {
"$ref": "#/components/headers/Retry-After"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"ClientClosedRequest": {
"description": "The client closed the connection before the response was produced.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"InternalError": {
"description": "An unexpected server error occurred.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2Error"
}
}
}
},
"ServiceUnavailable": {
"description": "A required service is temporarily unavailable. The condition is transient, so the response normally carries `Retry-After` with the number of seconds to wait; treat that value as a floor and add jitter before retrying. One case deliberately omits the header: when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, the run may already have started, so retrying could start and bill a second run. 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"
}
}
}
}
},
"schemas": {
"V2Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable error code."
},
"message": {
"type": "string",
"description": "Human-readable explanation of the error."
},
"details": {
"description": "Optional structured error details."
}
},
"required": ["code", "message"],
"additionalProperties": false,
"description": "Canonical error details."
}
},
"required": ["error"],
"additionalProperties": false,
"title": "v2 error response",
"description": "Canonical error envelope returned by the public v2 API.",
"examples": [
{
"error": {
"code": "BAD_REQUEST",
"message": "The request is invalid."
}
}
]
},
"WorkflowListItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"name": {
"type": "string",
"description": "Workflow name.",
"examples": ["Customer support triage"]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Workflow description, or null when none is set."
},
"folderPath": {
"type": "string",
"description": "Canonical containing-folder path; `/` is the workspace root.",
"examples": ["/Operations"]
},
"workspaceId": {
"type": "string",
"description": "Workspace that owns the workflow."
},
"isDeployed": {
"type": "boolean",
"description": "Whether the workflow has an active deployment."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 activation timestamp, or null when not deployed.",
"format": "date-time"
},
"runCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Total recorded workflow runs."
},
"lastRunAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp of the latest run, or null when never run.",
"format": "date-time"
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was last updated.",
"format": "date-time"
}
},
"required": [
"id",
"name",
"description",
"folderPath",
"workspaceId",
"isDeployed",
"deployedAt",
"runCount",
"lastRunAt",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"title": "Workflow summary",
"description": "Summary of a workflow and its deployment and run state."
},
"WorkflowListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowListItem"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor for the next page: send it back as `cursor` to continue, and stop when it is null. Most v2 lists page, so null means the last page was reached. A few are full-set lists that return their whole bounded result in one response and therefore always report null; those say so in the operation description. Either way, null means there is nothing further to fetch — never construct a cursor 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",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
],
"nextCursor": null
}
]
},
"CreateWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowListItem"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Create workflow response",
"description": "The created workflow summary.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
}
]
},
"CreateWorkflowRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"description": "Workspace in which to create the workflow."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Workflow name."
},
"description": {
"description": "Optional workflow description.",
"anyOf": [
{
"type": "string",
"maxLength": 50000
},
{
"type": "null"
}
]
},
"folderPath": {
"description": "Folder path. A missing leading slash is normalized before validation.",
"type": "string"
}
},
"required": ["workspaceId", "name"],
"additionalProperties": false,
"title": "Create workflow request",
"description": "Name, description, workspace, and optional folder for a new workflow."
},
"WorkflowInputField": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Input field name."
},
"type": {
"type": "string",
"description": "Input field type."
},
"description": {
"description": "Optional input field description.",
"type": "string"
}
},
"required": ["name", "type"],
"additionalProperties": false,
"title": "Workflow input field",
"description": "A deployed API trigger input exposed by a workflow."
},
"WorkflowDetail": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"name": {
"type": "string",
"description": "Workflow name.",
"examples": ["Customer support triage"]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Workflow description, or null when none is set."
},
"folderPath": {
"type": "string",
"description": "Canonical containing-folder path; `/` is the workspace root.",
"examples": ["/Operations"]
},
"workspaceId": {
"type": "string",
"description": "Workspace that owns the workflow."
},
"isDeployed": {
"type": "boolean",
"description": "Whether the workflow has an active deployment."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 activation timestamp, or null when not deployed.",
"format": "date-time"
},
"runCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Total recorded workflow runs."
},
"lastRunAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp of the latest run, or null when never run.",
"format": "date-time"
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was last updated.",
"format": "date-time"
},
"variables": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "Structured workflow variable value."
},
"description": "Workflow-scoped variables keyed by variable identifier."
},
"inputs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowInputField"
},
"description": "Input fields exposed by the workflow API trigger."
}
},
"required": [
"id",
"name",
"description",
"folderPath",
"workspaceId",
"isDeployed",
"deployedAt",
"runCount",
"lastRunAt",
"createdAt",
"updatedAt",
"variables",
"inputs"
],
"additionalProperties": false,
"title": "Workflow detail",
"description": "Full workflow summary with variables and API-trigger input fields."
},
"WorkflowDetailResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowDetail"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Workflow detail response",
"description": "Detailed workflow metadata, variables, and trigger inputs.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z",
"variables": {},
"inputs": []
}
}
]
},
"UpdateWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowListItem"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Update workflow response",
"description": "The updated workflow summary.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"folderPath": "/Operations",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"isDeployed": true,
"deployedAt": "2026-06-12T10:30:00.000Z",
"runCount": 42,
"lastRunAt": "2026-08-09T18:04:11.000Z",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
}
]
},
"UpdateWorkflowRequest": {
"type": "object",
"properties": {
"name": {
"description": "Replacement workflow name.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"description": "Replacement workflow description; null clears it.",
"anyOf": [
{
"type": "string",
"maxLength": 50000
},
{
"type": "null"
}
]
},
"folderPath": {
"description": "Destination folder path; `/` moves the workflow to the workspace root.",
"type": "string"
}
},
"additionalProperties": false,
"title": "Update workflow request",
"description": "Fields to update on an existing workflow."
},
"DeleteWorkflowResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the deleted workflow."
},
"deleted": {
"type": "boolean",
"const": true,
"description": "Confirms that the workflow was deleted."
}
},
"required": ["id", "deleted"],
"additionalProperties": false,
"title": "Delete workflow result",
"description": "Confirmation that a workflow was deleted."
},
"DeleteWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/DeleteWorkflowResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Delete workflow response",
"description": "Confirmation that the workflow was deleted.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"deleted": true
}
}
]
},
"WorkflowVersion": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique deployment-version identifier."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Monotonically increasing deployment version number."
},
"name": {
"description": "Optional deployment-version label.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"description": "Optional deployment-version release note.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"isActive": {
"type": "boolean",
"description": "Whether this version is currently serving executions."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when this version was created.",
"format": "date-time"
},
"deployedBy": {
"description": "Display name of the user who created the deployment, when available.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"latestOperationStatus": {
"description": "Latest lifecycle-operation status for this version.",
"anyOf": [
{
"type": "string",
"enum": ["preparing", "activating", "active", "failed", "superseded"]
},
{
"type": "null"
}
]
}
},
"required": ["id", "version", "isActive", "createdAt"],
"additionalProperties": false,
"title": "Workflow version",
"description": "A saved deployment version of a workflow."
},
"WorkflowVersionListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowVersion"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor for the next page: send it back as `cursor` to continue, and stop when it is null. Most v2 lists page, so null means the last page was reached. A few are full-set lists that return their whole bounded result in one response and therefore always report null; those say so in the operation description. Either way, null means there is nothing further to fetch — never construct a cursor 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. Credential-bearing values are redacted: `oauth-input`, `password: true`, and table sub-block values are null; sensitive nested tool parameters and every parameter without authoritative codec metadata are null.",
"$ref": "#/components/schemas/DeployedWorkflowState"
}
},
"required": ["id", "version", "name", "description", "isActive", "createdAt", "state"],
"additionalProperties": false,
"title": "Workflow version detail",
"description": "A deployment version together with the workflow state it pins."
},
"WorkflowVersionDetailResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowVersionDetail"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Workflow version detail response",
"description": "The deployment version and its pinned workflow graph.",
"examples": [
{
"data": {
"id": "version_3",
"version": 3,
"name": "Escalation routing",
"description": "Adds the priority escalation branch.",
"isActive": true,
"createdAt": "2026-06-12T10:30:00.000Z",
"state": {
"blocks": {},
"edges": []
}
}
}
]
},
"ActiveDeploymentSummary": {
"type": "object",
"properties": {
"deploymentVersionId": {
"type": "string",
"description": "Identifier of the active deployment version."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Numeric active deployment version."
},
"deployedAt": {
"type": "string",
"description": "ISO 8601 timestamp when this version became active.",
"format": "date-time"
}
},
"required": ["deploymentVersionId", "version", "deployedAt"],
"additionalProperties": false,
"title": "Active deployment",
"description": "Summary of the workflow version currently serving API executions."
},
"DeploymentOperationSummary": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique deployment operation identifier."
},
"deploymentVersionId": {
"type": "string",
"description": "Deployment version targeted by this operation."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Numeric deployment version."
},
"action": {
"type": "string",
"enum": ["deploy", "activate"],
"description": "Operation being performed on the deployment version."
},
"status": {
"type": "string",
"enum": ["preparing", "activating", "active", "failed", "superseded"],
"description": "Current deployment lifecycle status."
},
"isCurrent": {
"default": true,
"description": "Whether this operation still describes the current deployment attempt.",
"type": "boolean"
},
"readiness": {
"$ref": "#/components/schemas/DeploymentReadiness"
},
"requestedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the deployment operation was requested.",
"format": "date-time"
},
"activatedAt": {
"description": "ISO 8601 activation timestamp, or null before activation completes.",
"format": "date-time",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"description": "Deployment failure details, or null when no failure occurred.",
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationError"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"deploymentVersionId",
"version",
"action",
"status",
"isCurrent",
"readiness",
"requestedAt"
],
"additionalProperties": false,
"title": "Deployment operation",
"description": "Lifecycle state of a deployment or version-activation attempt."
},
"DeploymentReadiness": {
"type": "object",
"properties": {
"webhooks": {
"type": "string",
"enum": ["pending", "ready", "not_applicable"],
"description": "Webhook synchronization readiness."
},
"schedules": {
"type": "string",
"enum": ["pending", "ready", "not_applicable"],
"description": "Schedule synchronization readiness."
},
"mcp": {
"type": "string",
"enum": ["pending", "ready", "not_applicable"],
"description": "MCP synchronization readiness."
}
},
"required": ["webhooks", "schedules", "mcp"],
"additionalProperties": false,
"title": "Deployment readiness",
"description": "Readiness of the side effects required to activate a deployment."
},
"DeploymentOperationError": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable deployment failure code."
},
"message": {
"type": "string",
"description": "Human-readable deployment failure message."
},
"retryable": {
"type": "boolean",
"description": "Whether retrying the deployment may succeed."
}
},
"required": ["code", "message", "retryable"],
"additionalProperties": false,
"title": "Deployment operation error",
"description": "Failure details for a deployment lifecycle operation."
},
"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."
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt",
"needsRedeployment"
],
"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.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": true,
"needsRedeployment": true,
"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
}
}
}
]
},
"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; `latestDeploymentAttempt` on this response is the attempt handle. The request is NOT idempotent — every POST mints a new deployment version, so a retry after a timeout creates a second version rather than returning the first. `latestDeploymentAttempt` is returned only here: `GET /workflows/{id}` does not carry it, so poll activation with `isDeployed` and `deployedAt` on the workflow, or with `isActive` on `GET /workflows/{id}/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"
}
]
}
}
},
"UndeployResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"isDeployed": {
"type": "boolean",
"description": "Whether a workflow version is currently live and available for API execution."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.",
"format": "date-time",
"examples": ["2026-06-12T10:30:00.000Z"]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal synchronization warnings. Empty when there is nothing to report."
},
"activeDeployment": {
"anyOf": [
{
"$ref": "#/components/schemas/ActiveDeploymentSummary"
},
{
"type": "null"
}
],
"description": "Currently live deployment version, or null while no version is active."
},
"latestDeploymentAttempt": {
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationSummary"
},
{
"type": "null"
}
],
"description": "Most recent deployment lifecycle attempt, or null when none is available."
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt"
],
"additionalProperties": false,
"title": "Undeploy result",
"description": "Deployment state after a successful undeploy. `isDeployed` is false and no workflow version is active."
},
"UndeployWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/UndeployResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Undeploy workflow response",
"description": "Deployment state after deactivating the active version.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": false,
"deployedAt": null,
"warnings": [],
"activeDeployment": null,
"latestDeploymentAttempt": null
}
}
]
},
"RollbackResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier.",
"examples": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
},
"isDeployed": {
"type": "boolean",
"description": "Whether a workflow version is currently live and available for API execution."
},
"deployedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 timestamp associated with the deployment, or null when unavailable.",
"format": "date-time",
"examples": ["2026-06-12T10:30:00.000Z"]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal synchronization warnings. Empty when there is nothing to report."
},
"activeDeployment": {
"anyOf": [
{
"$ref": "#/components/schemas/ActiveDeploymentSummary"
},
{
"type": "null"
}
],
"description": "Currently live deployment version, or null while no version is active."
},
"latestDeploymentAttempt": {
"anyOf": [
{
"$ref": "#/components/schemas/DeploymentOperationSummary"
},
{
"type": "null"
}
],
"description": "Most recent deployment lifecycle attempt, or null when none is available."
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Deployment version selected for re-activation."
}
},
"required": [
"id",
"isDeployed",
"deployedAt",
"warnings",
"activeDeployment",
"latestDeploymentAttempt",
"version"
],
"additionalProperties": false,
"title": "Rollback result",
"description": "Rollback attempt accepted for processing. Activation is asynchronous; inspect `isDeployed` and `latestDeploymentAttempt` for current state."
},
"RollbackWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/RollbackResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Rollback workflow response",
"description": "Current deployment state after accepting the rollback attempt.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"isDeployed": 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
}
}
},
"WorkflowExportPayload": {
"type": "object",
"properties": {
"version": {
"type": "string",
"const": "1.0",
"description": "Workflow export format version."
},
"exportedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the export was created.",
"format": "date-time"
},
"workflow": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the source workflow."
},
"name": {
"type": "string",
"description": "Name of the exported workflow."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description of the exported workflow, or null when unset."
},
"workspaceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identifier of the source workspace, or null for legacy exports."
},
"folderPath": {
"type": "string",
"description": "Canonical containing-folder path; `/` is the workspace root."
}
},
"required": ["id", "name", "description", "workspaceId", "folderPath"],
"additionalProperties": false,
"description": "Source workflow metadata."
},
"state": {
"type": "object",
"additionalProperties": true,
"description": "Secret-sanitized workflow graph, edges, loops, parallels, metadata, and variables."
}
},
"required": ["version", "exportedAt", "workflow", "state"],
"additionalProperties": false,
"title": "Workflow export payload",
"description": "Portable, secret-sanitized workflow export. Workspace-scoped bindings must be selected again after import."
},
"ExportWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowExportPayload"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Export workflow response",
"description": "Portable, secret-sanitized workflow data.",
"examples": [
{
"data": {
"version": "1.0",
"exportedAt": "2026-08-09T18:04:11.000Z",
"workflow": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"folderPath": "/Operations"
},
"state": {
"blocks": {},
"edges": []
}
}
}
]
},
"ImportedWorkflow": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier of the imported workflow."
},
"name": {
"type": "string",
"description": "Imported workflow name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Imported workflow description."
},
"workspaceId": {
"type": "string",
"description": "Workspace that owns the imported workflow."
},
"folderPath": {
"type": "string",
"description": "Canonical containing-folder path."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was imported.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the workflow was last updated.",
"format": "date-time"
}
},
"required": [
"id",
"name",
"description",
"workspaceId",
"folderPath",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"title": "Imported workflow",
"description": "Workflow created by an import operation."
},
"ImportWorkflowResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/ImportedWorkflow"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Import workflow response",
"description": "The workflow created by the import.",
"examples": [
{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"name": "Customer support triage",
"description": "Routes incoming support requests to the right team.",
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
"folderPath": "/Operations",
"createdAt": "2026-05-01T09:00:00.000Z",
"updatedAt": "2026-08-09T18:04:11.000Z"
}
}
]
},
"ImportWorkflowRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"description": "Workspace in which to import the workflow."
},
"workflow": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"description": "JSON string containing a workflow export object or bare workflow state."
},
{
"type": "object",
"additionalProperties": true,
"description": "Workflow export object or bare workflow state."
}
],
"description": "Workflow export object, bare workflow state, or JSON string containing either form."
},
"folderPath": {
"description": "Destination folder path; omit for the workspace root.",
"type": "string"
},
"name": {
"description": "Override for the imported workflow name.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": {
"description": "Override for the imported workflow description.",
"type": "string",
"maxLength": 2000
}
},
"required": ["workspaceId", "workflow"],
"additionalProperties": false,
"title": "Import workflow request",
"description": "Portable workflow data and destination metadata for an import."
},
"ExecutionError": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Human-readable workflow execution failure message."
},
"code": {
"type": "string",
"enum": [
"TIMEOUT",
"CANCELLED",
"USAGE_LIMIT_EXCEEDED",
"INVALID_INPUT",
"BLOCK_EXECUTION_FAILED",
"CHILD_WORKFLOW_FAILED",
"OUTPUT_TOO_LARGE",
"EXECUTION_FAILED"
],
"description": "Stable machine-readable execution failure code."
},
"blockId": {
"description": "Identifier of the failing block, when attributable.",
"type": "string"
},
"blockName": {
"description": "Display name of the failing block.",
"type": "string"
},
"blockType": {
"description": "Integration or block type that failed.",
"type": "string"
}
},
"required": ["message", "code"],
"additionalProperties": false,
"title": "Execution error",
"description": "Structured in-band failure details for a workflow run."
},
"WorkflowRunResult": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"workflowId": {
"type": "string",
"description": "Workflow that produced the run."
},
"status": {
"type": "string",
"enum": ["completed", "failed", "paused", "cancelled"],
"description": "Terminal or paused run status."
},
"output": {
"description": "Workflow output, including partial output on failure."
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ExecutionError"
},
{
"type": "null"
}
],
"description": "Structured execution failure, or null when none occurred."
},
"startedAt": {
"description": "ISO 8601 timestamp when execution started.",
"format": "date-time",
"type": "string"
},
"endedAt": {
"description": "ISO 8601 timestamp when execution ended.",
"format": "date-time",
"type": "string"
},
"durationMs": {
"description": "Execution duration in milliseconds.",
"type": "number",
"minimum": 0
}
},
"required": ["runId", "workflowId", "status", "output", "error"],
"additionalProperties": false,
"title": "Workflow run result",
"description": "Synchronous workflow run output and in-band execution status. Run failures are reported in band, not as HTTP errors — a synchronous run that exceeds its execution timeout returns HTTP 200 with `status: \"failed\"` and `error.code: \"TIMEOUT\"`, so always branch on `status` rather than on the HTTP status alone."
},
"ExecuteWorkflowSyncResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowRunResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Synchronous workflow execution response",
"description": "Completed, failed, paused, or cancelled synchronous workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"status": "completed",
"output": {
"result": "Ticket routed to Support"
},
"error": null,
"startedAt": "2026-08-09T18:04:10.000Z",
"endedAt": "2026-08-09T18:04:11.000Z",
"durationMs": 1000
}
}
]
},
"QueuedWorkflowRun": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"statusUrl": {
"type": "string",
"format": "uri",
"description": "Absolute URL of the workflow run resource."
}
},
"required": ["runId", "statusUrl"],
"additionalProperties": false,
"title": "Queued workflow run",
"description": "Receipt returned when a workflow run is queued."
},
"ExecuteWorkflowQueuedResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/QueuedWorkflowRun"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Queued workflow execution response",
"description": "Receipt returned for an asynchronous workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
}
}
]
},
"ExecuteWorkflowRequest": {
"type": "object",
"properties": {
"input": {
"description": "Workflow input keyed by deployed trigger input-field name.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "Value supplied for one workflow input field."
}
},
"async": {
"default": false,
"description": "Queue the run and return a 202 receipt when true. 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. This is an upper bound on the request, not the effective timeout: the run uses the smaller of this value and the account plan's execution timeout, so requesting more than the plan allows silently yields the plan timeout with no warning. 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.",
"type": "boolean"
},
"base64MaxBytes": {
"description": "Maximum total bytes of file content to inline as base64.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 10485760
}
},
"additionalProperties": false,
"title": "Execute workflow request",
"description": "Input and execution-mode options for a deployed workflow. Option constraints — each is a 400: (1) `async: true` requires an API key; anonymous public-workflow callers may only execute synchronously or as a stream. (2) `async` and `stream` cannot both be true. (3) `executionTimeoutSeconds` is accepted only when `async: true`. (4) `async: true` rejects every streaming and output-shaping option — `selectedOutputs`, `includeThinking`, `includeToolCalls`, `includeFileBase64`, and `base64MaxBytes`. (5) `includeThinking` and `includeToolCalls` require `stream: true`. (6) `includeThinking` and `includeToolCalls` require the `X-Sim-Stream-Protocol: agent-events-v1` request header, which declares that the client understands agent-event frames.",
"examples": [
{
"input": {
"ticketId": "ticket_123"
}
},
{
"input": {
"ticketId": "ticket_123"
},
"async": true
},
{
"input": {
"ticketId": "ticket_123"
},
"stream": true
}
]
},
"WorkflowRunListItem": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"workflowId": {
"type": "string",
"description": "Workflow that produced the run."
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"paused",
"redacting",
"completed",
"failed",
"cancelled"
],
"description": "Current or terminal run status. `redacting` is transient, reported while the output of a finished run is being scrubbed. `paused` means the run is not executing and is waiting to be resumed: either held at a human-in-the-loop pause point, or left paused because a resume attempt did not run to completion. The status alone does not say which. On the single-run response `paused.automaticResumeWaitingReason` distinguishes them: it is recorded whenever a resume attempt fails and cleared once a resume succeeds, so a null value means the run is waiting on human input. When the failure is not retryable or the automatic retries are exhausted, the reason is prefixed `Automatic resume requires manual intervention: `. Run-list items carry no `paused` object, so the two cases are indistinguishable there."
},
"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` to continue, and stop when it is null. Most v2 lists page, so null means the last page was reached. A few are full-set lists that return their whole bounded result in one response and therefore always report null; those say so in the operation description. Either way, null means there is nothing further to fetch — never construct a cursor 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
}
]
},
"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 the output of a finished run is being scrubbed. `paused` means the run is not executing and is waiting to be resumed: either held at a human-in-the-loop pause point, or left paused because a resume attempt did not run to completion. The status alone does not say which. On the single-run response `paused.automaticResumeWaitingReason` distinguishes them: it is recorded whenever a resume attempt fails and cleared once a resume succeeds, so a null value means the run is waiting on human input. When the failure is not retryable or the automatic retries are exhausted, the reason is prefixed `Automatic resume requires manual intervention: `. Run-list items carry no `paused` object, so the two cases are indistinguishable there."
},
"trigger": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Trigger type, or null before the run is recorded."
},
"startedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 start timestamp, or null while queued.",
"format": "date-time"
},
"endedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 8601 end timestamp, or null while nonterminal.",
"format": "date-time"
},
"durationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Run duration in milliseconds, or null while active."
},
"paused": {
"anyOf": [
{
"type": "object",
"properties": {
"contextId": {
"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": "Reason automatic resume is waiting, or null when it is not waiting."
},
"pausePointCount": {
"type": "number",
"description": "Number of pause points tracked for the execution."
},
"resumedCount": {
"type": "number",
"description": "Number of pause points that have resumed."
}
},
"required": [
"contextId",
"pausedAt",
"resumeAt",
"pauseKind",
"blockedOnBlockId",
"automaticResumeWaitingReason",
"pausePointCount",
"resumedCount"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Current pause details, or null when the run is not paused."
},
"cost": {
"anyOf": [
{
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total credits consumed by the run."
}
},
"required": ["total"],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Credit cost, or null when unavailable."
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ExecutionError"
},
{
"type": "null"
}
],
"description": "Structured execution failure, or null when none occurred."
},
"output": {
"anyOf": [
{
"description": "Final workflow output value."
},
{
"type": "null"
}
],
"description": "Final workflow output when requested, otherwise null."
},
"blockOutputs": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"description": "Output value produced by one workflow block."
}
},
{
"type": "null"
}
],
"description": "Selected block outputs when requested, otherwise null."
}
},
"required": [
"runId",
"workflowId",
"status",
"trigger",
"startedAt",
"endedAt",
"durationMs",
"paused",
"cost",
"error",
"output",
"blockOutputs"
],
"additionalProperties": false,
"title": "Workflow run status",
"description": "Detailed current state of a workflow run."
},
"WorkflowRunStatusResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowRunStatus"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Workflow run status response",
"description": "Detailed current state of a workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"status": "completed",
"trigger": "api",
"startedAt": "2026-08-09T18:04:10.000Z",
"endedAt": "2026-08-09T18:04:11.000Z",
"durationMs": 1000,
"paused": null,
"cost": {
"total": 12
},
"error": null,
"output": {
"result": "Ticket routed to Support"
},
"blockOutputs": null
}
}
]
},
"ResumeWorkflowSyncResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/WorkflowRunResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Synchronous workflow resume response",
"description": "Completed, failed, paused, or cancelled resumed workflow run.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"status": "completed",
"output": {
"result": "Ticket routed to Support"
},
"error": null,
"startedAt": "2026-08-09T18:04:10.000Z",
"endedAt": "2026-08-09T18:04:11.000Z",
"durationMs": 1000
}
}
]
},
"QueuedWorkflowResume": {
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"statusUrl": {
"type": "string",
"format": "uri",
"description": "Absolute URL of the workflow run resource."
},
"queuePosition": {
"description": "Current queue position, when available.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["runId", "statusUrl"],
"additionalProperties": false,
"title": "Queued workflow resume",
"description": "Receipt returned when a resumed workflow attempt is queued."
},
"ResumeWorkflowQueuedResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/QueuedWorkflowResume"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Queued workflow resume response",
"description": "Receipt returned when a resumed workflow attempt is queued.",
"examples": [
{
"data": {
"runId": "run_8f14e45f-ceea-467f-a",
"statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
}
}
]
},
"ResumeWorkflowRequest": {
"type": "object",
"properties": {
"contextId": {
"type": "string",
"minLength": 1,
"description": "Human-in-the-loop pause-context identifier."
},
"input": {
"description": "Input supplied to the paused workflow block."
}
},
"required": ["contextId"],
"additionalProperties": false,
"title": "Resume workflow request",
"description": "Pause context and optional input used to resume a workflow run.",
"examples": [
{
"contextId": "ctx_123",
"input": {
"approved": true
}
}
]
},
"CancelWorkflowRunResult": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether cancellation was accepted."
},
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Unique workflow run identifier.",
"examples": ["run_8f14e45f-ceea-467f-a"]
},
"redisAvailable": {
"type": "boolean",
"description": "Whether the distributed cancellation channel was available."
},
"durablyRecorded": {
"type": "boolean",
"description": "Whether cancellation was recorded durably."
},
"locallyAborted": {
"type": "boolean",
"description": "Whether an in-process execution was aborted."
},
"pausedCancelled": {
"type": "boolean",
"description": "Whether a paused execution was cancelled."
},
"reason": {
"description": "Machine-readable cancellation outcome. Present on every cancellation, including full successes — it is not a partial-failure marker. `recorded` means cancellation was durably recorded (the normal success value). `redis_unavailable` and `redis_write_failed` mean the distributed cancellation signal could not be written, so an already-running execution may not observe the cancellation. `paused_event_publish_failed` and `paused_database_cancel_failed` name the failing step when cancelling a paused human-in-the-loop run.",
"type": "string",
"enum": [
"recorded",
"redis_unavailable",
"redis_write_failed",
"paused_event_publish_failed",
"paused_database_cancel_failed"
]
}
},
"required": [
"success",
"runId",
"redisAvailable",
"durablyRecorded",
"locallyAborted",
"pausedCancelled"
],
"additionalProperties": false,
"title": "Cancel workflow run result",
"description": "Outcome of a workflow run cancellation request. Cancelling a run that has already reached a terminal state (completed, failed, or cancelled) succeeds with no effect rather than returning an error — treat this endpoint as best-effort and poll the run to observe the final state."
},
"CancelWorkflowRunResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/CancelWorkflowRunResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Cancel workflow run response",
"description": "Outcome of the cancellation request.",
"examples": [
{
"data": {
"success": true,
"runId": "run_8f14e45f-ceea-467f-a",
"redisAvailable": true,
"durablyRecorded": true,
"locallyAborted": true,
"pausedCancelled": false,
"reason": "recorded"
}
}
]
},
"WorkflowFolder": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Folder name."
},
"path": {
"type": "string",
"description": "Canonical folder path used as the public folder identifier."
},
"parentPath": {
"type": "string",
"description": "Canonical parent path; `/` is the root."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 timestamp when the folder was created.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "ISO 8601 timestamp when the folder was last updated.",
"format": "date-time"
},
"locked": {
"type": "boolean",
"description": "Whether the folder is currently locked for mutation."
}
},
"required": ["name", "path", "parentPath", "createdAt", "updatedAt", "locked"],
"additionalProperties": false,
"title": "Workflow folder",
"description": "A canonical workflow folder and its mutation lock state."
},
"WorkflowFolderListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowFolder"
},
"description": "Items in the current page."
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque cursor for the next page: send it back as `cursor` to continue, and stop when it is null. Most v2 lists page, so null means the last page was reached. A few are full-set lists that return their whole bounded result in one response and therefore always report null; those say so in the operation description. Either way, null means there is nothing further to fetch — never construct a cursor yourself."
}
},
"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
}
}
]
},
"CreateWorkflowFolderRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"description": "Workspace in which to create the folder."
},
"path": {
"description": "Path of the folder to create.",
"type": "string"
}
},
"required": ["workspaceId", "path"],
"additionalProperties": false,
"title": "Create workflow folder request",
"description": "Workspace and canonical path for a new workflow folder."
},
"RelocateWorkflowFolderResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/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,
"description": "Workspace containing the folder."
},
"path": {
"description": "Current folder path.",
"type": "string"
},
"destinationPath": {
"description": "New full path for the folder and its descendants.",
"type": "string"
}
},
"required": ["workspaceId", "path", "destinationPath"],
"additionalProperties": false,
"title": "Relocate workflow folder request",
"description": "Current and destination paths for a workflow folder."
},
"DeleteWorkflowFolderResult": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Path of the deleted workflow folder."
},
"deleted": {
"type": "boolean",
"const": true,
"description": "Confirms that the folder was deleted."
},
"deletedItems": {
"type": "object",
"properties": {
"folders": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of folders deleted."
},
"workflows": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of workflows deleted."
}
},
"required": ["folders", "workflows"],
"additionalProperties": false,
"description": "Resources removed by the deletion."
}
},
"required": ["path", "deleted", "deletedItems"],
"additionalProperties": false,
"title": "Delete workflow folder result",
"description": "Confirmation and deletion counts for a workflow folder."
},
"DeleteWorkflowFolderResponse": {
"type": "object",
"properties": {
"data": {
"description": "Response data.",
"$ref": "#/components/schemas/DeleteWorkflowFolderResult"
}
},
"required": ["data"],
"additionalProperties": false,
"title": "Delete workflow folder response",
"description": "Confirmation and counts for the deleted folder.",
"examples": [
{
"data": {
"path": "/Operations",
"deleted": true,
"deletedItems": {
"folders": 1,
"workflows": 0
}
}
}
]
}
}
},
"x-generated-by": "scripts/generate-openapi.ts"
}
Reference in New Issue View Git Blame Copy Permalink