@zapier/zapier-sdk 0.116.2 → 0.118.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +1410 -1385
  3. package/dist/beta.cjs +288 -280
  4. package/dist/beta.d.mts +61 -34
  5. package/dist/beta.d.ts +61 -34
  6. package/dist/beta.mjs +2 -2
  7. package/dist/{chunk-ITO7PPY7.cjs → chunk-B3ZGHT7T.cjs} +157 -53
  8. package/dist/{chunk-VGHAYAI2.mjs → chunk-DH2I3KFA.mjs} +156 -54
  9. package/dist/{chunk-G7AIFCV6.mjs → chunk-LZ65RRUJ.mjs} +1 -1
  10. package/dist/{chunk-OEFIDWC6.cjs → chunk-XNPIHDWS.cjs} +4 -4
  11. package/dist/experimental.cjs +397 -397
  12. package/dist/experimental.d.mts +67 -40
  13. package/dist/experimental.d.ts +67 -40
  14. package/dist/experimental.mjs +7 -15
  15. package/dist/{index-CKzlo4Y-.d.mts → index-BhbmZ5gy.d.mts} +90 -2
  16. package/dist/{index-CKzlo4Y-.d.ts → index-BhbmZ5gy.d.ts} +90 -2
  17. package/dist/index.cjs +286 -278
  18. package/dist/index.d.mts +1 -1
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.mjs +1 -1
  21. package/package.json +3 -3
package/README.md CHANGED
@@ -29,7 +29,19 @@
29
29
  - [`createClientCredentials`](#createclientcredentials)
30
30
  - [`deleteClientCredentials`](#deleteclientcredentials)
31
31
  - [`listClientCredentials`](#listclientcredentials)
32
- - [Code Workflows (Experimental)](#code-workflows-experimental)
32
+ - [Connections](#connections)
33
+ - [`createConnection`](#createconnection)
34
+ - [`findFirstConnection`](#findfirstconnection)
35
+ - [`findUniqueConnection`](#finduniqueconnection)
36
+ - [`getConnection`](#getconnection)
37
+ - [`getConnectionStartUrl`](#getconnectionstarturl)
38
+ - [`listConnections`](#listconnections)
39
+ - [`waitForNewConnection`](#waitfornewconnection)
40
+ - [HTTP Requests](#http-requests)
41
+ - [`fetch`](#fetch)
42
+ - [Human Inputs (Experimental)](#human-inputs-experimental)
43
+ - [`createForm`](#createform--experimental)
44
+ - [Next Gen Zaps (Experimental)](#next-gen-zaps-experimental)
33
45
  - [`cancelDurableRun`](#canceldurablerun--experimental)
34
46
  - [`createWorkflow`](#createworkflow--experimental)
35
47
  - [`createWorkflowDraft`](#createworkflowdraft--experimental)
@@ -63,18 +75,6 @@
63
75
  - [`updateWorkflow`](#updateworkflow--experimental)
64
76
  - [`updateWorkflowDraft`](#updateworkflowdraft--experimental)
65
77
  - [`validateWorkflow`](#validateworkflow--experimental)
66
- - [Connections](#connections)
67
- - [`createConnection`](#createconnection)
68
- - [`findFirstConnection`](#findfirstconnection)
69
- - [`findUniqueConnection`](#finduniqueconnection)
70
- - [`getConnection`](#getconnection)
71
- - [`getConnectionStartUrl`](#getconnectionstarturl)
72
- - [`listConnections`](#listconnections)
73
- - [`waitForNewConnection`](#waitfornewconnection)
74
- - [HTTP Requests](#http-requests)
75
- - [`fetch`](#fetch)
76
- - [Human Inputs (Experimental)](#human-inputs-experimental)
77
- - [`createForm`](#createform--experimental)
78
78
  - [Tables](#tables)
79
79
  - [`createTable`](#createtable)
80
80
  - [`createTableFields`](#createtablefields)
@@ -484,6 +484,8 @@ await zapier.apps.slack.read.channels({
484
484
 
485
485
  ### Accounts
486
486
 
487
+ Your Zapier user account, the one the SDK is signed in as. Use these to check who that is.
488
+
487
489
  #### `getProfile`
488
490
 
489
491
  Get current user's profile information
@@ -515,22 +517,25 @@ const { data: profile } = await zapier.getProfile();
515
517
 
516
518
  ### Actions
517
519
 
520
+ An action is something an app can do, like sending an email or creating a contact. Use these to find an app's actions, see what inputs they need, and run them directly, outside a Zap.
521
+
518
522
  #### `createActionRun`
519
523
 
520
524
  Start an action run and return its ID without waiting for the result. Running an action is asynchronous: this hands back a run ID immediately, and `getActionRun` fetches the outcome. Reach for this pair when you want to start work and collect it later (fan out many runs, hand the ID to another process, survive a restart). `runAction` is the one-call form that starts a run and waits for its result.
521
525
 
522
526
  **Parameters:**
523
527
 
524
- | Name | Type | Required | Default | Possible Values | Description |
525
- | ----------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
526
- | `options` | `object` | ✅ | — | — | |
527
- | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
528
- | ​ ↳ `actionType` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
529
- | ​ ↳ `action` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
530
- | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Required if the action needs a connection to authenticate and interact with the service. Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
531
- | ​ ↳ `inputs` | `object` | ❌ | — | — | Input parameters for the action |
532
- | ​ ↳ `page` | `string` | ❌ | — | — | Page to fetch for bulk read actions. Pass the `next_page` a previous run returned to fetch the following page. |
533
- | ​ ↳ `callbackUrl` | `string` | ❌ | — | — | URL Zapier posts the finished run to, so you do not have to poll for it. Must use HTTPS and resolve to a public host, so a local receiver needs a tunnel. The body matches what `getActionRun` returns. Verify the `Zapier-Callback-Signature` header, and expect the same run to arrive more than once. |
528
+ | Name | Type | Required | Default | Possible Values | Description |
529
+ | -------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
530
+ | `options` | `object` | ✅ | — | — | |
531
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
532
+ | ​ ↳ `actionType` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
533
+ | ​ ↳ `action` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
534
+ | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Required if the action needs a connection to authenticate and interact with the service. Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
535
+ | ​ ↳ `inputs` | `object` | ❌ | — | — | Input parameters for the action |
536
+ | ​ ↳ `page` | `string` | ❌ | — | — | Page to fetch for bulk read actions. Pass the `next_page` a previous run returned to fetch the following page. |
537
+ | ​ ↳ `callbackUrl` | `string` | ❌ | — | — | URL Zapier posts the finished run to, so you do not have to poll for it. Must use HTTPS and resolve to a public host, so a local receiver needs a tunnel. The body matches what `getActionRun` returns. Verify the `Zapier-Callback-Signature` header, and expect the same run to arrive more than once. |
538
+ | ​ ↳ `idempotencyKey` | `string` | ❌ | — | — | Key that makes retrying a run safe. Another run with the same key within 72 hours returns the original run instead of starting a new one, even if its inputs differ, so use a fresh key per distinct run. A paged run is sent with a key derived from this key and the page, so one key covers every page and retrying a page replays that page's run. |
534
539
 
535
540
  **Returns:** `Promise<StartedActionRunItem>`
536
541
 
@@ -878,18 +883,19 @@ Execute an action with the given inputs and wait for its results. Each result pa
878
883
 
879
884
  **Parameters:**
880
885
 
881
- | Name | Type | Required | Default | Possible Values | Description |
882
- | -------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
883
- | `options` | `object` | ✅ | — | — | |
884
- | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
885
- | ​ ↳ `actionType` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
886
- | ​ ↳ `action` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
887
- | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId. |
888
- | ​ ↳ `inputs` | `object` | ❌ | — | — | Input parameters for the action |
889
- | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | Maximum time to wait for action completion in seconds (default: 180) |
890
- | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of results per page |
891
- | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total items to return across all pages |
892
- | ​ ↳ `cursor` | `string` | ❌ | — | — | Cursor to start from |
886
+ | Name | Type | Required | Default | Possible Values | Description |
887
+ | -------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
888
+ | `options` | `object` | ✅ | — | — | |
889
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
890
+ | ​ ↳ `actionType` | `string` | ✅ | — | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type |
891
+ | ​ ↳ `action` | `string` | ✅ | — | — | Action key (e.g., 'send_message' or 'find_row') |
892
+ | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId. |
893
+ | ​ ↳ `inputs` | `object` | ❌ | — | — | Input parameters for the action |
894
+ | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | Maximum time to wait for action completion in seconds (default: 180) |
895
+ | ​ ↳ `idempotencyKey` | `string` | ❌ | — | — | Key that makes retrying a run safe. Another run with the same key within 72 hours returns the original run instead of starting a new one, even if its inputs differ, so use a fresh key per distinct run. A paged run is sent with a key derived from this key and the page, so one key covers every page and retrying a page replays that page's run. |
896
+ | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of results per page |
897
+ | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total items to return across all pages |
898
+ | ​ ↳ `cursor` | `string` | ❌ | — | — | Cursor to start from |
893
899
 
894
900
  **Returns:** `Promise<PaginatedResult<ActionResultItem>>`
895
901
 
@@ -928,6 +934,8 @@ for await (const actionResult of zapier
928
934
 
929
935
  ### Apps
930
936
 
937
+ An app is a web service that connects with Zapier, like Gmail or Slack. Use these to find apps and the keys other methods use to refer to them.
938
+
931
939
  #### `apps.{appKey}`
932
940
 
933
941
  Bind a connection alias or numeric connectionId to an app
@@ -953,12 +961,13 @@ Execute an action with the given inputs for the bound app, as an alternative to
953
961
 
954
962
  **Parameters:**
955
963
 
956
- | Name | Type | Required | Default | Possible Values | Description |
957
- | -------------------- | ---------------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
958
- | `options` | `object` | ✅ | — | — | |
959
- | ​ ↳ `inputs` | `object` | ❌ | — | — | Input parameters for the action |
960
- | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
961
- | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | Maximum time to wait for action completion in seconds (default: 180) |
964
+ | Name | Type | Required | Default | Possible Values | Description |
965
+ | -------------------- | ---------------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
966
+ | `options` | `object` | ✅ | — | — | |
967
+ | ​ ↳ `inputs` | `object` | ❌ | — | — | Input parameters for the action |
968
+ | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
969
+ | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | Maximum time to wait for action completion in seconds (default: 180) |
970
+ | ​ ↳ `idempotencyKey` | `string` | ❌ | — | — | Key that makes retrying a run safe. Another run with the same key within 72 hours returns the original run instead of starting a new one, even if its inputs differ, so use a fresh key per distinct run. A paged run is sent with a key derived from this key and the page, so one key covers every page and retrying a page replays that page's run. |
962
971
 
963
972
  **Returns:** `Promise<PaginatedResult<ActionResultItem>>`
964
973
 
@@ -1144,6 +1153,8 @@ for await (const app of zapier.listApps().items()) {
1144
1153
 
1145
1154
  ### Client Credentials
1146
1155
 
1156
+ SDK client credentials are a client ID and client secret that authenticate your code to the Zapier SDK, separate from the connections that authenticate apps. Use these to create, list, and revoke them.
1157
+
1147
1158
  #### `createClientCredentials`
1148
1159
 
1149
1160
  Create new client credentials for the authenticated user
@@ -1237,362 +1248,487 @@ for await (const clientCredentials of zapier.listClientCredentials().items()) {
1237
1248
  }
1238
1249
  ```
1239
1250
 
1240
- ### Code Workflows (Experimental)
1241
-
1242
- > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
1243
-
1244
- #### `cancelDurableRun` 🧪 _experimental_
1245
-
1246
- Cancel a run-once durable run in initialized or started status. Returns 409 if the run is already terminal.
1247
-
1248
- **Parameters:**
1249
-
1250
- | Name | Type | Required | Default | Possible Values | Description |
1251
- | --------- | -------- | -------- | ------- | --------------- | -------------- |
1252
- | `options` | `object` | ✅ | — | — | |
1253
- | ​ ↳ `run` | `string` | ✅ | — | — | Durable run ID |
1254
-
1255
- **Returns:** `Promise<DurableRunItem>`
1256
-
1257
- | Name | Type | Required | Possible Values | Description |
1258
- | ------------ | -------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1259
- | `data` | `object` | ✅ | — | |
1260
- | ​ ↳ `id` | `string` | ✅ | — | Run ID that was targeted |
1261
- | ​ ↳ `status` | `string` | ✅ | `cancelled` | Always `cancelled` on a successful call. Synthesized client-side — the backend returns 204; callers needing the run's full state should follow up with getDurableRun. |
1251
+ ### Connections
1262
1252
 
1263
- **Example:**
1253
+ A connection is an authenticated link between Zapier and your account in an app, like your company's Slack workspace, made with OAuth or an API key. Use these to find existing connections or create new ones for actions, triggers, and API requests to use.
1264
1254
 
1265
- ```typescript
1266
- const { data: durableRun } = await zapier.cancelDurableRun({
1267
- run: "example-run",
1268
- });
1269
- ```
1255
+ #### `createConnection`
1270
1256
 
1271
- #### `createWorkflow` 🧪 _experimental_
1257
+ Create a new app connection, end-to-end. Mints the start URL via `get-connection-start-url`, prints it to stderr, opportunistically opens it in a browser when it looks safe to do so (skipping CI / SSH / headless-Linux by default — pass `--browser always` to force, `--browser never` to suppress), then polls via `wait-for-new-connection` until the user completes OAuth and the new connection appears. Returns the connection.
1272
1258
 
1273
- Create a durable workflow container. Starts disabled with no version; publish a version to add code.
1259
+ This is the right command for most callers. Reach for the lower-level building blocks when you want either of: (a) hand off the URL and _not_ block on completion — call `get-connection-start-url` alone, no `wait-for-new-connection` needed, or (b) do something custom between minting the URL and waiting — call `get-connection-start-url`, do your work (email or DM the URL, render a QR code, etc.), then `wait-for-new-connection`.
1274
1260
 
1275
1261
  **Parameters:**
1276
1262
 
1277
- | Name | Type | Required | Default | Possible Values | Description |
1278
- | ----------------- | --------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------- |
1279
- | `options` | `object` | ✅ | — | — | |
1280
- | ​ ↳ `name` | `string` | ✅ | — | — | Workflow name |
1281
- | ​ ↳ `description` | `string` | ❌ | — | — | Optional description for the workflow |
1282
- | ​ ↳ `private` | `boolean` | ❌ | — | — | If true, only the creating user can see or manage this workflow. Defaults to false (account-visible). |
1263
+ | Name | Type | Required | Default | Possible Values | Description |
1264
+ | ------------------------------ | -------- | -------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1265
+ | `options` | `object` | ✅ | — | — | |
1266
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
1267
+ | ​ ↳ `browser` | `string` | ❌ | `"auto"` | `auto`, `always`, `never` | When to auto-open the URL in a browser. `auto` (default) opens in local sessions and skips opening in CI / SSH / headless-Linux. `always` forces the open attempt. `never` skips it. The URL is always printed to stderr regardless — a failed or skipped open degrades gracefully to copy-paste. |
1268
+ | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300). |
1269
+ | ​ ↳ `pollIntervalMilliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
1283
1270
 
1284
- **Returns:** `Promise<WorkflowItem>`
1271
+ **Returns:** `Promise<ConnectionItem>`
1285
1272
 
1286
- | Name | Type | Required | Possible Values | Description |
1287
- | ------------------------ | --------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1288
- | `data` | `object` | ✅ | — | |
1289
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1290
- | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
1291
- | ​ ↳ `description` | `string` | ✅ | — | Workflow description (null if unset) |
1292
- | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
1293
- | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
1294
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers. Always false on a new workflow until enabled. |
1295
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
1296
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
1297
- | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1273
+ | Name | Type | Required | Possible Values | Description |
1274
+ | ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
1275
+ | `data` | `object` | ✅ | — | |
1276
+ | ​ ↳ `id` | `string` | ✅ | — | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
1277
+ | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the connection was created for (e.g., 'SlackCLIAPI'). |
1278
+ | ​ ↳ `title` | `string` | ❌ | — | Human-readable connection title set by the auth flow, when available. |
1298
1279
 
1299
1280
  **Example:**
1300
1281
 
1301
1282
  ```typescript
1302
- const { data: workflow } = await zapier.createWorkflow({
1303
- name: "example-name",
1283
+ const { data: connection } = await zapier.createConnection({
1284
+ app: "example-app",
1304
1285
  });
1305
1286
  ```
1306
1287
 
1307
- #### `createWorkflowDraft` 🧪 _experimental_
1288
+ #### `findFirstConnection`
1308
1289
 
1309
- Fork a new draft from the workflow's current live version (or a blank stub before the first publish)
1290
+ Find the first connection matching the criteria
1310
1291
 
1311
1292
  **Parameters:**
1312
1293
 
1313
- | Name | Type | Required | Default | Possible Values | Description |
1314
- | -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
1315
- | `options` | `object` | ✅ | — | — | |
1316
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1317
- | ​ ↳ `slug` | `string` | ❌ | — | — | Optional display name for the draft. When omitted, the server generates one. Need not be unique among the workflow's open drafts. |
1294
+ | Name | Type | Required | Default | Possible Values | Description |
1295
+ | ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
1296
+ | `options` | `object` | ✅ | — | — | |
1297
+ | ​ ↳ `search` | `string` | ❌ | — | — | Search term to filter connections by title |
1298
+ | ​ ↳ `title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
1299
+ | ​ ↳ `owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
1300
+ | ​ ↳ `app` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
1301
+ | ​ ↳ `account` | `string` | ❌ | — | — | Account to filter by |
1302
+ | ​ ↳ `includeShared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
1303
+ | ​ ↳ `status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
1318
1304
 
1319
- **Returns:** `Promise<WorkflowDraftItem>`
1305
+ **Returns:** `Promise<ConnectionItem>`
1320
1306
 
1321
- | Name | Type | Required | Possible Values | Description |
1322
- | ---------------------------- | -------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
1323
- | `data` | `object` | ✅ | — | |
1324
- | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
1325
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1326
- | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
1327
- | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
1328
- | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1329
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
1330
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
1331
- | ​ ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
1332
- | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
1333
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
1334
- | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
1335
- | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
1336
- | ​ ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
1337
- | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
1338
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
1339
- | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
1340
- | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
1341
- | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
1307
+ | Name | Type | Required | Possible Values | Description |
1308
+ | ------------------------------ | --------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
1309
+ | `data` | `object` | ✅ | — | |
1310
+ | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
1311
+ | ​ ↳ `date` | `string` | ✅ | — | Date created |
1312
+ | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
1313
+ | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
1314
+ | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
1315
+ | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
1316
+ | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
1317
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
1318
+ | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
1319
+ | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
1320
+ | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
1321
+ | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
1322
+ | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
1323
+ | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
1324
+ | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
1325
+ | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
1326
+ | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
1327
+ | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
1328
+ | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
1329
+ | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
1330
+ | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
1331
+ | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
1332
+ | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
1333
+ | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
1334
+ | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
1335
+ | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
1336
+ | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
1337
+ | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
1338
+ | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
1342
1339
 
1343
1340
  **Example:**
1344
1341
 
1345
1342
  ```typescript
1346
- const { data: workflowDraft } = await zapier.createWorkflowDraft({
1347
- workflow: "example-workflow",
1348
- });
1343
+ const { data: connection } = await zapier.findFirstConnection();
1349
1344
  ```
1350
1345
 
1351
- #### `deleteWorkflow` 🧪 _experimental_
1346
+ #### `findUniqueConnection`
1352
1347
 
1353
- Delete a durable workflow. Throws `ZapierNotFoundError` if the workflow doesn't exist; callers wanting idempotency should catch that themselves.
1348
+ Find a unique connection matching the criteria
1354
1349
 
1355
1350
  **Parameters:**
1356
1351
 
1357
- | Name | Type | Required | Default | Possible Values | Description |
1358
- | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1359
- | `options` | `object` | ✅ | — | — | |
1360
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1352
+ | Name | Type | Required | Default | Possible Values | Description |
1353
+ | ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
1354
+ | `options` | `object` | ✅ | — | — | |
1355
+ | ​ ↳ `search` | `string` | ❌ | — | — | Search term to filter connections by title |
1356
+ | ​ ↳ `title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
1357
+ | ​ ↳ `owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
1358
+ | ​ ↳ `app` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
1359
+ | ​ ↳ `account` | `string` | ❌ | — | — | Account to filter by |
1360
+ | ​ ↳ `includeShared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
1361
+ | ​ ↳ `status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
1361
1362
 
1362
- **Returns:** `Promise<{ success: boolean }>`
1363
+ **Returns:** `Promise<ConnectionItem>`
1363
1364
 
1364
- | Name | Type | Required | Possible Values | Description |
1365
- | -------- | -------- | -------- | --------------- | ------------------------------------------ |
1366
- | `data` | `object` | ✅ | — | |
1367
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID that was targeted for deletion |
1365
+ | Name | Type | Required | Possible Values | Description |
1366
+ | ------------------------------ | --------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
1367
+ | `data` | `object` | ✅ | — | |
1368
+ | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
1369
+ | ​ ↳ `date` | `string` | ✅ | — | Date created |
1370
+ | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
1371
+ | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
1372
+ | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
1373
+ | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
1374
+ | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
1375
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
1376
+ | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
1377
+ | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
1378
+ | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
1379
+ | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
1380
+ | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
1381
+ | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
1382
+ | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
1383
+ | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
1384
+ | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
1385
+ | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
1386
+ | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
1387
+ | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
1388
+ | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
1389
+ | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
1390
+ | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
1391
+ | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
1392
+ | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
1393
+ | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
1394
+ | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
1395
+ | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
1396
+ | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
1368
1397
 
1369
1398
  **Example:**
1370
1399
 
1371
1400
  ```typescript
1372
- const result = await zapier.deleteWorkflow({
1373
- workflow: "example-workflow",
1374
- });
1401
+ const { data: connection } = await zapier.findUniqueConnection();
1375
1402
  ```
1376
1403
 
1377
- #### `disableAgenticManagement` 🧪 _experimental_
1404
+ #### `getConnection`
1378
1405
 
1379
- Stop Agentic Management from working on one workflow. Its settings are kept, not deleted: the modes and auto-approve choice stay on file, so calling enableAgenticManagement later resumes with those settings instead of the defaults.
1406
+ Get details for a specific connection
1380
1407
 
1381
1408
  **Parameters:**
1382
1409
 
1383
- | Name | Type | Required | Default | Possible Values | Description |
1384
- | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------- |
1385
- | `options` | `object` | ✅ | — | — | |
1386
- | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to take out of agentic management. |
1387
-
1388
- **Returns:** `Promise<{ success: boolean }>`
1410
+ | Name | Type | Required | Default | Possible Values | Description |
1411
+ | ---------------- | ---------------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1412
+ | `options` | `object` | ✅ | — | — | |
1413
+ | ​ ↳ `connection` | `string, number` | ✅ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
1389
1414
 
1390
- | Name | Type | Required | Possible Values | Description |
1391
- | -------- | --------- | -------- | --------------- | -------------------------------------------------------------------- |
1392
- | `data` | `object` | ✅ | — | |
1393
- | ​ ↳ `ok` | `boolean` | ✅ | — | True when Zapier accepted the request to stop managing the workflow. |
1415
+ **Returns:** `Promise<ConnectionItem>`
1394
1416
 
1395
- **Example:**
1417
+ | Name | Type | Required | Possible Values | Description |
1418
+ | ------------------------------ | --------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
1419
+ | `data` | `object` | ✅ | — | |
1420
+ | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
1421
+ | ​ ↳ `date` | `string` | ✅ | — | Date created |
1422
+ | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
1423
+ | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
1424
+ | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
1425
+ | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
1426
+ | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
1427
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
1428
+ | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
1429
+ | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
1430
+ | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
1431
+ | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
1432
+ | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
1433
+ | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
1434
+ | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
1435
+ | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
1436
+ | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
1437
+ | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
1438
+ | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
1439
+ | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
1440
+ | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
1441
+ | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
1442
+ | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
1443
+ | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
1444
+ | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
1445
+ | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
1446
+ | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
1447
+ | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
1448
+ | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
1449
+
1450
+ **Example:**
1396
1451
 
1397
1452
  ```typescript
1398
- const result = await zapier.disableAgenticManagement({
1399
- workflow: "example-workflow",
1453
+ const { data: connection } = await zapier.getConnection({
1454
+ connection: "example-connection",
1400
1455
  });
1401
1456
  ```
1402
1457
 
1403
- #### `disableWorkflow` 🧪 _experimental_
1458
+ #### `getConnectionStartUrl`
1404
1459
 
1405
- Disable a durable workflow so it stops accepting triggers
1460
+ Mint a short-lived URL that begins an SDK-initiated connection flow. The URL is signed by zapier.com and bound to the current user/account — opening it in a different browser session will fail the binding check. Returns the URL as data so the caller decides what to do with it.
1461
+
1462
+ Use this directly (rather than the higher-level `create-connection`) when you want either of: (a) hand off the URL and _not_ block waiting for completion — call this alone, skip `wait-for-new-connection` entirely, or (b) do something custom between minting the URL and waiting for the connection — call this, then email or DM the URL, render it as a QR code for mobile sign-in, etc., then call `wait-for-new-connection`. For the common case where you'd just print and poll back-to-back, `create-connection` is one call.
1463
+
1464
+ Pair with `wait-for-new-connection` to detect completion: pass the `startedAt` returned here straight through (it's the server's mint time, so polling isn't affected by client clock skew). Example (JS):
1465
+
1466
+ ```ts
1467
+ const {
1468
+ data: { url, app, startedAt },
1469
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
1470
+ // hand `url` off — print it, DM it, email it, render a button, whatever
1471
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
1472
+ ```
1406
1473
 
1407
1474
  **Parameters:**
1408
1475
 
1409
- | Name | Type | Required | Default | Possible Values | Description |
1410
- | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1411
- | `options` | `object` | ✅ | — | — | |
1412
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1476
+ | Name | Type | Required | Default | Possible Values | Description |
1477
+ | --------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
1478
+ | `options` | `object` | ✅ | — | — | |
1479
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
1413
1480
 
1414
- **Returns:** `Promise<WorkflowItem>`
1481
+ **Returns:** `Promise<ConnectionStartUrlItem>`
1415
1482
 
1416
- | Name | Type | Required | Possible Values | Description |
1417
- | ------------- | --------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
1418
- | `data` | `object` | ✅ | — | |
1419
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1420
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Workflow's enabled state after the operation. Typically false; mirrors the row's true state in case a concurrent enable raced with this call. |
1483
+ | Name | Type | Required | Possible Values | Description |
1484
+ | --------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1485
+ | `data` | `object` | ✅ | — | |
1486
+ | ​ ↳ `url` | `string` | ✅ | — | URL the user should open in their browser to complete the auth flow. Single-use, time-limited. |
1487
+ | ​ ↳ `expiresAt` | `number` | ✅ | — | Unix timestamp (seconds) after which the URL's signature is rejected by zapier.com. |
1488
+ | ​ ↳ `startedAt` | `number` | ✅ | — | Unix timestamp (seconds) when the server minted the URL. Use it as the `startedAt` for `wait-for-new-connection` so polling is anchored to server time rather than a possibly-skewed client clock. |
1489
+ | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the URL was minted for (e.g., 'SlackCLIAPI'). Useful for downstream filtering. |
1421
1490
 
1422
1491
  **Example:**
1423
1492
 
1424
1493
  ```typescript
1425
- const { data: workflow } = await zapier.disableWorkflow({
1426
- workflow: "example-workflow",
1494
+ const { data: connectionStartUrl } = await zapier.getConnectionStartUrl({
1495
+ app: "example-app",
1427
1496
  });
1428
1497
  ```
1429
1498
 
1430
- #### `discardWorkflowDraft` 🧪 _experimental_
1499
+ #### `listConnections`
1431
1500
 
1432
- Discard an open workflow draft (soft delete). The draft's unpublished edits stop resolving; the published version is untouched.
1501
+ List available connections with optional filtering
1433
1502
 
1434
1503
  **Parameters:**
1435
1504
 
1436
- | Name | Type | Required | Default | Possible Values | Description |
1437
- | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1438
- | `options` | `object` | ✅ | — | — | |
1439
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1440
- | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
1505
+ | Name | Type | Required | Default | Possible Values | Description |
1506
+ | ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
1507
+ | `options` | `object` | ✅ | — | — | |
1508
+ | ​ ↳ `search` | `string` | ❌ | — | — | Search term to filter connections by title |
1509
+ | ​ ↳ `title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
1510
+ | ​ ↳ `owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
1511
+ | ​ ↳ `app` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
1512
+ | ​ ↳ `connections` | `array` | ❌ | — | — | List of connection IDs to filter by |
1513
+ | ​ ↳ `account` | `string` | ❌ | — | — | Account to filter by |
1514
+ | ​ ↳ `includeShared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
1515
+ | ​ ↳ `status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
1516
+ | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of connections per page. The upstream API may cap this and reject values above its limit. |
1517
+ | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total items to return across all pages |
1518
+ | ​ ↳ `cursor` | `string` | ❌ | — | — | Cursor to start from |
1441
1519
 
1442
- **Returns:** `Promise<WorkflowDraftItem>`
1520
+ **Returns:** `Promise<PaginatedResult<ConnectionItem>>`
1443
1521
 
1444
- | Name | Type | Required | Possible Values | Description |
1445
- | ---------------------------- | -------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
1446
- | `data` | `object` | ✅ | — | |
1447
- | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
1448
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1449
- | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
1450
- | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
1451
- | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1452
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
1453
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
1454
- | ​ ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
1455
- | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
1456
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
1457
- | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
1458
- | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
1459
- | ​ ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
1460
- | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
1461
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
1462
- | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
1463
- | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
1464
- | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
1522
+ | Name | Type | Required | Possible Values | Description |
1523
+ | ------------------------------ | ---------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
1524
+ | `data[]` | `object[]` | ✅ | — | |
1525
+ | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
1526
+ | ​ ↳ `date` | `string` | ✅ | — | Date created |
1527
+ | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
1528
+ | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
1529
+ | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
1530
+ | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
1531
+ | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
1532
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
1533
+ | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
1534
+ | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
1535
+ | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
1536
+ | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
1537
+ | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
1538
+ | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
1539
+ | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
1540
+ | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
1541
+ | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
1542
+ | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
1543
+ | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
1544
+ | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
1545
+ | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
1546
+ | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
1547
+ | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
1548
+ | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
1549
+ | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
1550
+ | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
1551
+ | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
1552
+ | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
1553
+ | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
1554
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
1465
1555
 
1466
1556
  **Example:**
1467
1557
 
1468
1558
  ```typescript
1469
- const result = await zapier.discardWorkflowDraft({
1470
- workflow: "example-workflow",
1471
- draft: "example-draft",
1472
- });
1559
+ // Get first page and a cursor for the second page
1560
+ const { data: connections, nextCursor } = await zapier.listConnections();
1561
+
1562
+ // Or iterate over all pages
1563
+ for await (const page of zapier.listConnections().pages()) {
1564
+ // Do something with each page
1565
+ }
1566
+
1567
+ // Or iterate over individual items across all pages
1568
+ for await (const connection of zapier.listConnections().items()) {
1569
+ // Do something with each connection
1570
+ }
1473
1571
  ```
1474
1572
 
1475
- #### `enableAgenticManagement` 🧪 _experimental_
1573
+ #### `waitForNewConnection`
1476
1574
 
1477
- Put one workflow under Agentic Management. A workflow disabled earlier comes back with the modes and auto-approve choice it had, unless you pass new ones here.
1575
+ Wait for a new connection to appear for the given app. Polls the connections list newest-first until the most recent matching row's `date` is at or after the started-at timestamp, then returns it. Pair with `get-connection-start-url` — that mints the URL the user opens, this waits for the resulting connection to land. Errors with a timeout after the configured timeout (default 5 min). Example (JS):
1576
+
1577
+ ```ts
1578
+ const {
1579
+ data: { url, app, startedAt },
1580
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
1581
+ // show `url` to the user via the channel they're reading from
1582
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
1583
+ ```
1478
1584
 
1479
1585
  **Parameters:**
1480
1586
 
1481
- | Name | Type | Required | Default | Possible Values | Description |
1482
- | ----------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1483
- | `options` | `object` | ✅ | — | — | |
1484
- | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to put under agentic management. |
1485
- | ​ ↳ `modes` | `array` | ❌ | — | — | The modes to run for this workflow. Omit it and the workflow starts on `heal` alone. A mode is what Agentic Management watches for and what it changes in response. `heal` monitors runs for errors and, when something breaks, diagnoses the cause and drafts and tests a fix; it is the mode a workflow gets by default. `expand` grows what the workflow covers: it reviews runs that succeeded without actually doing anything — a lookup that matched nothing, a filter that passed no items, a trigger payload no branch handles — and proposes a new branch or step to handle that case, rather than rewriting the ones that already work. `harden` watches the AI steps: when an AI step keeps doing the same work the same way, it converts that step into fixed code, so the workflow runs faster, costs less, and behaves the same way every time. Modes stack — each one you name runs alongside the others, and a mode you leave out does nothing, so a workflow on `expand` alone does not repair failed runs. Whether a change goes live on its own or waits for someone to approve it is `autoApprove`, not the mode. |
1486
- | ​ ↳ `autoApprove` | `boolean` | ❌ | — | — | Apply the fixes Agentic Management proposes without asking first. Set it to false and each fix waits for someone to approve it. Omit it and fixes are applied without asking, which is what a workflow enabled for the first time gets; a workflow being re-enabled keeps the setting it had before. |
1587
+ | Name | Type | Required | Default | Possible Values | Description |
1588
+ | ------------------------------ | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1589
+ | `options` | `object` | ✅ | — | — | |
1590
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
1591
+ | ​ ↳ `startedAt` | `number` | ✅ | — | — | Unix timestamp (seconds). Only connections whose `date` is at or after this value count as 'new'. Prefer the `startedAt` returned by `get-connection-start-url` — it's server-stamped, so the comparison isn't thrown off by client clock skew. If you mint the timestamp yourself, capture it _before_ showing the start URL so a fast OAuth completion isn't missed. |
1592
+ | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | How long to wait before giving up. Default 5 minutes (300). |
1593
+ | ​ ↳ `pollIntervalMilliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
1487
1594
 
1488
- **Returns:** `Promise<AgenticManagementEnableResultItem>`
1595
+ **Returns:** `Promise<ConnectionItem>`
1489
1596
 
1490
- | Name | Type | Required | Possible Values | Description |
1491
- | ---------------- | -------- | -------- | --------------- | ----------------------------------------------------------------------- |
1492
- | `data` | `object` | ✅ | — | |
1493
- | ​ ↳ `manager_id` | `string` | ✅ | — | ID of the manager automation Zapier provisioned to watch this workflow. |
1597
+ | Name | Type | Required | Possible Values | Description |
1598
+ | ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
1599
+ | `data` | `object` | ✅ | — | |
1600
+ | ​ ↳ `id` | `string` | ✅ | — | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
1601
+ | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the connection was created for (e.g., 'SlackCLIAPI'). |
1602
+ | ​ ↳ `title` | `string` | ❌ | — | Human-readable connection title set by the auth flow, when available. |
1494
1603
 
1495
1604
  **Example:**
1496
1605
 
1497
1606
  ```typescript
1498
- const { data: agenticManagementEnableResult } =
1499
- await zapier.enableAgenticManagement({
1500
- workflow: "example-workflow",
1501
- });
1607
+ const { data: connection } = await zapier.waitForNewConnection({
1608
+ app: "example-app",
1609
+ startedAt: 100,
1610
+ });
1502
1611
  ```
1503
1612
 
1504
- #### `enableWorkflow` 🧪 _experimental_
1613
+ ### HTTP Requests
1505
1614
 
1506
- Enable a durable workflow so it accepts triggers
1615
+ Make authenticated requests to an app's API through Zapier's API proxy, using a connection's credentials so your code never handles tokens or keys. Useful when an app's actions don't cover what you need.
1507
1616
 
1508
- **Parameters:**
1617
+ #### `fetch`
1509
1618
 
1510
- | Name | Type | Required | Default | Possible Values | Description |
1511
- | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1512
- | `options` | `object` | ✅ | — | — | |
1513
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1619
+ Make authenticated HTTP requests to any API through Zapier. Pass a connectionId to automatically inject the user's stored credentials (OAuth tokens, API keys, etc.) into the outgoing request. Mirrors the native fetch(url, init?) signature with additional Zapier-specific options.
1514
1620
 
1515
- **Returns:** `Promise<WorkflowItem>`
1621
+ **Parameters:**
1516
1622
 
1517
- | Name | Type | Required | Possible Values | Description |
1518
- | ------------- | --------- | -------- | --------------- | ---------------------------------------------------------- |
1519
- | `data` | `object` | ✅ | — | |
1520
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1521
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Workflow's enabled state after the operation (always true) |
1623
+ | Name | Type | Required | Default | Possible Values | Description |
1624
+ | -------------------- | ------------------------ | -------- | ------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1625
+ | `url` | `string, custom` | ✅ | — | — | The full URL of the API endpoint to call (proxied through Zapier's API Proxy) |
1626
+ | `init` | `object` | ❌ | — | — | Request options including method, headers, body, and authentication |
1627
+ | ​ ↳ `method` | `string` | ❌ | — | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method for the request (defaults to GET) |
1628
+ | ​ ↳ `headers` | `object` | ❌ | — | — | HTTP headers to include in the request |
1629
+ | ​ ↳ `body` | `string, custom, record` | ❌ | — | — | Request body — plain objects and JSON strings are auto-detected and Content-Type is set accordingly |
1630
+ | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
1631
+ | ​ ↳ `callbackUrl` | `string` | ❌ | — | — | URL to send async response to (makes request async) |
1632
+ | ​ ↳ `idempotencyKey` | `string` | ❌ | — | — | Key used to make API Proxy retries safe from duplicate side effects |
1633
+ | ​ ↳ `maxTimeSeconds` | `number` | ❌ | — | — | Maximum seconds to wait for a response. Honored on a best-effort basis; the server may silently enforce a lower ceiling. |
1634
+
1635
+ **Returns:** `Promise<Response>`
1522
1636
 
1523
1637
  **Example:**
1524
1638
 
1525
1639
  ```typescript
1526
- const { data: workflow } = await zapier.enableWorkflow({
1527
- workflow: "example-workflow",
1528
- });
1640
+ const result = await zapier.fetch("https://example.com", {});
1529
1641
  ```
1530
1642
 
1531
- #### `getAgenticManagementConfig` 🧪 _experimental_
1643
+ ### Human Inputs (Experimental)
1532
1644
 
1533
- Read the Agentic Management config for one workflow.
1534
-
1535
- **Parameters:**
1536
-
1537
- | Name | Type | Required | Default | Possible Values | Description |
1538
- | -------------- | -------- | -------- | ------- | --------------- | --------------------------- |
1539
- | `options` | `object` | ✅ | — | — | |
1540
- | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to read. |
1541
-
1542
- **Returns:** `Promise<AgenticManagementConfigItem>`
1543
-
1544
- | Name | Type | Required | Possible Values | Description |
1545
- | ------------------ | --------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1546
- | `data` | `object` | ✅ | — | |
1547
- | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow this config describes. |
1548
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether Agentic Management is currently active for this workflow. |
1549
- | ​ ↳ `auto_approve` | `boolean` | ✅ | — | Whether fixes are applied without asking for approval first. `false` when Agentic Management has never been set up for this workflow. |
1550
- | ​ ↳ `modes` | `array` | ✅ | — | The modes the workflow runs. Still listed while `enabled` is false, because the settings are kept for a later re-enable — so read `enabled` to tell whether they are in effect, not this list. |
1551
- | ​ ↳ `manager_id` | `string` | ❌ | — | ID of the manager automation Zapier provisioned for this workflow, once one exists; `null` otherwise. Use it to link to that automation to see the runs it has taken. |
1552
-
1553
- **Example:**
1645
+ Collect information from people with Zapier Forms. Use these to create a form and share its link to gather responses.
1554
1646
 
1555
- ```typescript
1556
- const { data: agenticManagementConfig } =
1557
- await zapier.getAgenticManagementConfig({
1558
- workflow: "example-workflow",
1559
- });
1560
- ```
1647
+ > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
1561
1648
 
1562
- #### `getAgenticManagementIntent` 🧪 _experimental_
1649
+ #### `createForm` 🧪 _experimental_
1563
1650
 
1564
- Read the intent recorded for one workflow version: the plain-language description of what that version of the workflow is meant to do.
1651
+ Create a Zapier Form from a title and optional fields. Forms publish by default and return a shareable `hosted_url`; set `draft` to save without publishing.
1565
1652
 
1566
1653
  **Parameters:**
1567
1654
 
1568
- | Name | Type | Required | Default | Possible Values | Description |
1569
- | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1570
- | `options` | `object` | ✅ | — | — | |
1571
- | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to read. |
1572
- | ​ ↳ `version` | `string` | ❌ | — | — | The workflow version the intent belongs to. Each version stores its own intent, and a version never picks up the intent of another, so publishing a new version starts it with none. Omit this to use the workflow's current published version. |
1655
+ | Name | Type | Required | Default | Possible Values | Description |
1656
+ | ------------------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1657
+ | `options` | `object` | ✅ | — | — | |
1658
+ | ​ ↳ `title` | `string` | ✅ | — | — | The title shown in the Forms UI and on the form. |
1659
+ | ​ ↳ `description` | `string` | ❌ | — | — | An optional description of the form. |
1660
+ | ​ ↳ `fields[]` | `object[]` | ❌ | — | — | Initial fields to add to the form. |
1661
+ | ​   ↳ `label` | `string` | ✅ | — | — | Human-readable label shown above the input. |
1662
+ | ​   ↳ `type` | `string` | ✅ | — | `short_text`, `long_text`, `email`, `number`, `yes_no`, `url`, `date`, `date_range`, `currency`, `phone_number`, `dropdown`, `integration_backed` | The type of field. |
1663
+ | ​   ↳ `required` | `boolean` | ❌ | — | — | Whether the field must be answered before the form can submit. |
1664
+ | ​   ↳ `disabled` | `boolean` | ❌ | — | — | When true, the field is rendered read-only — shown but not editable. A rendering hint only; it is not enforced during submission validation. |
1665
+ | ​   ↳ `variant` | `string` | ❌ | — | `checkbox`, `radio` | For `yes_no` fields: `checkbox` renders a single toggle, `radio` renders explicit yes/no buttons. Defaults to `checkbox`. |
1666
+ | ​   ↳ `multiUrl` | `boolean` | ❌ | — | — | For `url` fields: when true the field accepts a list of URLs, otherwise a single URL. Defaults to false. |
1667
+ | ​   ↳ `includeTime` | `boolean` | ❌ | — | — | For `date` and `date_range` fields: when true the picker also captures a time. Defaults to false. |
1668
+ | ​   ↳ `currencyFormat` | `string` | ❌ | — | — | For `currency` fields: ISO 4217 currency code (e.g. `usd`, `eur`). Controls the symbol shown in the form UI. |
1669
+ | ​   ↳ `decimals` | `literal` | ❌ | — | — | For `currency` fields: allowed decimal places. `0` for whole numbers, `2` for up to two decimal places. Defaults to `2`. |
1670
+ | ​   ↳ `defaultCountry` | `string` | ❌ | — | — | For `phone_number` fields: ISO 3166-1 alpha-2 code for the default selected country (e.g. `US`). Defaults to `US`. |
1671
+ | ​   ↳ `phoneNumberFormat` | `string` | ❌ | — | `national`, `international` | For `phone_number` fields: `national` omits the country-code prefix, `international` includes it. Defaults to `national`. |
1672
+ | ​   ↳ `acceptedCountries` | `array` | ❌ | — | — | For `phone_number` fields: restrict input to specific ISO 3166-1 alpha-2 country codes. Omit to allow all countries. |
1673
+ | ​   ↳ `options[]` | `object[]` | ❌ | — | — | For `dropdown` fields: the selectable options. At least one is required. |
1674
+ | ​     ↳ `value` | `string` | ✅ | — | — | The value submitted when this option is selected. |
1675
+ | ​     ↳ `label` | `string` | ✅ | — | — | Human-readable label shown to the user. |
1676
+ | ​   ↳ `multiSelect` | `boolean` | ❌ | — | — | For `dropdown` fields: when true the user may select multiple options. Defaults to false. |
1677
+ | ​   ↳ `dataSource` | `object` | ❌ | — | — | For `integration_backed` fields: where to fetch the field's options from at render time. |
1678
+ | ​     ↳ `app` | `string` | ✅ | — | — | Zapier app to pull options from. See `listApps` for the catalog. |
1679
+ | ​     ↳ `actionType` | `string` | ✅ | — | `read`, `read_bulk` | Whether the data source returns a single record (`read`) or a collection (`read_bulk`). |
1680
+ | ​     ↳ `resource` | `string` | ✅ | — | — | Resource name within the app — typically a trigger or search key from the app's definition. |
1681
+ | ​     ↳ `valueKey` | `string` | ❌ | — | — | Property on each returned record to use as the submitted option value. Defaults to `id`. |
1682
+ | ​     ↳ `labelKey` | `string` | ❌ | — | — | Property on each returned record to use as the displayed option label. Defaults to a sensible name field. |
1683
+ | ​ ↳ `draft` | `boolean` | ❌ | — | — | When true, save without publishing. Omit to publish immediately, making `hosted_url` live. |
1684
+ | ​ ↳ `confirmationTitle` | `string` | ❌ | — | — | Heading shown to the respondent after they submit. Omit to use the form renderer's default. |
1685
+ | ​ ↳ `confirmationMessage` | `string` | ❌ | — | — | Message shown to the respondent after they submit, below the confirmation title. Omit to use the form renderer's default. |
1686
+ | ​ ↳ `callbackUrl` | `string` | ❌ | — | — | Absolute http/https URL notified with the submission JSON each time the form is answered. |
1687
+ | ​ ↳ `consumerAuth` | `string` | ❌ | — | `none`, `zapier` | Who may open the published form. `none` (the default) leaves it public to anyone with the link; `zapier` requires the visitor to be signed in to Zapier on the form's owning account. |
1688
+ | ​ ↳ `document` | `object` | ❌ | — | — | Escape hatch: a complete form document tree, sent as-is. When supplied it replaces the document built from `fields`, and `title`, `description`, `confirmationTitle`, and `confirmationMessage` are ignored. Use only for structures the flat field list cannot express, such as approval decisions or multi-column row layout. |
1689
+ | ​   ↳ `id` | `string` | ✅ | — | — | |
1690
+ | ​   ↳ `type` | `string` | ✅ | — | `root` | |
1691
+ | ​   ↳ `attrs` | `object` | ✅ | — | — | |
1692
+ | ​     ↳ `schema_version` | `number` | ✅ | — | — | |
1693
+ | ​     ↳ `title` | `string` | ✅ | — | — | |
1694
+ | ​   ↳ `children` | `array` | ❌ | — | — | |
1573
1695
 
1574
- **Returns:** `Promise<AgenticManagementIntentItem>`
1696
+ **Returns:** `Promise<FormItem>`
1575
1697
 
1576
- | Name | Type | Required | Possible Values | Description |
1577
- | ------------------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1578
- | `data` | `object` | ✅ | — | |
1579
- | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow the intent belongs to. |
1580
- | ​ ↳ `workflow_version_id` | `string` | ✅ | — | The version this read or write actually landed on, so you can tell which one answered when you omitted `version`. `null` only when you read a workflow that has nothing published yet. |
1581
- | ​ ↳ `intent` | `string` | ✅ | — | The intent stored for this version, or `null` when this version has none. Intent is never carried over from another version. |
1582
- | ​ ↳ `updated_at` | `string` | ❌ | — | When the intent was last written; `null` when never captured. |
1698
+ | Name | Type | Required | Possible Values | Description |
1699
+ | ----------------------- | --------- | -------- | --------------- | ----------- |
1700
+ | `data` | `object` | ✅ | — | |
1701
+ | ​ ↳ `id` | `string` | ✅ | — | |
1702
+ | ​ ↳ `title` | `string` | ✅ | — | |
1703
+ | ​ ↳ `description` | `string` | ❌ | — | |
1704
+ | ​ ↳ `hosted_url` | `string` | ✅ | — | |
1705
+ | ​ ↳ `submission_count` | `number` | ✅ | — | |
1706
+ | ​ ↳ `account_id` | `number` | ✅ | — | |
1707
+ | ​ ↳ `owner_id` | `string` | ✅ | — | |
1708
+ | ​ ↳ `created_at` | `string` | ✅ | — | |
1709
+ | ​ ↳ `updated_at` | `string` | ✅ | — | |
1710
+ | ​ ↳ `document` | `unknown` | ✅ | — | |
1711
+ | ​ ↳ `last_published_at` | `string` | ✅ | — | |
1712
+ | ​ ↳ `consumer_auth` | `unknown` | ✅ | — | |
1713
+ | ​ ↳ `callback_url` | `unknown` | ✅ | — | |
1583
1714
 
1584
1715
  **Example:**
1585
1716
 
1586
1717
  ```typescript
1587
- const { data: agenticManagementIntent } =
1588
- await zapier.getAgenticManagementIntent({
1589
- workflow: "example-workflow",
1590
- });
1718
+ const { data: form } = await zapier.createForm({
1719
+ title: "example-title",
1720
+ });
1591
1721
  ```
1592
1722
 
1593
- #### `getDurableRun` 🧪 _experimental_
1723
+ ### Next Gen Zaps (Experimental)
1594
1724
 
1595
- Get the full state of a run-once durable run, including its operations journal
1725
+ Next Gen Zaps are a new version of Zaps that run on code, which makes them easier for agents and AI tools to understand. Use these to build, test, publish, and run Next Gen Zaps, and to check on their runs.
1726
+
1727
+ > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
1728
+
1729
+ #### `cancelDurableRun` 🧪 _experimental_
1730
+
1731
+ Cancel a run-once durable run in initialized or started status. Returns 409 if the run is already terminal.
1596
1732
 
1597
1733
  **Parameters:**
1598
1734
 
@@ -1603,127 +1739,67 @@ Get the full state of a run-once durable run, including its operations journal
1603
1739
 
1604
1740
  **Returns:** `Promise<DurableRunItem>`
1605
1741
 
1606
- | Name | Type | Required | Possible Values | Description |
1607
- | ---------------- | --------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
1608
- | `data` | `object` | ✅ | — | |
1609
- | ​ ↳ `id` | `string` | ✅ | — | Run ID (UUID) |
1610
- | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
1611
- | ​ ↳ `input` | `unknown` | ✅ | — | Input data passed to the run |
1612
- | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
1613
- | ​ ↳ `error` | `object` | ✅ | — | Structured error details when the run failed (null otherwise) |
1614
- | ​ ↳ `execution` | `object` | ✅ | — | Linked execution, including the operations journal. Null while the run is still in `initialized` state. |
1615
- | ​ ↳ `is_private` | `boolean` | ✅ | — | When true, the run is visible only to the creating user; otherwise visible across the account. |
1616
- | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
1617
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
1742
+ | Name | Type | Required | Possible Values | Description |
1743
+ | ------------ | -------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1744
+ | `data` | `object` | ✅ | — | |
1745
+ | ​ ↳ `id` | `string` | ✅ | — | Run ID that was targeted |
1746
+ | ​ ↳ `status` | `string` | ✅ | `cancelled` | Always `cancelled` on a successful call. Synthesized client-side — the backend returns 204; callers needing the run's full state should follow up with getDurableRun. |
1618
1747
 
1619
1748
  **Example:**
1620
1749
 
1621
1750
  ```typescript
1622
- const { data: durableRun } = await zapier.getDurableRun({
1751
+ const { data: durableRun } = await zapier.cancelDurableRun({
1623
1752
  run: "example-run",
1624
1753
  });
1625
1754
  ```
1626
1755
 
1627
- #### `getTriggerRun` 🧪 _experimental_
1628
-
1629
- Get the workflow run associated with a deployed workflow's trigger. Useful immediately after firing a trigger, when you have the trigger ID but not yet the run ID.
1630
-
1631
- **Parameters:**
1632
-
1633
- | Name | Type | Required | Default | Possible Values | Description |
1634
- | ------------- | -------- | -------- | ------- | --------------- | ------------------- |
1635
- | `options` | `object` | ✅ | — | — | |
1636
- | ​ ↳ `trigger` | `string` | ✅ | — | — | Workflow trigger ID |
1637
-
1638
- **Returns:** `Promise<WorkflowRunItem>`
1639
-
1640
- | Name | Type | Required | Possible Values | Description |
1641
- | ------------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
1642
- | `data` | `object` | ✅ | — | |
1643
- | ​ ↳ `id` | `string` | ✅ | — | Workflow run ID (UUID) |
1644
- | ​ ↳ `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
1645
- | ​ ↳ `workflow_version_id` | `string` | ✅ | — | Workflow version the run is bound to |
1646
- | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
1647
- | ​ ↳ `input` | `unknown` | ✅ | — | Input passed to the run |
1648
- | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
1649
- | ​ ↳ `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
1650
- | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
1651
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
1652
-
1653
- **Example:**
1654
-
1655
- ```typescript
1656
- const { data: workflowRun } = await zapier.getTriggerRun({
1657
- trigger: "example-trigger",
1658
- });
1659
- ```
1660
-
1661
- #### `getWorkflow` 🧪 _experimental_
1756
+ #### `createWorkflow` 🧪 _experimental_
1662
1757
 
1663
- Get a durable workflow with its current version details and trigger claim status
1758
+ Create a durable workflow container. Starts disabled with no version; publish a version to add code.
1664
1759
 
1665
1760
  **Parameters:**
1666
1761
 
1667
- | Name | Type | Required | Default | Possible Values | Description |
1668
- | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1669
- | `options` | `object` | ✅ | — | — | |
1670
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1762
+ | Name | Type | Required | Default | Possible Values | Description |
1763
+ | ----------------- | --------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------- |
1764
+ | `options` | `object` | ✅ | — | — | |
1765
+ | ​ ↳ `name` | `string` | ✅ | — | — | Workflow name |
1766
+ | ​ ↳ `description` | `string` | ❌ | — | — | Optional description for the workflow |
1767
+ | ​ ↳ `private` | `boolean` | ❌ | — | — | If true, only the creating user can see or manage this workflow. Defaults to false (account-visible). |
1671
1768
 
1672
1769
  **Returns:** `Promise<WorkflowItem>`
1673
1770
 
1674
- | Name | Type | Required | Possible Values | Description |
1675
- | ------------------------------ | ---------- | -------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1676
- | `data` | `object` | ✅ | — | |
1677
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1678
- | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
1679
- | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
1680
- | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
1681
- | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
1682
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
1683
- | ​ ↳ `disabled_reason` | `string` | ❌ | `trigger_claim_failed` | Why the workflow is off, when system-disabled. Null when not system-disabled. Independent of per-trigger claim status: an enabled workflow can still have a failed trigger. |
1684
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
1685
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
1686
- | ​ ↳ `current_version` | `object` | ❌ | — | The currently published version, if any. Absent for workflows with no version published yet. |
1687
- | ​   ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1688
- | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID |
1689
- | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1690
- | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1691
- | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1692
- | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1693
- | ​   ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1694
- | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
1695
- | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
1696
- | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
1697
- | ​ ↳ `triggers[]` | `object[]` | ✅ | — | Trigger configurations from the current version, with live claim status. Empty array when the workflow has no triggers. |
1698
- | ​   ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
1699
- | ​   ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
1700
- | ​   ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
1701
- | ​   ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
1702
- | ​   ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
1703
- | ​   ↳ `error` | `string` | ❌ | — | Failure reason for the latest claim. Present (non-null) only when status is 'failed'. |
1704
- | ​   ↳ `details` | `object` | ❌ | — | Trigger-type-specific metadata; shape varies by trigger type (e.g. `webhook_url` on catch-hook triggers). Null or absent when none applies. |
1705
- | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1706
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
1771
+ | Name | Type | Required | Possible Values | Description |
1772
+ | ------------------------ | --------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1773
+ | `data` | `object` | ✅ | — | |
1774
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1775
+ | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
1776
+ | ​ ↳ `description` | `string` | ✅ | — | Workflow description (null if unset) |
1777
+ | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
1778
+ | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
1779
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers. Always false on a new workflow until enabled. |
1780
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
1781
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
1782
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1707
1783
 
1708
1784
  **Example:**
1709
1785
 
1710
1786
  ```typescript
1711
- const { data: workflow } = await zapier.getWorkflow({
1712
- workflow: "example-workflow",
1787
+ const { data: workflow } = await zapier.createWorkflow({
1788
+ name: "example-name",
1713
1789
  });
1714
1790
  ```
1715
1791
 
1716
- #### `getWorkflowDraft` 🧪 _experimental_
1792
+ #### `createWorkflowDraft` 🧪 _experimental_
1717
1793
 
1718
- Get full details of a workflow draft including source files
1794
+ Fork a new draft from the workflow's current live version (or a blank stub before the first publish)
1719
1795
 
1720
1796
  **Parameters:**
1721
1797
 
1722
- | Name | Type | Required | Default | Possible Values | Description |
1723
- | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1724
- | `options` | `object` | ✅ | — | — | |
1725
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1726
- | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
1798
+ | Name | Type | Required | Default | Possible Values | Description |
1799
+ | -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
1800
+ | `options` | `object` | ✅ | — | — | |
1801
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1802
+ | ​ ↳ `slug` | `string` | ❌ | — | — | Optional display name for the draft. When omitted, the server generates one. Need not be unique among the workflow's open drafts. |
1727
1803
 
1728
1804
  **Returns:** `Promise<WorkflowDraftItem>`
1729
1805
 
@@ -1752,75 +1828,66 @@ Get full details of a workflow draft including source files
1752
1828
  **Example:**
1753
1829
 
1754
1830
  ```typescript
1755
- const { data: workflowDraft } = await zapier.getWorkflowDraft({
1831
+ const { data: workflowDraft } = await zapier.createWorkflowDraft({
1756
1832
  workflow: "example-workflow",
1757
- draft: "example-draft",
1758
1833
  });
1759
1834
  ```
1760
1835
 
1761
- #### `getWorkflowRun` 🧪 _experimental_
1836
+ #### `deleteWorkflow` 🧪 _experimental_
1762
1837
 
1763
- Get the current state of a workflow run — a live run of a published workflow version, or a draft run launched via `runWorkflowDraft` (the `kind` field says which)
1838
+ Delete a durable workflow. Throws `ZapierNotFoundError` if the workflow doesn't exist; callers wanting idempotency should catch that themselves.
1764
1839
 
1765
1840
  **Parameters:**
1766
1841
 
1767
- | Name | Type | Required | Default | Possible Values | Description |
1768
- | -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------- |
1769
- | `options` | `object` | ✅ | — | — | |
1770
- | ​ ↳ `workflow` | `string` | ❌ | — | — | Parent workflow ID — used only to scope the CLI run-id picker; ignored by the API call. |
1771
- | ​ ↳ `run` | `string` | ✅ | — | — | Workflow run ID |
1842
+ | Name | Type | Required | Default | Possible Values | Description |
1843
+ | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1844
+ | `options` | `object` | ✅ | — | — | |
1845
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1772
1846
 
1773
- **Returns:** `Promise<WorkflowRunItem>`
1847
+ **Returns:** `Promise<{ success: boolean }>`
1774
1848
 
1775
- | Name | Type | Required | Possible Values | Description |
1776
- | ------ | -------- | -------- | --------------- | -------------------------------------------------- |
1777
- | `data` | `object` | ✅ | — | One of the variants below, distinguished by `kind` |
1849
+ | Name | Type | Required | Possible Values | Description |
1850
+ | -------- | -------- | -------- | --------------- | ------------------------------------------ |
1851
+ | `data` | `object` | ✅ | — | |
1852
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID that was targeted for deletion |
1778
1853
 
1779
- **When `kind` is `"live"`:**
1854
+ **Example:**
1780
1855
 
1781
- | Name | Type | Required | Possible Values | Description |
1782
- | --------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
1783
- | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
1784
- | `workflow_id` | `string` | ✅ | — | The workflow this run belongs to |
1785
- | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
1786
- | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
1787
- | `input` | `unknown` | ✅ | — | Input passed to the run |
1788
- | `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
1789
- | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
1790
- | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
1791
- | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
1792
- | `kind` | `string` | ✅ | `live` | A run of a published workflow version. |
1793
- | `trigger_id` | `string` | ✅ | — | ID of the trigger that fired this run. Null for runs created without a trigger. |
1794
- | `workflow_version_id` | `string` | ✅ | — | Workflow version the run is bound to. Null in rare edge cases. |
1856
+ ```typescript
1857
+ const result = await zapier.deleteWorkflow({
1858
+ workflow: "example-workflow",
1859
+ });
1860
+ ```
1795
1861
 
1796
- **When `kind` is `"draft"`:**
1862
+ #### `disableAgenticManagement` 🧪 _experimental_
1797
1863
 
1798
- | Name | Type | Required | Possible Values | Description |
1799
- | ------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1800
- | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
1801
- | `workflow_id` | `string` | ✅ | — | The workflow this run belongs to |
1802
- | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
1803
- | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
1804
- | `input` | `unknown` | ✅ | — | Input passed to the run |
1805
- | `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
1806
- | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
1807
- | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
1808
- | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
1809
- | `kind` | `string` | ✅ | `draft` | A run launched from a workflow draft via `runWorkflowDraft`. |
1810
- | `workflow_draft_id` | `string` | ✅ | — | The draft this run was launched from. Null once that draft has been deleted (the run outlives its draft). |
1811
- | `draft_revision` | `number` | ✅ | — | The draft's revision at the moment this run was created. Compare against the draft's current `draft_revision` to tell whether the run still reflects the draft as it now stands. |
1864
+ Stop Agentic Management from working on one workflow. Its settings are kept, not deleted: the modes and auto-approve choice stay on file, so calling enableAgenticManagement later resumes with those settings instead of the defaults.
1865
+
1866
+ **Parameters:**
1867
+
1868
+ | Name | Type | Required | Default | Possible Values | Description |
1869
+ | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------- |
1870
+ | `options` | `object` | ✅ | — | — | |
1871
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to take out of agentic management. |
1872
+
1873
+ **Returns:** `Promise<{ success: boolean }>`
1874
+
1875
+ | Name | Type | Required | Possible Values | Description |
1876
+ | -------- | --------- | -------- | --------------- | -------------------------------------------------------------------- |
1877
+ | `data` | `object` | ✅ | — | |
1878
+ | ​ ↳ `ok` | `boolean` | ✅ | — | True when Zapier accepted the request to stop managing the workflow. |
1812
1879
 
1813
1880
  **Example:**
1814
1881
 
1815
1882
  ```typescript
1816
- const { data: workflowRun } = await zapier.getWorkflowRun({
1817
- run: "example-run",
1883
+ const result = await zapier.disableAgenticManagement({
1884
+ workflow: "example-workflow",
1818
1885
  });
1819
1886
  ```
1820
1887
 
1821
- #### `getWorkflowVersion` 🧪 _experimental_
1888
+ #### `disableWorkflow` 🧪 _experimental_
1822
1889
 
1823
- Get full details of a workflow version including source files
1890
+ Disable a durable workflow so it stops accepting triggers
1824
1891
 
1825
1892
  **Parameters:**
1826
1893
 
@@ -1828,1292 +1895,1246 @@ Get full details of a workflow version including source files
1828
1895
  | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1829
1896
  | `options` | `object` | ✅ | — | — | |
1830
1897
  | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1831
- | ​ ↳ `version` | `string` | ✅ | — | — | Workflow version ID |
1832
1898
 
1833
- **Returns:** `Promise<WorkflowVersionItem>`
1899
+ **Returns:** `Promise<WorkflowItem>`
1834
1900
 
1835
- | Name | Type | Required | Possible Values | Description |
1836
- | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
1837
- | `data` | `object` | ✅ | — | |
1838
- | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1839
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1840
- | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1841
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1842
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1843
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1844
- | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1845
- | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
1846
- | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
1847
- | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
1901
+ | Name | Type | Required | Possible Values | Description |
1902
+ | ------------- | --------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
1903
+ | `data` | `object` | ✅ | — | |
1904
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1905
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Workflow's enabled state after the operation. Typically false; mirrors the row's true state in case a concurrent enable raced with this call. |
1848
1906
 
1849
1907
  **Example:**
1850
1908
 
1851
1909
  ```typescript
1852
- const { data: workflowVersion } = await zapier.getWorkflowVersion({
1910
+ const { data: workflow } = await zapier.disableWorkflow({
1853
1911
  workflow: "example-workflow",
1854
- version: "example-version",
1855
1912
  });
1856
1913
  ```
1857
1914
 
1858
- #### `importWorkflow` 🧪 _experimental_
1915
+ #### `discardWorkflowDraft` 🧪 _experimental_
1859
1916
 
1860
- Convert an existing Zap into a durable workflow. Transforms the Zap's latest published version (falling back to its draft only when the Zap has never been published) and puts the resulting source in an open draft. The workflow is created disabled with no published version, so publish the draft to make it live. The original Zap is untouched and keeps running.
1917
+ Discard an open workflow draft (soft delete). The draft's unpublished edits stop resolving; the published version is untouched.
1861
1918
 
1862
1919
  **Parameters:**
1863
1920
 
1864
- | Name | Type | Required | Default | Possible Values | Description |
1865
- | ------------- | --------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
1866
- | `options` | `object` | ✅ | — | — | |
1867
- | ​ ↳ `zap` | `string` | ✅ | — | — | ID of the Zap to import. Must be owned by the requesting user. Recorded on the created workflow as source_zap_id. |
1868
- | ​ ↳ `name` | `string` | ❌ | — | — | Name for the created workflow. Defaults to a kebab-cased form of the Zap's title, or "imported-workflow" when the Zap has no title. |
1869
- | ​ ↳ `private` | `boolean` | ❌ | — | — | Restrict the created workflow to the creating user. Defaults to false, which makes it account-visible. |
1921
+ | Name | Type | Required | Default | Possible Values | Description |
1922
+ | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1923
+ | `options` | `object` | ✅ | — | — | |
1924
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1925
+ | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
1870
1926
 
1871
- **Returns:** `Promise<ImportWorkflowResponse>`
1927
+ **Returns:** `Promise<WorkflowDraftItem>`
1872
1928
 
1873
- | Name | Type | Required | Possible Values | Description |
1874
- | ------------------------------ | ---------- | -------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1875
- | `data` | `object` | ✅ | — | |
1876
- | ​ ↳ `workflow` | `object` | ✅ | — | The created workflow. Disabled, with no published version, and source_zap_id set to the imported Zap. |
1877
- | ​   ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1878
- | ​   ↳ `name` | `string` | ✅ | — | Workflow name |
1879
- | ​   ↳ `description` | `string` | ❌ | — | Optional workflow description (null if unset) |
1880
- | ​   ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
1881
- | ​   ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
1882
- | ​   ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow accepts triggers. An import always lands disabled. |
1883
- | ​   ↳ `disabled_reason` | `string` | ❌ | `trigger_claim_failed` | Why the workflow is off, when system-disabled. |
1884
- | ​   ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
1885
- | ​   ↳ `source_zap_id` | `string` | ❌ | — | The Zap this workflow was imported from. |
1886
- | ​   ↳ `created_by_user_id` | `string` | ✅ | — | |
1887
- | ​   ↳ `updated_by_user_id` | `string` | ❌ | — | |
1888
- | ​   ↳ `current_version_id` | `string` | ❌ | — | Null on a fresh import, which has no published version yet. |
1889
- | ​   ↳ `triggers[]` | `object[]` | ✅ | — | Empty on a fresh import, which has no published version yet. |
1890
- | ​     ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
1891
- | ​     ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
1892
- | ​     ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
1893
- | ​     ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
1894
- | ​     ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
1895
- | ​     ↳ `error` | `string` | ❌ | — | Failure reason for the latest claim. Present (non-null) only when status is 'failed'. |
1896
- | ​     ↳ `details` | `object` | ❌ | — | Trigger-type-specific metadata; shape varies by trigger type (e.g. `webhook_url` on catch-hook triggers). Null or absent when none applies. |
1897
- | ​   ↳ `created_at` | `string` | ✅ | — | |
1898
- | ​   ↳ `updated_at` | `string` | ❌ | — | |
1899
- | ​ ↳ `draft` | `object` | ✅ | — | The open draft holding the transformed source. |
1900
- | ​   ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
1901
- | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1902
- | ​   ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
1903
- | ​   ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
1904
- | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1905
- | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
1906
- | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
1907
- | ​   ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
1908
- | ​   ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
1909
- | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
1910
- | ​   ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
1911
- | ​   ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
1912
- | ​   ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
1913
- | ​   ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
1914
- | ​   ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
1915
- | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
1916
- | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
1917
- | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
1918
- | ​ ↳ `issues[]` | `object[]` | ✅ | — | Blocking and non-blocking translation issues from the transform, passed through unchanged. Blocking issues do not prevent draft creation; they must be resolved before the draft will publish. |
1919
- | ​   ↳ `line` | `number` | ✅ | — | 1-based line in the generated source the issue relates to, or 0 when not line-specific. |
1920
- | ​   ↳ `column` | `number` | ✅ | — | 1-based column, or 0 when not column-specific. |
1921
- | ​   ↳ `node_kind` | `string` | ✅ | — | Category of the issue, used to group and message them, e.g. "invalid-connection-id", "DelayStep", "app-version-conflict". |
1922
- | ​   ↳ `step_name` | `string` | ❌ | — | ZDL step id or name the issue originated from, when known. |
1923
- | ​   ↳ `message` | `string` | ✅ | — | Human-readable description of the issue. |
1924
- | ​   ↳ `blocking` | `boolean` | ✅ | — | Whether the issue must be resolved before the draft can be published. Computed server-side, so callers do not re-derive it. A blocking issue does not prevent the draft being created. |
1929
+ | Name | Type | Required | Possible Values | Description |
1930
+ | ---------------------------- | -------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
1931
+ | `data` | `object` | ✅ | — | |
1932
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
1933
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1934
+ | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
1935
+ | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
1936
+ | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1937
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
1938
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
1939
+ | ​ ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
1940
+ | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
1941
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
1942
+ | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
1943
+ | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
1944
+ | ​ ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
1945
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
1946
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
1947
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
1948
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
1949
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
1925
1950
 
1926
1951
  **Example:**
1927
1952
 
1928
1953
  ```typescript
1929
- const { data: workflow } = await zapier.importWorkflow({
1930
- zap: "example-zap",
1954
+ const result = await zapier.discardWorkflowDraft({
1955
+ workflow: "example-workflow",
1956
+ draft: "example-draft",
1931
1957
  });
1932
1958
  ```
1933
1959
 
1934
- #### `listDurableRuns` 🧪 _experimental_
1960
+ #### `enableAgenticManagement` 🧪 _experimental_
1935
1961
 
1936
- List run-once durable runs for the authenticated account, newest first
1962
+ Put one workflow under Agentic Management. A workflow disabled earlier comes back with the modes and auto-approve choice it had, unless you pass new ones here.
1937
1963
 
1938
1964
  **Parameters:**
1939
1965
 
1940
- | Name | Type | Required | Default | Possible Values | Description |
1941
- | -------------- | -------- | -------- | ------- | --------------- | ---------------------------------------------- |
1942
- | `options` | `object` | ✅ | — | — | |
1943
- | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of runs per page (max 100) |
1944
- | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
1945
- | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total items to return across all pages |
1966
+ | Name | Type | Required | Default | Possible Values | Description |
1967
+ | ----------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1968
+ | `options` | `object` | ✅ | — | — | |
1969
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to put under agentic management. |
1970
+ | ​ ↳ `modes` | `array` | ❌ | — | — | The modes to run for this workflow. Omit it and the workflow starts on `heal` alone. A mode is what Agentic Management watches for and what it changes in response. `heal` monitors runs for errors and, when something breaks, diagnoses the cause and drafts and tests a fix; it is the mode a workflow gets by default. `expand` grows what the workflow covers: it reviews runs that succeeded without actually doing anything — a lookup that matched nothing, a filter that passed no items, a trigger payload no branch handles — and proposes a new branch or step to handle that case, rather than rewriting the ones that already work. `harden` watches the AI steps: when an AI step keeps doing the same work the same way, it converts that step into fixed code, so the workflow runs faster, costs less, and behaves the same way every time. Modes stack — each one you name runs alongside the others, and a mode you leave out does nothing, so a workflow on `expand` alone does not repair failed runs. Whether a change goes live on its own or waits for someone to approve it is `autoApprove`, not the mode. |
1971
+ | ​ ↳ `autoApprove` | `boolean` | ❌ | — | — | Apply the fixes Agentic Management proposes without asking first. Set it to false and each fix waits for someone to approve it. Omit it and fixes are applied without asking, which is what a workflow enabled for the first time gets; a workflow being re-enabled keeps the setting it had before. |
1946
1972
 
1947
- **Returns:** `Promise<PaginatedResult<DurableRunItem>>`
1973
+ **Returns:** `Promise<AgenticManagementEnableResultItem>`
1948
1974
 
1949
- | Name | Type | Required | Possible Values | Description |
1950
- | ------------------ | ---------- | -------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
1951
- | `data[]` | `object[]` | ✅ | — | |
1952
- | ​ ↳ `id` | `string` | ✅ | — | Run ID (UUID) |
1953
- | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
1954
- | ​ ↳ `input` | `unknown` | ✅ | — | Input data passed to the run |
1955
- | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
1956
- | ​ ↳ `error` | `object` | ✅ | — | Structured error details when the run failed (null otherwise) |
1957
- | ​ ↳ `execution_id` | `string` | ✅ | — | Linked execution ID. Null until the run leaves the `initialized` state. |
1958
- | ​ ↳ `is_private` | `boolean` | ✅ | — | When true, the run is visible only to the creating user; otherwise visible across the account. |
1959
- | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
1960
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
1961
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
1975
+ | Name | Type | Required | Possible Values | Description |
1976
+ | ---------------- | -------- | -------- | --------------- | ----------------------------------------------------------------------- |
1977
+ | `data` | `object` | ✅ | — | |
1978
+ | ​ ↳ `manager_id` | `string` | ✅ | — | ID of the manager automation Zapier provisioned to watch this workflow. |
1962
1979
 
1963
1980
  **Example:**
1964
1981
 
1965
1982
  ```typescript
1966
- // Get first page and a cursor for the second page
1967
- const { data: durableRuns, nextCursor } = await zapier.listDurableRuns();
1968
-
1969
- // Or iterate over all pages
1970
- for await (const page of zapier.listDurableRuns().pages()) {
1971
- // Do something with each page
1972
- }
1973
-
1974
- // Or iterate over individual items across all pages
1975
- for await (const durableRun of zapier.listDurableRuns().items()) {
1976
- // Do something with each durableRun
1977
- }
1983
+ const { data: agenticManagementEnableResult } =
1984
+ await zapier.enableAgenticManagement({
1985
+ workflow: "example-workflow",
1986
+ });
1978
1987
  ```
1979
1988
 
1980
- #### `listWorkflowDrafts` 🧪 _experimental_
1989
+ #### `enableWorkflow` 🧪 _experimental_
1981
1990
 
1982
- List drafts for a workflow, most recently edited first (open drafts by default)
1991
+ Enable a durable workflow so it accepts triggers
1983
1992
 
1984
1993
  **Parameters:**
1985
1994
 
1986
- | Name | Type | Required | Default | Possible Values | Description |
1987
- | -------------- | -------- | -------- | ------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1988
- | `options` | `object` | ✅ | — | — | |
1989
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1990
- | ​ ↳ `status` | `string` | ❌ | — | `open`, `discarded` | Filter by draft status (server default: open) |
1991
- | ​ ↳ `slug` | `string` | ❌ | — | — | Filter by exact slug match. Slugs are not unique, so this returns every draft with this slug matching the selected status, ordered by most recent activity and paginated |
1992
- | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of drafts per page (max 100) |
1993
- | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
1994
- | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total drafts to return across all pages |
1995
+ | Name | Type | Required | Default | Possible Values | Description |
1996
+ | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
1997
+ | `options` | `object` | ✅ | — | — | |
1998
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
1995
1999
 
1996
- **Returns:** `Promise<PaginatedResult<WorkflowDraftItem>>`
2000
+ **Returns:** `Promise<WorkflowItem>`
1997
2001
 
1998
- | Name | Type | Required | Possible Values | Description |
1999
- | ---------------------------- | ---------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
2000
- | `data[]` | `object[]` | ✅ | — | |
2001
- | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
2002
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2003
- | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
2004
- | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
2005
- | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
2006
- | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
2007
- | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
2008
- | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
2009
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2002
+ | Name | Type | Required | Possible Values | Description |
2003
+ | ------------- | --------- | -------- | --------------- | ---------------------------------------------------------- |
2004
+ | `data` | `object` | ✅ | — | |
2005
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
2006
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Workflow's enabled state after the operation (always true) |
2010
2007
 
2011
2008
  **Example:**
2012
2009
 
2013
2010
  ```typescript
2014
- // Get first page and a cursor for the second page
2015
- const { data: workflowDrafts, nextCursor } = await zapier.listWorkflowDrafts({
2011
+ const { data: workflow } = await zapier.enableWorkflow({
2016
2012
  workflow: "example-workflow",
2017
2013
  });
2018
-
2019
- // Or iterate over all pages
2020
- for await (const page of zapier
2021
- .listWorkflowDrafts({
2022
- workflow: "example-workflow",
2023
- })
2024
- .pages()) {
2025
- // Do something with each page
2026
- }
2027
-
2028
- // Or iterate over individual items across all pages
2029
- for await (const workflowDraft of zapier
2030
- .listWorkflowDrafts({
2031
- workflow: "example-workflow",
2032
- })
2033
- .items()) {
2034
- // Do something with each workflowDraft
2035
- }
2036
2014
  ```
2037
2015
 
2038
- #### `listWorkflowRuns` 🧪 _experimental_
2016
+ #### `getAgenticManagementConfig` 🧪 _experimental_
2039
2017
 
2040
- List workflow runs for a specific workflow, newest first. Live runs (of published versions) and draft runs share the one list; pass `kind` to narrow it to one.
2018
+ Read the Agentic Management config for one workflow.
2041
2019
 
2042
2020
  **Parameters:**
2043
2021
 
2044
- | Name | Type | Required | Default | Possible Values | Description |
2045
- | -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------- |
2046
- | `options` | `object` | ✅ | — | — | |
2047
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2048
- | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of runs per page (max 100) |
2049
- | ​ ↳ `kind` | `string` | ❌ | — | `live`, `draft` | Return only runs of this kind. Omit for both, interleaved by recency. |
2050
- | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
2051
- | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total runs to return across all pages |
2052
-
2053
- **Returns:** `Promise<PaginatedResult<WorkflowRunItem>>`
2054
-
2055
- | Name | Type | Required | Possible Values | Description |
2056
- | ------------ | ---------- | -------- | --------------- | -------------------------------------------------------------- |
2057
- | `data[]` | `object[]` | ✅ | — | One of the variants below, distinguished by `kind` |
2058
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2059
-
2060
- **When `kind` is `"live"`:**
2061
-
2062
- | Name | Type | Required | Possible Values | Description |
2063
- | --------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
2064
- | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2065
- | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
2066
- | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2067
- | `input` | `unknown` | ✅ | — | Input passed to the run |
2068
- | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2069
- | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2070
- | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2071
- | `kind` | `string` | ✅ | `live` | A run of a published workflow version. |
2072
- | `trigger_id` | `string` | ✅ | — | ID of the trigger that fired this run. Null for runs created without a trigger. |
2073
- | `workflow_version_id` | `string` | ✅ | — | Workflow version the run is bound to. Null in rare edge cases. |
2022
+ | Name | Type | Required | Default | Possible Values | Description |
2023
+ | -------------- | -------- | -------- | ------- | --------------- | --------------------------- |
2024
+ | `options` | `object` | ✅ | — | — | |
2025
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to read. |
2074
2026
 
2075
- **When `kind` is `"draft"`:**
2027
+ **Returns:** `Promise<AgenticManagementConfigItem>`
2076
2028
 
2077
- | Name | Type | Required | Possible Values | Description |
2078
- | ------------------- | --------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
2079
- | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2080
- | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
2081
- | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2082
- | `input` | `unknown` | ✅ | — | Input passed to the run |
2083
- | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2084
- | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2085
- | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2086
- | `kind` | `string` | ✅ | `draft` | A run launched from a workflow draft via `runWorkflowDraft`. |
2087
- | `workflow_draft_id` | `string` | ✅ | — | The draft this run was launched from. Null once that draft has been deleted (the run outlives its draft). |
2088
- | `draft_revision` | `number` | ✅ | — | The draft's revision at the moment this run was created. |
2029
+ | Name | Type | Required | Possible Values | Description |
2030
+ | ------------------ | --------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2031
+ | `data` | `object` | ✅ | — | |
2032
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow this config describes. |
2033
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether Agentic Management is currently active for this workflow. |
2034
+ | ​ ↳ `auto_approve` | `boolean` | ✅ | — | Whether fixes are applied without asking for approval first. `false` when Agentic Management has never been set up for this workflow. |
2035
+ | ​ ↳ `modes` | `array` | ✅ | — | The modes the workflow runs. Still listed while `enabled` is false, because the settings are kept for a later re-enable — so read `enabled` to tell whether they are in effect, not this list. |
2036
+ | ​ ↳ `manager_id` | `string` | ❌ | — | ID of the manager automation Zapier provisioned for this workflow, once one exists; `null` otherwise. Use it to link to that automation to see the runs it has taken. |
2089
2037
 
2090
2038
  **Example:**
2091
2039
 
2092
2040
  ```typescript
2093
- // Get first page and a cursor for the second page
2094
- const { data: workflowRuns, nextCursor } = await zapier.listWorkflowRuns({
2095
- workflow: "example-workflow",
2096
- });
2097
-
2098
- // Or iterate over all pages
2099
- for await (const page of zapier
2100
- .listWorkflowRuns({
2101
- workflow: "example-workflow",
2102
- })
2103
- .pages()) {
2104
- // Do something with each page
2105
- }
2106
-
2107
- // Or iterate over individual items across all pages
2108
- for await (const workflowRun of zapier
2109
- .listWorkflowRuns({
2041
+ const { data: agenticManagementConfig } =
2042
+ await zapier.getAgenticManagementConfig({
2110
2043
  workflow: "example-workflow",
2111
- })
2112
- .items()) {
2113
- // Do something with each workflowRun
2114
- }
2044
+ });
2115
2045
  ```
2116
2046
 
2117
- #### `listWorkflowVersions` 🧪 _experimental_
2047
+ #### `getAgenticManagementIntent` 🧪 _experimental_
2118
2048
 
2119
- List published versions for a workflow, newest first
2049
+ Read the intent recorded for one workflow version: the plain-language description of what that version of the workflow is meant to do.
2120
2050
 
2121
2051
  **Parameters:**
2122
2052
 
2123
- | Name | Type | Required | Default | Possible Values | Description |
2124
- | -------------- | -------- | -------- | ------- | --------------- | ------------------------------------------------- |
2125
- | `options` | `object` | ✅ | — | — | |
2126
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2127
- | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of versions per page (max 100) |
2128
- | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
2129
- | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total versions to return across all pages |
2053
+ | Name | Type | Required | Default | Possible Values | Description |
2054
+ | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2055
+ | `options` | `object` | ✅ | — | — | |
2056
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to read. |
2057
+ | ​ ↳ `version` | `string` | ❌ | — | — | The workflow version the intent belongs to. Each version stores its own intent, and a version never picks up the intent of another, so publishing a new version starts it with none. Omit this to use the workflow's current published version. |
2130
2058
 
2131
- **Returns:** `Promise<PaginatedResult<WorkflowVersionItem>>`
2059
+ **Returns:** `Promise<AgenticManagementIntentItem>`
2132
2060
 
2133
- | Name | Type | Required | Possible Values | Description |
2134
- | ---------------------------- | ---------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2135
- | `data[]` | `object[]` | ✅ | — | |
2136
- | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2137
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2138
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2139
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2140
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2141
- | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2142
- | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2143
- | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2144
- | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2145
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2061
+ | Name | Type | Required | Possible Values | Description |
2062
+ | ------------------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2063
+ | `data` | `object` | ✅ | — | |
2064
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow the intent belongs to. |
2065
+ | ​ ↳ `workflow_version_id` | `string` | ✅ | — | The version this read or write actually landed on, so you can tell which one answered when you omitted `version`. `null` only when you read a workflow that has nothing published yet. |
2066
+ | ​ ↳ `intent` | `string` | ✅ | — | The intent stored for this version, or `null` when this version has none. Intent is never carried over from another version. |
2067
+ | ​ ↳ `updated_at` | `string` | ❌ | — | When the intent was last written; `null` when never captured. |
2146
2068
 
2147
2069
  **Example:**
2148
2070
 
2149
2071
  ```typescript
2150
- // Get first page and a cursor for the second page
2151
- const { data: workflowVersions, nextCursor } =
2152
- await zapier.listWorkflowVersions({
2072
+ const { data: agenticManagementIntent } =
2073
+ await zapier.getAgenticManagementIntent({
2153
2074
  workflow: "example-workflow",
2154
2075
  });
2155
-
2156
- // Or iterate over all pages
2157
- for await (const page of zapier
2158
- .listWorkflowVersions({
2159
- workflow: "example-workflow",
2160
- })
2161
- .pages()) {
2162
- // Do something with each page
2163
- }
2164
-
2165
- // Or iterate over individual items across all pages
2166
- for await (const workflowVersion of zapier
2167
- .listWorkflowVersions({
2168
- workflow: "example-workflow",
2169
- })
2170
- .items()) {
2171
- // Do something with each workflowVersion
2172
- }
2173
2076
  ```
2174
2077
 
2175
- #### `listWorkflows` 🧪 _experimental_
2078
+ #### `getDurableRun` 🧪 _experimental_
2176
2079
 
2177
- List all active durable workflows for the authenticated account
2080
+ Get the full state of a run-once durable run, including its operations journal
2178
2081
 
2179
2082
  **Parameters:**
2180
2083
 
2181
- | Name | Type | Required | Default | Possible Values | Description |
2182
- | -------------- | -------- | -------- | ------- | --------------- | -------------------------------------------------- |
2183
- | `options` | `object` | ✅ | — | — | |
2184
- | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of workflows per page (max 100) |
2185
- | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total workflows to return across all pages |
2186
- | ​ ↳ `cursor` | `string` | ❌ | — | — | Cursor to start from for pagination |
2084
+ | Name | Type | Required | Default | Possible Values | Description |
2085
+ | --------- | -------- | -------- | ------- | --------------- | -------------- |
2086
+ | `options` | `object` | ✅ | — | — | |
2087
+ | ​ ↳ `run` | `string` | ✅ | — | — | Durable run ID |
2187
2088
 
2188
- **Returns:** `Promise<PaginatedResult<WorkflowItem>>`
2089
+ **Returns:** `Promise<DurableRunItem>`
2189
2090
 
2190
- | Name | Type | Required | Possible Values | Description |
2191
- | ------------------------- | ---------- | -------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2192
- | `data[]` | `object[]` | ✅ | — | |
2193
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
2194
- | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
2195
- | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
2196
- | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
2197
- | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
2198
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
2199
- | ​ ↳ `disabled_reason` | `string` | ❌ | `trigger_claim_failed` | Why the workflow is off, when system-disabled. Null when not system-disabled. |
2200
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
2201
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
2202
- | ​ ↳ `current_version_id` | `string` | ✅ | — | ID of the workflow version that runs handle. Null until a version is published. |
2203
- | ​ ↳ `triggers[]` | `object[]` | ✅ | — | Trigger configurations from the current version, with live claim status. Empty array when the workflow has no triggers. |
2204
- | ​   ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
2205
- | ​   ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
2206
- | ​   ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
2207
- | ​   ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
2208
- | ​   ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
2209
- | ​   ↳ `error` | `string` | ❌ | — | Failure reason for the latest claim. Present (non-null) only when status is 'failed'. |
2210
- | ​   ↳ `details` | `object` | ❌ | — | Trigger-type-specific metadata; shape varies by trigger type (e.g. `webhook_url` on catch-hook triggers). Null or absent when none applies. |
2211
- | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
2212
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
2213
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2091
+ | Name | Type | Required | Possible Values | Description |
2092
+ | ---------------- | --------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
2093
+ | `data` | `object` | ✅ | — | |
2094
+ | ​ ↳ `id` | `string` | ✅ | — | Run ID (UUID) |
2095
+ | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2096
+ | ​ ↳ `input` | `unknown` | ✅ | — | Input data passed to the run |
2097
+ | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
2098
+ | ​ ↳ `error` | `object` | ✅ | — | Structured error details when the run failed (null otherwise) |
2099
+ | ​ ↳ `execution` | `object` | ✅ | — | Linked execution, including the operations journal. Null while the run is still in `initialized` state. |
2100
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | When true, the run is visible only to the creating user; otherwise visible across the account. |
2101
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2102
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2214
2103
 
2215
2104
  **Example:**
2216
2105
 
2217
2106
  ```typescript
2218
- // Get first page and a cursor for the second page
2219
- const { data: workflows, nextCursor } = await zapier.listWorkflows();
2107
+ const { data: durableRun } = await zapier.getDurableRun({
2108
+ run: "example-run",
2109
+ });
2110
+ ```
2220
2111
 
2221
- // Or iterate over all pages
2222
- for await (const page of zapier.listWorkflows().pages()) {
2223
- // Do something with each page
2224
- }
2112
+ #### `getTriggerRun` 🧪 _experimental_
2225
2113
 
2226
- // Or iterate over individual items across all pages
2227
- for await (const workflow of zapier.listWorkflows().items()) {
2228
- // Do something with each workflow
2229
- }
2230
- ```
2231
-
2232
- #### `publishWorkflowDraft` 🧪 _experimental_
2233
-
2234
- Publish an open draft as a new immutable workflow version. Advances the workflow's live pointer and discards the draft — publish consumes it, so an open draft always means unpublished work. Continue editing by creating a new draft, which forks from the just-published version.
2114
+ Get the workflow run associated with a deployed workflow's trigger. Useful immediately after firing a trigger, when you have the trigger ID but not yet the run ID.
2235
2115
 
2236
2116
  **Parameters:**
2237
2117
 
2238
- | Name | Type | Required | Default | Possible Values | Description |
2239
- | ------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2240
- | `options` | `object` | ✅ | — | — | |
2241
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2242
- | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
2243
- | ​ ↳ `enabled` | `boolean` | ❌ | — | — | Set the workflow's enabled state as part of the publish. If omitted, the current enabled state is preserved. |
2244
- | ​ ↳ `draftRevision` | `number` | ❌ | — | — | Expected draft revision for optimistic concurrency. Pass the revision from the last read; the server rejects the publish with a conflict if the draft has changed since. Omit to skip the check. |
2245
- | ​ ↳ `manual` | `boolean` | ❌ | — | — | Declare this publish on-demand and triggerless, overriding the draft's stored intent for this publish only. Pass `manual: true` only when the draft has no trigger configured; the API rejects a draft with a trigger published as `manual: true` as a contradiction (400). |
2118
+ | Name | Type | Required | Default | Possible Values | Description |
2119
+ | ------------- | -------- | -------- | ------- | --------------- | ------------------- |
2120
+ | `options` | `object` | ✅ | — | — | |
2121
+ | ​ ↳ `trigger` | `string` | ✅ | — | — | Workflow trigger ID |
2246
2122
 
2247
- **Returns:** `Promise<PublishWorkflowDraftResponse>`
2123
+ **Returns:** `Promise<WorkflowRunItem>`
2248
2124
 
2249
- | Name | Type | Required | Possible Values | Description |
2250
- | ------------------------------ | -------- | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
2251
- | `data` | `object` | ✅ | — | |
2252
- | ​ ↳ `draft` | `object` | ✅ | — | The consumed draft: status is 'discarded' and discarded_at is set. base_version_id still records the version the draft was forked from. |
2253
- | ​   ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
2254
- | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2255
- | ​   ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
2256
- | ​   ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
2257
- | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2258
- | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
2259
- | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
2260
- | ​   ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
2261
- | ​   ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
2262
- | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
2263
- | ​   ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
2264
- | ​   ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
2265
- | ​   ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
2266
- | ​   ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
2267
- | ​   ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
2268
- | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
2269
- | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
2270
- | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
2271
- | ​ ↳ `version` | `object` | ✅ | — | The newly published immutable workflow version, now live. |
2272
- | ​   ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2273
- | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2274
- | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2275
- | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2276
- | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2277
- | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2278
- | ​   ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2279
- | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2280
- | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2281
- | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2125
+ | Name | Type | Required | Possible Values | Description |
2126
+ | ------------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
2127
+ | `data` | `object` | ✅ | — | |
2128
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow run ID (UUID) |
2129
+ | ​ ↳ `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
2130
+ | ​ ↳ `workflow_version_id` | `string` | ✅ | — | Workflow version the run is bound to |
2131
+ | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2132
+ | ​ ↳ `input` | `unknown` | ✅ | — | Input passed to the run |
2133
+ | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
2134
+ | ​ ↳ `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2135
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2136
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2282
2137
 
2283
2138
  **Example:**
2284
2139
 
2285
2140
  ```typescript
2286
- const { data: workflowVersion } = await zapier.publishWorkflowDraft({
2287
- workflow: "example-workflow",
2288
- draft: "example-draft",
2141
+ const { data: workflowRun } = await zapier.getTriggerRun({
2142
+ trigger: "example-trigger",
2289
2143
  });
2290
2144
  ```
2291
2145
 
2292
- #### `publishWorkflowVersion` 🧪 _experimental_
2146
+ #### `getWorkflow` 🧪 _experimental_
2293
2147
 
2294
- Publish a new version of a durable workflow. Enables the workflow by default.
2148
+ Get a durable workflow with its current version details and trigger claim status
2295
2149
 
2296
2150
  **Parameters:**
2297
2151
 
2298
- | Name | Type | Required | Default | Possible Values | Description |
2299
- | -------------------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2300
- | `options` | `object` | ✅ | — | — | |
2301
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2302
- | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Source files keyed by filename → contents |
2303
- | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies. A version of "latest" is resolved by the server for @zapier/zapier-durable and @zapier/zapier-sdk only; every other value, including a "latest" on any other package, is passed to the install as written. |
2304
- | ​ ↳ `zapierDurableVersion` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"), or "latest". Defaults to the server-configured version if omitted. "latest" is resolved by the server to the newest release old enough to clear the sandbox install age gate (24h) -- this is not npm's "latest" tag, which can point at a release too new to install. Ranges (^1.2.3, ~1.2) are rejected. |
2305
- | ​ ↳ `enabled` | `boolean` | ❌ | — | — | Enable the workflow after publishing. Defaults to true if omitted; pass false to publish without enabling. |
2306
- | ​ ↳ `ignoreOpenDrafts` | `boolean` | ❌ | — | — | Publish even though the workflow has open draft(s). Without this, the API rejects a direct publish with a 409 while any draft is open, since publishing the draft later would ship its stale content over this version. |
2307
- | ​ ↳ `connections` | `object` | ❌ | — | — | Map of connection aliases to Zapier connections used by the workflow. Pass `null` to clear an existing binding. |
2308
- | ​ ↳ `appVersions` | `object` | ❌ | — | — | Map of app keys to pinned app implementation/version used by the workflow. Pass `null` to clear an existing binding. |
2309
- | ​ ↳ `trigger` | `object` | ❌ | — | — | Trigger configuration. When provided, the workflow subscribes to a Zapier trigger; for an on-demand, triggerless workflow, omit this and pass `manual: true` instead. |
2310
- | ​   ↳ `selectedApi` | `string` | ❌ | — | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI'). Required when a trigger is configured. |
2311
- | ​   ↳ `action` | `string` | ✅ | — | — | Trigger action key (e.g. 'new_row') |
2312
- | ​   ↳ `authenticationId` | `string` | ❌ | — | — | Connection ID for the trigger source. Omit or pass null for no-auth triggers (e.g. Schedule by Zapier). |
2313
- | ​   ↳ `params` | `object` | ❌ | — | — | Trigger parameters as a JSON object |
2314
- | ​ ↳ `manual` | `boolean` | ❌ | — | — | Declare this an on-demand, triggerless workflow version. Pass `manual: true` only when omitting `trigger`; passing both is a contradiction the API rejects with a 400. |
2152
+ | Name | Type | Required | Default | Possible Values | Description |
2153
+ | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
2154
+ | `options` | `object` | ✅ | — | — | |
2155
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2315
2156
 
2316
- **Returns:** `Promise<WorkflowVersionItem>`
2157
+ **Returns:** `Promise<WorkflowItem>`
2317
2158
 
2318
- | Name | Type | Required | Possible Values | Description |
2319
- | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2320
- | `data` | `object` | ✅ | — | |
2321
- | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2322
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2323
- | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2324
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2325
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2326
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2327
- | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2328
- | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2329
- | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2330
- | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2159
+ | Name | Type | Required | Possible Values | Description |
2160
+ | ------------------------------ | ---------- | -------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2161
+ | `data` | `object` | ✅ | — | |
2162
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
2163
+ | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
2164
+ | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
2165
+ | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
2166
+ | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
2167
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
2168
+ | ​ ↳ `disabled_reason` | `string` | ❌ | `trigger_claim_failed` | Why the workflow is off, when system-disabled. Null when not system-disabled. Independent of per-trigger claim status: an enabled workflow can still have a failed trigger. |
2169
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
2170
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
2171
+ | ​ ↳ `current_version` | `object` | ❌ | — | The currently published version, if any. Absent for workflows with no version published yet. |
2172
+ | ​   ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2173
+ | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID |
2174
+ | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2175
+ | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2176
+ | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2177
+ | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2178
+ | ​   ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2179
+ | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2180
+ | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2181
+ | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2182
+ | ​ ↳ `triggers[]` | `object[]` | ✅ | — | Trigger configurations from the current version, with live claim status. Empty array when the workflow has no triggers. |
2183
+ | ​   ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
2184
+ | ​   ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
2185
+ | ​   ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
2186
+ | ​   ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
2187
+ | ​   ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
2188
+ | ​   ↳ `error` | `string` | ❌ | — | Failure reason for the latest claim. Present (non-null) only when status is 'failed'. |
2189
+ | ​   ↳ `details` | `object` | ❌ | — | Trigger-type-specific metadata; shape varies by trigger type (e.g. `webhook_url` on catch-hook triggers). Null or absent when none applies. |
2190
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
2191
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
2331
2192
 
2332
2193
  **Example:**
2333
2194
 
2334
2195
  ```typescript
2335
- const { data: workflowVersion } = await zapier.publishWorkflowVersion({
2196
+ const { data: workflow } = await zapier.getWorkflow({
2336
2197
  workflow: "example-workflow",
2337
- sourceFiles: {},
2338
2198
  });
2339
2199
  ```
2340
2200
 
2341
- #### `runDurable` 🧪 _experimental_
2201
+ #### `getWorkflowDraft` 🧪 _experimental_
2342
2202
 
2343
- Run a workflow's complete source-files map as a run-once durable run on code-substrate-runner (no deployed workflow required). Send every file the workflow needs, not only its entry point. Returns the run ID immediately; poll via getDurableRun for terminal status.
2203
+ Get full details of a workflow draft including source files
2344
2204
 
2345
2205
  **Parameters:**
2346
2206
 
2347
- | Name | Type | Required | Default | Possible Values | Description |
2348
- | -------------------------- | ---------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2349
- | `options` | `object` | ✅ | — | — | |
2350
- | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Source files keyed by filename → contents |
2351
- | ​ ↳ `input` | `unknown` | ❌ | — | — | Input data passed to the run. Accepts any JSON value, or its JSON-string encoding. |
2352
- | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies. A version of "latest" is resolved by the server for @zapier/zapier-durable and @zapier/zapier-sdk only; every other value, including a "latest" on any other package, is passed to the install as written. |
2353
- | ​ ↳ `zapierDurableVersion` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"), or "latest". Defaults to the server-configured version if omitted. "latest" is resolved by the server to the newest release old enough to clear the sandbox install age gate (24h) -- this is not npm's "latest" tag, which can point at a release too new to install. Ranges (^1.2.3, ~1.2) are rejected. |
2354
- | ​ ↳ `connections` | `object` | ❌ | — | — | Named connection aliases. Maps each alias to an object holding its Zapier connection ID, e.g. `{ "slack": { "connectionId": "123" } }`. |
2355
- | ​ ↳ `appVersions` | `object` | ❌ | — | — | Pinned app versions. Maps app keys (slugs) to implementation names and versions. |
2356
- | ​ ↳ `private` | `boolean` | ❌ | — | — | Only the creating user can see the run (default false) |
2357
- | ​ ↳ `notifications[]` | `object[]` | ❌ | — | — | Webhook subscribers for run lifecycle events. Each entry specifies a URL and the events it subscribes to. |
2358
- | ​   ↳ `type` | `string` | ❌ | — | `webhook` | Notification transport. Webhook is the only supported type. |
2359
- | ​   ↳ `url` | `string` | ✅ | — | — | URL to POST event notifications to. Payload is `{run_id, event}`. |
2360
- | ​   ↳ `max_retries` | `number` | ❌ | — | — | Max delivery attempts with exponential backoff. Defaults to 3 server-side. |
2361
- | ​   ↳ `events` | `array` | ✅ | — | — | One or more lifecycle events to subscribe this URL to. |
2207
+ | Name | Type | Required | Default | Possible Values | Description |
2208
+ | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
2209
+ | `options` | `object` | ✅ | — | — | |
2210
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2211
+ | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
2362
2212
 
2363
- **Returns:** `Promise<DurableRunItem>`
2213
+ **Returns:** `Promise<WorkflowDraftItem>`
2364
2214
 
2365
- | Name | Type | Required | Possible Values | Description |
2366
- | ---------------- | --------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
2367
- | `data` | `object` | ✅ | — | |
2368
- | ​ ↳ `id` | `string` | ✅ | — | Run ID (UUID) — server-generated, time-sortable |
2369
- | ​ ↳ `status` | `string` | ✅ | `initialized` | Always `initialized` on creation. Poll via getDurableRun to observe the run advancing to `started` / `finished` / `failed` / `cancelled`. |
2370
- | ​ ↳ `is_private` | `boolean` | ✅ | — | When true, the run is visible only to the creating user; otherwise visible across the account. |
2371
- | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2215
+ | Name | Type | Required | Possible Values | Description |
2216
+ | ---------------------------- | -------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
2217
+ | `data` | `object` | ✅ | — | |
2218
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
2219
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2220
+ | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
2221
+ | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
2222
+ | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2223
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
2224
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
2225
+ | ​ ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
2226
+ | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
2227
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
2228
+ | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
2229
+ | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
2230
+ | ​ ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
2231
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
2232
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
2233
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
2234
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
2235
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
2372
2236
 
2373
2237
  **Example:**
2374
2238
 
2375
2239
  ```typescript
2376
- const { data: durableRun } = await zapier.runDurable({
2377
- sourceFiles: {},
2240
+ const { data: workflowDraft } = await zapier.getWorkflowDraft({
2241
+ workflow: "example-workflow",
2242
+ draft: "example-draft",
2378
2243
  });
2379
2244
  ```
2380
2245
 
2381
- #### `runWorkflowDraft` 🧪 _experimental_
2246
+ #### `getWorkflowRun` 🧪 _experimental_
2382
2247
 
2383
- Launch a draft test run: execute the draft's current source without publishing it. The draft's payload is snapshotted onto the run at creation, so later edits (or discarding the draft) never change what the run executed. Draft runs are free (not task-charged) and rate limited per user. The run is accepted asynchronously — it comes back `initialized`; follow it with `getWorkflowRun`, or list it via `listWorkflowRuns` with `kind: "draft"`.
2248
+ Get the current state of a workflow run — a live run of a published workflow version, or a draft run launched via `runWorkflowDraft` (the `kind` field says which)
2384
2249
 
2385
2250
  **Parameters:**
2386
2251
 
2387
- | Name | Type | Required | Default | Possible Values | Description |
2388
- | ------------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2389
- | `options` | `object` | ✅ | — | — | |
2390
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2391
- | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
2392
- | ​ ↳ `draftRevision` | `number` | ✅ | — | — | The draft revision you intend to run, from the last read of the draft. The server rejects the run with a conflict if the draft has changed since. The upstream API treats this check as optional; the SDK requires it so a test run can never silently execute source the caller has already replaced. |
2393
- | ​ ↳ `input` | `unknown` | ❌ | — | — | Input data passed to the workflow. Accepts any JSON value, or its JSON-string encoding. Omit for a workflow that takes no input. |
2394
-
2395
- **Returns:** `Promise<RunWorkflowDraftResponse>`
2396
-
2397
- | Name | Type | Required | Possible Values | Description |
2398
- | ----------------------- | --------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
2399
- | `data` | `object` | ✅ | — | |
2400
- | ​ ↳ `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2401
- | ​ ↳ `kind` | `string` | ✅ | `draft` | A run launched from a workflow draft. |
2402
- | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow this run belongs to |
2403
- | ​ ↳ `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Usually still null in this response — the run is accepted and launched in the background. |
2404
- | ​ ↳ `workflow_draft_id` | `string` | ✅ | — | The draft this run was launched from. Becomes null once that draft is deleted — the run outlives its draft. |
2405
- | ​ ↳ `draft_revision` | `number` | ✅ | — | The draft's revision at the moment this run was created. |
2406
- | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2407
- | ​ ↳ `input` | `unknown` | ✅ | — | Input passed to the run |
2408
- | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
2409
- | ​ ↳ `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2410
- | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2411
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2252
+ | Name | Type | Required | Default | Possible Values | Description |
2253
+ | -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------- |
2254
+ | `options` | `object` | ✅ | — | — | |
2255
+ | ​ ↳ `workflow` | `string` | ❌ | — | — | Parent workflow ID — used only to scope the CLI run-id picker; ignored by the API call. |
2256
+ | ​ ↳ `run` | `string` | ✅ | — | — | Workflow run ID |
2412
2257
 
2413
- **Example:**
2258
+ **Returns:** `Promise<WorkflowRunItem>`
2414
2259
 
2415
- ```typescript
2416
- const { data: workflowRun } = await zapier.runWorkflowDraft({
2417
- workflow: "example-workflow",
2418
- draft: "example-draft",
2419
- draftRevision: 100,
2420
- });
2421
- ```
2260
+ | Name | Type | Required | Possible Values | Description |
2261
+ | ------ | -------- | -------- | --------------- | -------------------------------------------------- |
2262
+ | `data` | `object` | ✅ | — | One of the variants below, distinguished by `kind` |
2422
2263
 
2423
- #### `triggerWorkflow` 🧪 _experimental_
2264
+ **When `kind` is `"live"`:**
2424
2265
 
2425
- Look up a workflow's trigger URL and fire it manually, as the authenticated account.
2426
-
2427
- **Parameters:**
2428
-
2429
- | Name | Type | Required | Default | Possible Values | Description |
2430
- | -------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2431
- | `options` | `object` | ✅ | — | — | |
2432
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2433
- | ​ ↳ `input` | `unknown` | ❌ | — | — | JSON payload delivered as the trigger body. Accepts any JSON value, or its JSON-string encoding. Sent as `application/json`; omit to fire with an empty body. |
2266
+ | Name | Type | Required | Possible Values | Description |
2267
+ | --------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
2268
+ | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2269
+ | `workflow_id` | `string` | ✅ | — | The workflow this run belongs to |
2270
+ | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
2271
+ | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2272
+ | `input` | `unknown` | ✅ | — | Input passed to the run |
2273
+ | `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
2274
+ | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2275
+ | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2276
+ | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2277
+ | `kind` | `string` | ✅ | `live` | A run of a published workflow version. |
2278
+ | `trigger_id` | `string` | ✅ | — | ID of the trigger that fired this run. Null for runs created without a trigger. |
2279
+ | `workflow_version_id` | `string` | ✅ | — | Workflow version the run is bound to. Null in rare edge cases. |
2434
2280
 
2435
- **Returns:** `Promise<WorkflowRunItem>`
2281
+ **When `kind` is `"draft"`:**
2436
2282
 
2437
- | Name | Type | Required | Possible Values | Description |
2438
- | ----------------- | -------- | -------- | --------------- | ---------------------------------------- |
2439
- | `data` | `object` | ✅ | — | |
2440
- | ​ ↳ `id` | `string` | ✅ | — | Trigger ID (UUID) |
2441
- | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow that was triggered (UUID) |
2442
- | ​ ↳ `created_at` | `string` | ✅ | — | When the trigger was received (ISO-8601) |
2283
+ | Name | Type | Required | Possible Values | Description |
2284
+ | ------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2285
+ | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2286
+ | `workflow_id` | `string` | ✅ | — | The workflow this run belongs to |
2287
+ | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
2288
+ | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2289
+ | `input` | `unknown` | ✅ | — | Input passed to the run |
2290
+ | `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
2291
+ | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2292
+ | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2293
+ | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2294
+ | `kind` | `string` | ✅ | `draft` | A run launched from a workflow draft via `runWorkflowDraft`. |
2295
+ | `workflow_draft_id` | `string` | ✅ | — | The draft this run was launched from. Null once that draft has been deleted (the run outlives its draft). |
2296
+ | `draft_revision` | `number` | ✅ | — | The draft's revision at the moment this run was created. Compare against the draft's current `draft_revision` to tell whether the run still reflects the draft as it now stands. |
2443
2297
 
2444
2298
  **Example:**
2445
2299
 
2446
2300
  ```typescript
2447
- const { data: workflowRun } = await zapier.triggerWorkflow({
2448
- workflow: "example-workflow",
2301
+ const { data: workflowRun } = await zapier.getWorkflowRun({
2302
+ run: "example-run",
2449
2303
  });
2450
2304
  ```
2451
2305
 
2452
- #### `updateAgenticManagementConfig` 🧪 _experimental_
2306
+ #### `getWorkflowVersion` 🧪 _experimental_
2453
2307
 
2454
- Change the modes a workflow runs, whether fixes are applied without approval, or both. A `modes` list replaces the whole current set rather than adding to it.
2308
+ Get full details of a workflow version including source files
2455
2309
 
2456
2310
  **Parameters:**
2457
2311
 
2458
- | Name | Type | Required | Default | Possible Values | Description |
2459
- | ----------------- | --------- | -------- | ------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2460
- | `options` | `object` | ✅ | — | — | |
2461
- | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to update. |
2462
- | ​ ↳ `modes` | `array` | ❌ | — | — | The modes to run. The list you pass replaces the whole current set in one step; it is not added to what is already active. Omit it to leave the active modes as they are. A mode is what Agentic Management watches for and what it changes in response. `heal` monitors runs for errors and, when something breaks, diagnoses the cause and drafts and tests a fix; it is the mode a workflow gets by default. `expand` grows what the workflow covers: it reviews runs that succeeded without actually doing anything — a lookup that matched nothing, a filter that passed no items, a trigger payload no branch handles — and proposes a new branch or step to handle that case, rather than rewriting the ones that already work. `harden` watches the AI steps: when an AI step keeps doing the same work the same way, it converts that step into fixed code, so the workflow runs faster, costs less, and behaves the same way every time. Modes stack — each one you name runs alongside the others, and a mode you leave out does nothing, so a workflow on `expand` alone does not repair failed runs. Whether a change goes live on its own or waits for someone to approve it is `autoApprove`, not the mode. |
2463
- | ​ ↳ `autoApprove` | `boolean` | ❌ | — | — | Apply the fixes Agentic Management proposes without asking first. Set it to false and each fix waits for someone to approve it before anything changes. Omit it to leave the current setting alone. |
2312
+ | Name | Type | Required | Default | Possible Values | Description |
2313
+ | -------------- | -------- | -------- | ------- | --------------- | ------------------- |
2314
+ | `options` | `object` | ✅ | — | — | |
2315
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2316
+ | ​ ↳ `version` | `string` | ✅ | — | — | Workflow version ID |
2464
2317
 
2465
- **Returns:** `Promise<AgenticManagementConfigItem>`
2318
+ **Returns:** `Promise<WorkflowVersionItem>`
2466
2319
 
2467
- | Name | Type | Required | Possible Values | Description |
2468
- | ------------------ | --------- | -------- | --------------- | ------------------------------------------------------------- |
2469
- | `data` | `object` | ✅ | — | |
2470
- | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow whose config was updated. |
2471
- | ​ ↳ `modes` | `array` | ✅ | — | The modes the workflow runs after this update. |
2472
- | ​ ↳ `auto_approve` | `boolean` | ✅ | — | Whether fixes are applied without approval after this update. |
2320
+ | Name | Type | Required | Possible Values | Description |
2321
+ | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2322
+ | `data` | `object` | ✅ | — | |
2323
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2324
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2325
+ | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2326
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2327
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2328
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2329
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2330
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2331
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2332
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2473
2333
 
2474
2334
  **Example:**
2475
2335
 
2476
2336
  ```typescript
2477
- const { data: agenticManagementConfig } =
2478
- await zapier.updateAgenticManagementConfig({
2479
- workflow: "example-workflow",
2480
- });
2337
+ const { data: workflowVersion } = await zapier.getWorkflowVersion({
2338
+ workflow: "example-workflow",
2339
+ version: "example-version",
2340
+ });
2481
2341
  ```
2482
2342
 
2483
- #### `updateAgenticManagementIntent` 🧪 _experimental_
2343
+ #### `importWorkflow` 🧪 _experimental_
2484
2344
 
2485
- Record what one workflow version is meant to do. Writing again for the same version replaces the text already stored, so there is no separate create and update.
2345
+ Convert an existing Zap into a durable workflow. Transforms the Zap's latest published version (falling back to its draft only when the Zap has never been published) and puts the resulting source in an open draft. The workflow is created disabled with no published version, so publish the draft to make it live. The original Zap is untouched and keeps running.
2486
2346
 
2487
2347
  **Parameters:**
2488
2348
 
2489
- | Name | Type | Required | Default | Possible Values | Description |
2490
- | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2491
- | `options` | `object` | ✅ | — | — | |
2492
- | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to write to. |
2493
- | ​ ↳ `intent` | `string` | ✅ | — | — | What this version of the workflow is for, in your own words: the outcome it produces, what sets it off, and anything that must always hold true. Plain prose, not code. |
2494
- | ​ ↳ `version` | `string` | ❌ | — | — | The workflow version the intent belongs to. Each version stores its own intent, and a version never picks up the intent of another, so publishing a new version starts it with none. Omit this to use the workflow's current published version. |
2349
+ | Name | Type | Required | Default | Possible Values | Description |
2350
+ | ------------- | --------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
2351
+ | `options` | `object` | ✅ | — | — | |
2352
+ | ​ ↳ `zap` | `string` | ✅ | — | — | ID of the Zap to import. Must be owned by the requesting user. Recorded on the created workflow as source_zap_id. |
2353
+ | ​ ↳ `name` | `string` | ❌ | — | — | Name for the created workflow. Defaults to a kebab-cased form of the Zap's title, or "imported-workflow" when the Zap has no title. |
2354
+ | ​ ↳ `private` | `boolean` | ❌ | — | — | Restrict the created workflow to the creating user. Defaults to false, which makes it account-visible. |
2495
2355
 
2496
- **Returns:** `Promise<AgenticManagementIntentItem>`
2356
+ **Returns:** `Promise<ImportWorkflowResponse>`
2497
2357
 
2498
- | Name | Type | Required | Possible Values | Description |
2499
- | ------------------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2500
- | `data` | `object` | ✅ | — | |
2501
- | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow the intent belongs to. |
2502
- | ​ ↳ `workflow_version_id` | `string` | ✅ | — | The version this read or write actually landed on, so you can tell which one answered when you omitted `version`. `null` only when you read a workflow that has nothing published yet. |
2503
- | ​ ↳ `intent` | `string` | ✅ | — | The intent stored for this version, or `null` when this version has none. Intent is never carried over from another version. |
2504
- | ​ ↳ `updated_at` | `string` | ❌ | — | When the intent was last written; `null` when never captured. |
2358
+ | Name | Type | Required | Possible Values | Description |
2359
+ | ------------------------------ | ---------- | -------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2360
+ | `data` | `object` | ✅ | — | |
2361
+ | ​ ↳ `workflow` | `object` | ✅ | — | The created workflow. Disabled, with no published version, and source_zap_id set to the imported Zap. |
2362
+ | ​   ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
2363
+ | ​   ↳ `name` | `string` | ✅ | — | Workflow name |
2364
+ | ​   ↳ `description` | `string` | ❌ | — | Optional workflow description (null if unset) |
2365
+ | ​   ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
2366
+ | ​   ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
2367
+ | ​   ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow accepts triggers. An import always lands disabled. |
2368
+ | ​   ↳ `disabled_reason` | `string` | ❌ | `trigger_claim_failed` | Why the workflow is off, when system-disabled. |
2369
+ | ​   ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
2370
+ | ​   ↳ `source_zap_id` | `string` | ❌ | — | The Zap this workflow was imported from. |
2371
+ | ​   ↳ `created_by_user_id` | `string` | ✅ | — | |
2372
+ | ​   ↳ `updated_by_user_id` | `string` | ❌ | — | |
2373
+ | ​   ↳ `current_version_id` | `string` | ❌ | — | Null on a fresh import, which has no published version yet. |
2374
+ | ​   ↳ `triggers[]` | `object[]` | ✅ | — | Empty on a fresh import, which has no published version yet. |
2375
+ | ​     ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
2376
+ | ​     ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
2377
+ | ​     ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
2378
+ | ​     ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
2379
+ | ​     ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
2380
+ | ​     ↳ `error` | `string` | ❌ | — | Failure reason for the latest claim. Present (non-null) only when status is 'failed'. |
2381
+ | ​     ↳ `details` | `object` | ❌ | — | Trigger-type-specific metadata; shape varies by trigger type (e.g. `webhook_url` on catch-hook triggers). Null or absent when none applies. |
2382
+ | ​   ↳ `created_at` | `string` | ✅ | — | |
2383
+ | ​   ↳ `updated_at` | `string` | ❌ | — | |
2384
+ | ​ ↳ `draft` | `object` | ✅ | — | The open draft holding the transformed source. |
2385
+ | ​   ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
2386
+ | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2387
+ | ​   ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
2388
+ | ​   ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
2389
+ | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2390
+ | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
2391
+ | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
2392
+ | ​   ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
2393
+ | ​   ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
2394
+ | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
2395
+ | ​   ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
2396
+ | ​   ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
2397
+ | ​   ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
2398
+ | ​   ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
2399
+ | ​   ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
2400
+ | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
2401
+ | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
2402
+ | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
2403
+ | ​ ↳ `issues[]` | `object[]` | ✅ | — | Blocking and non-blocking translation issues from the transform, passed through unchanged. Blocking issues do not prevent draft creation; they must be resolved before the draft will publish. |
2404
+ | ​   ↳ `line` | `number` | ✅ | — | 1-based line in the generated source the issue relates to, or 0 when not line-specific. |
2405
+ | ​   ↳ `column` | `number` | ✅ | — | 1-based column, or 0 when not column-specific. |
2406
+ | ​   ↳ `node_kind` | `string` | ✅ | — | Category of the issue, used to group and message them, e.g. "invalid-connection-id", "DelayStep", "app-version-conflict". |
2407
+ | ​   ↳ `step_name` | `string` | ❌ | — | ZDL step id or name the issue originated from, when known. |
2408
+ | ​   ↳ `message` | `string` | ✅ | — | Human-readable description of the issue. |
2409
+ | ​   ↳ `blocking` | `boolean` | ✅ | — | Whether the issue must be resolved before the draft can be published. Computed server-side, so callers do not re-derive it. A blocking issue does not prevent the draft being created. |
2505
2410
 
2506
2411
  **Example:**
2507
2412
 
2508
2413
  ```typescript
2509
- const { data: agenticManagementIntent } =
2510
- await zapier.updateAgenticManagementIntent({
2511
- workflow: "example-workflow",
2512
- intent: "example-intent",
2513
- });
2414
+ const { data: workflow } = await zapier.importWorkflow({
2415
+ zap: "example-zap",
2416
+ });
2514
2417
  ```
2515
2418
 
2516
- #### `updateWorkflow` 🧪 _experimental_
2419
+ #### `listDurableRuns` 🧪 _experimental_
2517
2420
 
2518
- Update a durable workflow's name and/or description
2421
+ List run-once durable runs for the authenticated account, newest first
2519
2422
 
2520
2423
  **Parameters:**
2521
2424
 
2522
- | Name | Type | Required | Default | Possible Values | Description |
2523
- | ----------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------- |
2524
- | `options` | `object` | ✅ | — | — | |
2525
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2526
- | ​ ↳ `name` | `string` | ❌ | — | — | New name for the workflow |
2527
- | ​ ↳ `description` | `string` | ❌ | — | — | New description for the workflow (pass null to clear) |
2425
+ | Name | Type | Required | Default | Possible Values | Description |
2426
+ | -------------- | -------- | -------- | ------- | --------------- | ---------------------------------------------- |
2427
+ | `options` | `object` | ✅ | — | — | |
2428
+ | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of runs per page (max 100) |
2429
+ | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
2430
+ | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total items to return across all pages |
2528
2431
 
2529
- **Returns:** `Promise<WorkflowItem>`
2432
+ **Returns:** `Promise<PaginatedResult<DurableRunItem>>`
2530
2433
 
2531
- | Name | Type | Required | Possible Values | Description |
2532
- | ------------------------ | --------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2533
- | `data` | `object` | ✅ | — | |
2534
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
2535
- | ​ ↳ `name` | `string` | ✅ | — | Workflow name (post-update) |
2536
- | ​ ↳ `description` | `string` | ✅ | — | Workflow description, post-update (null if unset) |
2537
- | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
2538
- | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
2539
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
2540
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
2541
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
2542
- | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
2543
- | ​ ↳ `updated_at` | `string` | ✅ | — | When this update was applied (ISO-8601) |
2434
+ | Name | Type | Required | Possible Values | Description |
2435
+ | ------------------ | ---------- | -------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
2436
+ | `data[]` | `object[]` | ✅ | — | |
2437
+ | ​ ↳ `id` | `string` | ✅ | — | Run ID (UUID) |
2438
+ | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2439
+ | ​ ↳ `input` | `unknown` | ✅ | — | Input data passed to the run |
2440
+ | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
2441
+ | ​ ↳ `error` | `object` | ✅ | — | Structured error details when the run failed (null otherwise) |
2442
+ | ​ ↳ `execution_id` | `string` | ✅ | — | Linked execution ID. Null until the run leaves the `initialized` state. |
2443
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | When true, the run is visible only to the creating user; otherwise visible across the account. |
2444
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2445
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2446
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2544
2447
 
2545
2448
  **Example:**
2546
2449
 
2547
2450
  ```typescript
2548
- const { data: workflow } = await zapier.updateWorkflow({
2549
- workflow: "example-workflow",
2550
- });
2451
+ // Get first page and a cursor for the second page
2452
+ const { data: durableRuns, nextCursor } = await zapier.listDurableRuns();
2453
+
2454
+ // Or iterate over all pages
2455
+ for await (const page of zapier.listDurableRuns().pages()) {
2456
+ // Do something with each page
2457
+ }
2458
+
2459
+ // Or iterate over individual items across all pages
2460
+ for await (const durableRun of zapier.listDurableRuns().items()) {
2461
+ // Do something with each durableRun
2462
+ }
2551
2463
  ```
2552
2464
 
2553
- #### `updateWorkflowDraft` 🧪 _experimental_
2465
+ #### `listWorkflowDrafts` 🧪 _experimental_
2554
2466
 
2555
- Update (autosave) an open workflow draft
2467
+ List drafts for a workflow, most recently edited first (open drafts by default)
2556
2468
 
2557
2469
  **Parameters:**
2558
2470
 
2559
- | Name | Type | Required | Default | Possible Values | Description |
2560
- | -------------------------- | --------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2561
- | `options` | `object` | ✅ | — | — | |
2562
- | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2563
- | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
2564
- | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Source files keyed by filename → contents |
2565
- | ​ ↳ `zapierDurableVersion` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"), or "latest". Leaves the stored pin unchanged if omitted. A draft stores what you pass verbatim, so "latest" is recorded as-is and resolved to an exact version when the draft is published -- reading the draft back shows "latest", not a version. Ranges (^1.2.3, ~1.2) are rejected at publish. |
2566
- | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies. A version of "latest" is resolved by the server for @zapier/zapier-durable and @zapier/zapier-sdk only; every other value, including a "latest" on any other package, is passed to the install as written. |
2567
- | ​ ↳ `draftRevision` | `number` | ❌ | — | — | Expected draft revision for optimistic concurrency. Pass the revision from the last read; the server rejects the save with a conflict if the draft has changed since. Omit to skip the check. |
2568
- | ​ ↳ `trigger` | `object` | ❌ | — | — | Trigger configuration. Omit to leave the stored trigger unchanged, pass null to clear it, or pass an object to replace it; for an on-demand, triggerless workflow, clear this and pass `manual: true` instead. |
2569
- | ​ ↳ `connections` | `object` | ❌ | — | — | Map of connection aliases to Zapier connections used by the workflow. Pass `null` to clear an existing binding. |
2570
- | ​ ↳ `appVersions` | `object` | ❌ | — | — | Map of app keys to pinned app implementation/version used by the workflow. Pass `null` to clear an existing binding. |
2571
- | ​ ↳ `manual` | `boolean` | ❌ | — | — | Declare this draft on-demand and triggerless. Pass `manual: true` only when omitting `trigger` (or clearing it with `trigger: null`); passing both is a contradiction the API rejects with a 400. Setting a `trigger` later clears a previously stored `manual: true`. |
2572
-
2573
- **Returns:** `Promise<WorkflowDraftItem>`
2471
+ | Name | Type | Required | Default | Possible Values | Description |
2472
+ | -------------- | -------- | -------- | ------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2473
+ | `options` | `object` | ✅ | — | — | |
2474
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2475
+ | ​ ↳ `status` | `string` | ❌ | — | `open`, `discarded` | Filter by draft status (server default: open) |
2476
+ | ​ ↳ `slug` | `string` | ❌ | — | — | Filter by exact slug match. Slugs are not unique, so this returns every draft with this slug matching the selected status, ordered by most recent activity and paginated |
2477
+ | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of drafts per page (max 100) |
2478
+ | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
2479
+ | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total drafts to return across all pages |
2574
2480
 
2575
- | Name | Type | Required | Possible Values | Description |
2576
- | ---------------------------- | -------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
2577
- | `data` | `object` | ✅ | — | |
2578
- | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
2579
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2580
- | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
2581
- | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
2582
- | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2583
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
2584
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
2585
- | ​ ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
2586
- | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
2587
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
2588
- | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
2589
- | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
2590
- | ​ ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
2591
- | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
2592
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
2593
- | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
2594
- | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
2595
- | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
2481
+ **Returns:** `Promise<PaginatedResult<WorkflowDraftItem>>`
2482
+
2483
+ | Name | Type | Required | Possible Values | Description |
2484
+ | ---------------------------- | ---------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
2485
+ | `data[]` | `object[]` | ✅ | — | |
2486
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
2487
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2488
+ | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
2489
+ | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
2490
+ | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
2491
+ | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
2492
+ | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
2493
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
2494
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2596
2495
 
2597
2496
  **Example:**
2598
2497
 
2599
2498
  ```typescript
2600
- const { data: workflowDraft } = await zapier.updateWorkflowDraft({
2499
+ // Get first page and a cursor for the second page
2500
+ const { data: workflowDrafts, nextCursor } = await zapier.listWorkflowDrafts({
2601
2501
  workflow: "example-workflow",
2602
- draft: "example-draft",
2603
- sourceFiles: {},
2604
2502
  });
2503
+
2504
+ // Or iterate over all pages
2505
+ for await (const page of zapier
2506
+ .listWorkflowDrafts({
2507
+ workflow: "example-workflow",
2508
+ })
2509
+ .pages()) {
2510
+ // Do something with each page
2511
+ }
2512
+
2513
+ // Or iterate over individual items across all pages
2514
+ for await (const workflowDraft of zapier
2515
+ .listWorkflowDrafts({
2516
+ workflow: "example-workflow",
2517
+ })
2518
+ .items()) {
2519
+ // Do something with each workflowDraft
2520
+ }
2605
2521
  ```
2606
2522
 
2607
- #### `validateWorkflow` 🧪 _experimental_
2523
+ #### `listWorkflowRuns` 🧪 _experimental_
2608
2524
 
2609
- Validate durable workflow source without publishing it. Returns source diagnostics; issue kinds are extensible and may be unfamiliar to the client.
2525
+ List workflow runs for a specific workflow, newest first. Live runs (of published versions) and draft runs share the one list; pass `kind` to narrow it to one.
2610
2526
 
2611
2527
  **Parameters:**
2612
2528
 
2613
- | Name | Type | Required | Default | Possible Values | Description |
2614
- | -------------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------- |
2615
- | `options` | `object` | ✅ | — | — | |
2616
- | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Exact TypeScript sources keyed by absolute logical path. |
2617
- | ​ ↳ `entrypointFile` | `string` | ❌ | — | — | Absolute logical path of the entry file in sourceFiles. Defaults to /workflow.ts. |
2529
+ | Name | Type | Required | Default | Possible Values | Description |
2530
+ | -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------- |
2531
+ | `options` | `object` | ✅ | — | — | |
2532
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2533
+ | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of runs per page (max 100) |
2534
+ | ​ ↳ `kind` | `string` | ❌ | — | `live`, `draft` | Return only runs of this kind. Omit for both, interleaved by recency. |
2535
+ | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
2536
+ | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total runs to return across all pages |
2618
2537
 
2619
- **Returns:** `Promise<WorkflowValidationItem>`
2538
+ **Returns:** `Promise<PaginatedResult<WorkflowRunItem>>`
2620
2539
 
2621
- | Name | Type | Required | Possible Values | Description |
2622
- | ---------------------- | ---------- | -------- | ---------------------------------- | ----------------------------------------------------------------------------------- |
2623
- | `data` | `object` | ✅ | — | |
2624
- | ​ ↳ `issues[]` | `object[]` | ✅ | — | Source diagnostics, or an empty array when validation passes. |
2625
- | ​   ↳ `kind` | `string` | ✅ | — | Extensible diagnostic category; clients must accept unfamiliar values. |
2626
- | ​   ↳ `message` | `string` | ✅ | — | Safe human-readable explanation. |
2627
- | ​   ↳ `severity` | `string` | ✅ | `error`, `warning`, `info`, `hint` | Diagnostic severity. |
2628
- | ​   ↳ `suggestion` | `string` | ❌ | — | Actionable fix hint. |
2629
- | ​   ↳ `source` | `object` | ❌ | — | Affected source location. |
2630
- | ​     ↳ `file_id` | `string` | ✅ | — | Source file containing the diagnostic. |
2631
- | ​     ↳ `start_line` | `number` | ✅ | — | Inclusive 1-based start line. |
2632
- | ​     ↳ `start_column` | `number` | ✅ | — | Inclusive 1-based start column. |
2633
- | ​     ↳ `end_line` | `number` | ✅ | — | Inclusive 1-based end line. |
2634
- | ​     ↳ `end_column` | `number` | ✅ | — | Inclusive 1-based end column. |
2635
- | ​   ↳ `source_excerpt` | `string` | ❌ | — | Source text the diagnostic was raised against, truncated to 240 characters. |
2636
- | ​   ↳ `syntax_kind` | `string` | ❌ | — | TypeScript AST node kind the diagnostic was raised against (e.g. `CallExpression`). |
2540
+ | Name | Type | Required | Possible Values | Description |
2541
+ | ------------ | ---------- | -------- | --------------- | -------------------------------------------------------------- |
2542
+ | `data[]` | `object[]` | ✅ | — | One of the variants below, distinguished by `kind` |
2543
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2544
+
2545
+ **When `kind` is `"live"`:**
2546
+
2547
+ | Name | Type | Required | Possible Values | Description |
2548
+ | --------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
2549
+ | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2550
+ | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
2551
+ | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2552
+ | `input` | `unknown` | ✅ | — | Input passed to the run |
2553
+ | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2554
+ | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2555
+ | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2556
+ | `kind` | `string` | ✅ | `live` | A run of a published workflow version. |
2557
+ | `trigger_id` | `string` | ✅ | — | ID of the trigger that fired this run. Null for runs created without a trigger. |
2558
+ | `workflow_version_id` | `string` | ✅ | — | Workflow version the run is bound to. Null in rare edge cases. |
2559
+
2560
+ **When `kind` is `"draft"`:**
2561
+
2562
+ | Name | Type | Required | Possible Values | Description |
2563
+ | ------------------- | --------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
2564
+ | `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2565
+ | `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Null until the durable run is created. |
2566
+ | `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2567
+ | `input` | `unknown` | ✅ | — | Input passed to the run |
2568
+ | `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2569
+ | `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2570
+ | `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2571
+ | `kind` | `string` | ✅ | `draft` | A run launched from a workflow draft via `runWorkflowDraft`. |
2572
+ | `workflow_draft_id` | `string` | ✅ | — | The draft this run was launched from. Null once that draft has been deleted (the run outlives its draft). |
2573
+ | `draft_revision` | `number` | ✅ | — | The draft's revision at the moment this run was created. |
2637
2574
 
2638
2575
  **Example:**
2639
2576
 
2640
2577
  ```typescript
2641
- const { data: workflowValidation } = await zapier.validateWorkflow({
2642
- sourceFiles: {
2643
- "/workflow.ts":
2644
- 'import { defineDurable } from "@zapier/zapier-durable"; export default defineDurable("hello-world", async (ctx, input) => { return ctx.step("greet", async () => "Hello, world!"); });',
2645
- },
2578
+ // Get first page and a cursor for the second page
2579
+ const { data: workflowRuns, nextCursor } = await zapier.listWorkflowRuns({
2580
+ workflow: "example-workflow",
2646
2581
  });
2582
+
2583
+ // Or iterate over all pages
2584
+ for await (const page of zapier
2585
+ .listWorkflowRuns({
2586
+ workflow: "example-workflow",
2587
+ })
2588
+ .pages()) {
2589
+ // Do something with each page
2590
+ }
2591
+
2592
+ // Or iterate over individual items across all pages
2593
+ for await (const workflowRun of zapier
2594
+ .listWorkflowRuns({
2595
+ workflow: "example-workflow",
2596
+ })
2597
+ .items()) {
2598
+ // Do something with each workflowRun
2599
+ }
2647
2600
  ```
2648
2601
 
2649
- ### Connections
2602
+ #### `listWorkflowVersions` 🧪 _experimental_
2650
2603
 
2651
- #### `createConnection`
2604
+ List published versions for a workflow, newest first
2652
2605
 
2653
- Create a new app connection, end-to-end. Mints the start URL via `get-connection-start-url`, prints it to stderr, opportunistically opens it in a browser when it looks safe to do so (skipping CI / SSH / headless-Linux by default — pass `--browser always` to force, `--browser never` to suppress), then polls via `wait-for-new-connection` until the user completes OAuth and the new connection appears. Returns the connection.
2606
+ **Parameters:**
2654
2607
 
2655
- This is the right command for most callers. Reach for the lower-level building blocks when you want either of: (a) hand off the URL and _not_ block on completion — call `get-connection-start-url` alone, no `wait-for-new-connection` needed, or (b) do something custom between minting the URL and waiting — call `get-connection-start-url`, do your work (email or DM the URL, render a QR code, etc.), then `wait-for-new-connection`.
2608
+ | Name | Type | Required | Default | Possible Values | Description |
2609
+ | -------------- | -------- | -------- | ------- | --------------- | ------------------------------------------------- |
2610
+ | `options` | `object` | ✅ | — | — | |
2611
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2612
+ | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of versions per page (max 100) |
2613
+ | ​ ↳ `cursor` | `string` | ❌ | — | — | Pagination cursor |
2614
+ | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total versions to return across all pages |
2615
+
2616
+ **Returns:** `Promise<PaginatedResult<WorkflowVersionItem>>`
2617
+
2618
+ | Name | Type | Required | Possible Values | Description |
2619
+ | ---------------------------- | ---------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2620
+ | `data[]` | `object[]` | ✅ | — | |
2621
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2622
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2623
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2624
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2625
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2626
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2627
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2628
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2629
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2630
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2631
+
2632
+ **Example:**
2633
+
2634
+ ```typescript
2635
+ // Get first page and a cursor for the second page
2636
+ const { data: workflowVersions, nextCursor } =
2637
+ await zapier.listWorkflowVersions({
2638
+ workflow: "example-workflow",
2639
+ });
2640
+
2641
+ // Or iterate over all pages
2642
+ for await (const page of zapier
2643
+ .listWorkflowVersions({
2644
+ workflow: "example-workflow",
2645
+ })
2646
+ .pages()) {
2647
+ // Do something with each page
2648
+ }
2649
+
2650
+ // Or iterate over individual items across all pages
2651
+ for await (const workflowVersion of zapier
2652
+ .listWorkflowVersions({
2653
+ workflow: "example-workflow",
2654
+ })
2655
+ .items()) {
2656
+ // Do something with each workflowVersion
2657
+ }
2658
+ ```
2659
+
2660
+ #### `listWorkflows` 🧪 _experimental_
2661
+
2662
+ List all active durable workflows for the authenticated account
2656
2663
 
2657
2664
  **Parameters:**
2658
2665
 
2659
- | Name | Type | Required | Default | Possible Values | Description |
2660
- | ------------------------------ | -------- | -------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2661
- | `options` | `object` | ✅ | — | — | |
2662
- | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
2663
- | ​ ↳ `browser` | `string` | ❌ | `"auto"` | `auto`, `always`, `never` | When to auto-open the URL in a browser. `auto` (default) opens in local sessions and skips opening in CI / SSH / headless-Linux. `always` forces the open attempt. `never` skips it. The URL is always printed to stderr regardless — a failed or skipped open degrades gracefully to copy-paste. |
2664
- | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300). |
2665
- | ​ ↳ `pollIntervalMilliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
2666
+ | Name | Type | Required | Default | Possible Values | Description |
2667
+ | -------------- | -------- | -------- | ------- | --------------- | -------------------------------------------------- |
2668
+ | `options` | `object` | ✅ | — | — | |
2669
+ | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of workflows per page (max 100) |
2670
+ | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total workflows to return across all pages |
2671
+ | ​ ↳ `cursor` | `string` | ❌ | — | — | Cursor to start from for pagination |
2666
2672
 
2667
- **Returns:** `Promise<ConnectionItem>`
2673
+ **Returns:** `Promise<PaginatedResult<WorkflowItem>>`
2668
2674
 
2669
- | Name | Type | Required | Possible Values | Description |
2670
- | ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2671
- | `data` | `object` | ✅ | — | |
2672
- | ​ ↳ `id` | `string` | ✅ | — | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
2673
- | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the connection was created for (e.g., 'SlackCLIAPI'). |
2674
- | ​ ↳ `title` | `string` | ❌ | — | Human-readable connection title set by the auth flow, when available. |
2675
+ | Name | Type | Required | Possible Values | Description |
2676
+ | ------------------------- | ---------- | -------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2677
+ | `data[]` | `object[]` | ✅ | — | |
2678
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
2679
+ | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
2680
+ | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
2681
+ | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
2682
+ | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
2683
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
2684
+ | ​ ↳ `disabled_reason` | `string` | ❌ | `trigger_claim_failed` | Why the workflow is off, when system-disabled. Null when not system-disabled. |
2685
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
2686
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
2687
+ | ​ ↳ `current_version_id` | `string` | ✅ | — | ID of the workflow version that runs handle. Null until a version is published. |
2688
+ | ​ ↳ `triggers[]` | `object[]` | ✅ | — | Trigger configurations from the current version, with live claim status. Empty array when the workflow has no triggers. |
2689
+ | ​   ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
2690
+ | ​   ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
2691
+ | ​   ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
2692
+ | ​   ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
2693
+ | ​   ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
2694
+ | ​   ↳ `error` | `string` | ❌ | — | Failure reason for the latest claim. Present (non-null) only when status is 'failed'. |
2695
+ | ​   ↳ `details` | `object` | ❌ | — | Trigger-type-specific metadata; shape varies by trigger type (e.g. `webhook_url` on catch-hook triggers). Null or absent when none applies. |
2696
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
2697
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
2698
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2675
2699
 
2676
2700
  **Example:**
2677
2701
 
2678
2702
  ```typescript
2679
- const { data: connection } = await zapier.createConnection({
2680
- app: "example-app",
2703
+ // Get first page and a cursor for the second page
2704
+ const { data: workflows, nextCursor } = await zapier.listWorkflows();
2705
+
2706
+ // Or iterate over all pages
2707
+ for await (const page of zapier.listWorkflows().pages()) {
2708
+ // Do something with each page
2709
+ }
2710
+
2711
+ // Or iterate over individual items across all pages
2712
+ for await (const workflow of zapier.listWorkflows().items()) {
2713
+ // Do something with each workflow
2714
+ }
2715
+ ```
2716
+
2717
+ #### `publishWorkflowDraft` 🧪 _experimental_
2718
+
2719
+ Publish an open draft as a new immutable workflow version. Advances the workflow's live pointer and discards the draft — publish consumes it, so an open draft always means unpublished work. Continue editing by creating a new draft, which forks from the just-published version.
2720
+
2721
+ **Parameters:**
2722
+
2723
+ | Name | Type | Required | Default | Possible Values | Description |
2724
+ | ------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2725
+ | `options` | `object` | ✅ | — | — | |
2726
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2727
+ | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
2728
+ | ​ ↳ `enabled` | `boolean` | ❌ | — | — | Set the workflow's enabled state as part of the publish. If omitted, the current enabled state is preserved. |
2729
+ | ​ ↳ `draftRevision` | `number` | ❌ | — | — | Expected draft revision for optimistic concurrency. Pass the revision from the last read; the server rejects the publish with a conflict if the draft has changed since. Omit to skip the check. |
2730
+ | ​ ↳ `manual` | `boolean` | ❌ | — | — | Declare this publish on-demand and triggerless, overriding the draft's stored intent for this publish only. Pass `manual: true` only when the draft has no trigger configured; the API rejects a draft with a trigger published as `manual: true` as a contradiction (400). |
2731
+
2732
+ **Returns:** `Promise<PublishWorkflowDraftResponse>`
2733
+
2734
+ | Name | Type | Required | Possible Values | Description |
2735
+ | ------------------------------ | -------- | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
2736
+ | `data` | `object` | ✅ | — | |
2737
+ | ​ ↳ `draft` | `object` | ✅ | — | The consumed draft: status is 'discarded' and discarded_at is set. base_version_id still records the version the draft was forked from. |
2738
+ | ​   ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
2739
+ | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2740
+ | ​   ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
2741
+ | ​   ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
2742
+ | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2743
+ | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
2744
+ | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
2745
+ | ​   ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
2746
+ | ​   ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
2747
+ | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
2748
+ | ​   ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
2749
+ | ​   ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
2750
+ | ​   ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
2751
+ | ​   ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
2752
+ | ​   ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
2753
+ | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
2754
+ | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
2755
+ | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
2756
+ | ​ ↳ `version` | `object` | ✅ | — | The newly published immutable workflow version, now live. |
2757
+ | ​   ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2758
+ | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2759
+ | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2760
+ | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2761
+ | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2762
+ | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2763
+ | ​   ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2764
+ | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2765
+ | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2766
+ | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2767
+
2768
+ **Example:**
2769
+
2770
+ ```typescript
2771
+ const { data: workflowVersion } = await zapier.publishWorkflowDraft({
2772
+ workflow: "example-workflow",
2773
+ draft: "example-draft",
2681
2774
  });
2682
2775
  ```
2683
2776
 
2684
- #### `findFirstConnection`
2777
+ #### `publishWorkflowVersion` 🧪 _experimental_
2685
2778
 
2686
- Find the first connection matching the criteria
2779
+ Publish a new version of a durable workflow. Enables the workflow by default.
2687
2780
 
2688
2781
  **Parameters:**
2689
2782
 
2690
- | Name | Type | Required | Default | Possible Values | Description |
2691
- | ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2692
- | `options` | `object` | ✅ | — | — | |
2693
- | ​ ↳ `search` | `string` | ❌ | — | — | Search term to filter connections by title |
2694
- | ​ ↳ `title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
2695
- | ​ ↳ `owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
2696
- | ​ ↳ `app` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
2697
- | ​ ↳ `account` | `string` | ❌ | — | — | Account to filter by |
2698
- | ​ ↳ `includeShared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
2699
- | ​ ↳ `status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
2783
+ | Name | Type | Required | Default | Possible Values | Description |
2784
+ | -------------------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2785
+ | `options` | `object` | ✅ | — | — | |
2786
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2787
+ | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Source files keyed by filename → contents |
2788
+ | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies. A version of "latest" is resolved by the server for @zapier/zapier-durable and @zapier/zapier-sdk only; every other value, including a "latest" on any other package, is passed to the install as written. |
2789
+ | ​ ↳ `zapierDurableVersion` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"), or "latest". Defaults to the server-configured version if omitted. "latest" is resolved by the server to the newest release old enough to clear the sandbox install age gate (24h) -- this is not npm's "latest" tag, which can point at a release too new to install. Ranges (^1.2.3, ~1.2) are rejected. |
2790
+ | ​ ↳ `enabled` | `boolean` | ❌ | — | — | Enable the workflow after publishing. Defaults to true if omitted; pass false to publish without enabling. |
2791
+ | ​ ↳ `ignoreOpenDrafts` | `boolean` | ❌ | — | — | Publish even though the workflow has open draft(s). Without this, the API rejects a direct publish with a 409 while any draft is open, since publishing the draft later would ship its stale content over this version. |
2792
+ | ​ ↳ `connections` | `object` | ❌ | — | — | Map of connection aliases to Zapier connections used by the workflow. Pass `null` to clear an existing binding. |
2793
+ | ​ ↳ `appVersions` | `object` | ❌ | — | — | Map of app keys to pinned app implementation/version used by the workflow. Pass `null` to clear an existing binding. |
2794
+ | ​ ↳ `trigger` | `object` | ❌ | — | — | Trigger configuration. When provided, the workflow subscribes to a Zapier trigger; for an on-demand, triggerless workflow, omit this and pass `manual: true` instead. |
2795
+ | ​   ↳ `selectedApi` | `string` | ❌ | — | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI'). Required when a trigger is configured. |
2796
+ | ​   ↳ `action` | `string` | ✅ | — | — | Trigger action key (e.g. 'new_row') |
2797
+ | ​   ↳ `authenticationId` | `string` | ❌ | — | — | Connection ID for the trigger source. Omit or pass null for no-auth triggers (e.g. Schedule by Zapier). |
2798
+ | ​   ↳ `params` | `object` | ❌ | — | — | Trigger parameters as a JSON object |
2799
+ | ​ ↳ `manual` | `boolean` | ❌ | — | — | Declare this an on-demand, triggerless workflow version. Pass `manual: true` only when omitting `trigger`; passing both is a contradiction the API rejects with a 400. |
2700
2800
 
2701
- **Returns:** `Promise<ConnectionItem>`
2801
+ **Returns:** `Promise<WorkflowVersionItem>`
2702
2802
 
2703
- | Name | Type | Required | Possible Values | Description |
2704
- | ------------------------------ | --------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
2705
- | `data` | `object` | ✅ | — | |
2706
- | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
2707
- | ​ ↳ `date` | `string` | ✅ | — | Date created |
2708
- | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
2709
- | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
2710
- | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
2711
- | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
2712
- | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
2713
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
2714
- | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
2715
- | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
2716
- | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
2717
- | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
2718
- | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
2719
- | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
2720
- | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
2721
- | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
2722
- | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
2723
- | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
2724
- | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
2725
- | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
2726
- | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
2727
- | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
2728
- | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
2729
- | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
2730
- | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
2731
- | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
2732
- | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
2733
- | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
2734
- | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
2803
+ | Name | Type | Required | Possible Values | Description |
2804
+ | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2805
+ | `data` | `object` | ✅ | — | |
2806
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
2807
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
2808
+ | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
2809
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
2810
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
2811
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
2812
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
2813
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
2814
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
2815
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
2735
2816
 
2736
2817
  **Example:**
2737
2818
 
2738
2819
  ```typescript
2739
- const { data: connection } = await zapier.findFirstConnection();
2820
+ const { data: workflowVersion } = await zapier.publishWorkflowVersion({
2821
+ workflow: "example-workflow",
2822
+ sourceFiles: {},
2823
+ });
2740
2824
  ```
2741
2825
 
2742
- #### `findUniqueConnection`
2826
+ #### `runDurable` 🧪 _experimental_
2743
2827
 
2744
- Find a unique connection matching the criteria
2828
+ Run a workflow's complete source-files map as a run-once durable run on code-substrate-runner (no deployed workflow required). Send every file the workflow needs, not only its entry point. Returns the run ID immediately; poll via getDurableRun for terminal status.
2745
2829
 
2746
2830
  **Parameters:**
2747
2831
 
2748
- | Name | Type | Required | Default | Possible Values | Description |
2749
- | ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2750
- | `options` | `object` | ✅ | — | — | |
2751
- | ​ ↳ `search` | `string` | ❌ | — | — | Search term to filter connections by title |
2752
- | ​ ↳ `title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
2753
- | ​ ↳ `owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
2754
- | ​ ↳ `app` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
2755
- | ​ ↳ `account` | `string` | ❌ | — | — | Account to filter by |
2756
- | ​ ↳ `includeShared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
2757
- | ​ ↳ `status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
2832
+ | Name | Type | Required | Default | Possible Values | Description |
2833
+ | -------------------------- | ---------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2834
+ | `options` | `object` | ✅ | — | — | |
2835
+ | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Source files keyed by filename → contents |
2836
+ | ​ ↳ `input` | `unknown` | ❌ | — | — | Input data passed to the run. Accepts any JSON value, or its JSON-string encoding. |
2837
+ | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies. A version of "latest" is resolved by the server for @zapier/zapier-durable and @zapier/zapier-sdk only; every other value, including a "latest" on any other package, is passed to the install as written. |
2838
+ | ​ ↳ `zapierDurableVersion` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"), or "latest". Defaults to the server-configured version if omitted. "latest" is resolved by the server to the newest release old enough to clear the sandbox install age gate (24h) -- this is not npm's "latest" tag, which can point at a release too new to install. Ranges (^1.2.3, ~1.2) are rejected. |
2839
+ | ​ ↳ `connections` | `object` | ❌ | — | — | Named connection aliases. Maps each alias to an object holding its Zapier connection ID, e.g. `{ "slack": { "connectionId": "123" } }`. |
2840
+ | ​ ↳ `appVersions` | `object` | ❌ | — | — | Pinned app versions. Maps app keys (slugs) to implementation names and versions. |
2841
+ | ​ ↳ `private` | `boolean` | ❌ | — | — | Only the creating user can see the run (default false) |
2842
+ | ​ ↳ `notifications[]` | `object[]` | ❌ | — | — | Webhook subscribers for run lifecycle events. Each entry specifies a URL and the events it subscribes to. |
2843
+ | ​   ↳ `type` | `string` | ❌ | — | `webhook` | Notification transport. Webhook is the only supported type. |
2844
+ | ​   ↳ `url` | `string` | ✅ | — | — | URL to POST event notifications to. Payload is `{run_id, event}`. |
2845
+ | ​   ↳ `max_retries` | `number` | ❌ | — | — | Max delivery attempts with exponential backoff. Defaults to 3 server-side. |
2846
+ | ​   ↳ `events` | `array` | ✅ | — | — | One or more lifecycle events to subscribe this URL to. |
2758
2847
 
2759
- **Returns:** `Promise<ConnectionItem>`
2848
+ **Returns:** `Promise<DurableRunItem>`
2760
2849
 
2761
- | Name | Type | Required | Possible Values | Description |
2762
- | ------------------------------ | --------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
2763
- | `data` | `object` | ✅ | — | |
2764
- | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
2765
- | ​ ↳ `date` | `string` | ✅ | — | Date created |
2766
- | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
2767
- | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
2768
- | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
2769
- | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
2770
- | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
2771
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
2772
- | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
2773
- | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
2774
- | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
2775
- | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
2776
- | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
2777
- | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
2778
- | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
2779
- | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
2780
- | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
2781
- | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
2782
- | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
2783
- | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
2784
- | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
2785
- | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
2786
- | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
2787
- | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
2788
- | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
2789
- | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
2790
- | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
2791
- | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
2792
- | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
2850
+ | Name | Type | Required | Possible Values | Description |
2851
+ | ---------------- | --------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
2852
+ | `data` | `object` | ✅ | — | |
2853
+ | ​ ↳ `id` | `string` | ✅ | — | Run ID (UUID) — server-generated, time-sortable |
2854
+ | ​ ↳ `status` | `string` | ✅ | `initialized` | Always `initialized` on creation. Poll via getDurableRun to observe the run advancing to `started` / `finished` / `failed` / `cancelled`. |
2855
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | When true, the run is visible only to the creating user; otherwise visible across the account. |
2856
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2793
2857
 
2794
2858
  **Example:**
2795
2859
 
2796
2860
  ```typescript
2797
- const { data: connection } = await zapier.findUniqueConnection();
2861
+ const { data: durableRun } = await zapier.runDurable({
2862
+ sourceFiles: {},
2863
+ });
2798
2864
  ```
2799
2865
 
2800
- #### `getConnection`
2866
+ #### `runWorkflowDraft` 🧪 _experimental_
2801
2867
 
2802
- Get details for a specific connection
2868
+ Launch a draft test run: execute the draft's current source without publishing it. The draft's payload is snapshotted onto the run at creation, so later edits (or discarding the draft) never change what the run executed. Draft runs are free (not task-charged) and rate limited per user. The run is accepted asynchronously — it comes back `initialized`; follow it with `getWorkflowRun`, or list it via `listWorkflowRuns` with `kind: "draft"`.
2803
2869
 
2804
2870
  **Parameters:**
2805
2871
 
2806
- | Name | Type | Required | Default | Possible Values | Description |
2807
- | ---------------- | ---------------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2808
- | `options` | `object` | ✅ | — | — | |
2809
- | ​ ↳ `connection` | `string, number` | ✅ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
2872
+ | Name | Type | Required | Default | Possible Values | Description |
2873
+ | ------------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2874
+ | `options` | `object` | ✅ | — | — | |
2875
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2876
+ | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
2877
+ | ​ ↳ `draftRevision` | `number` | ✅ | — | — | The draft revision you intend to run, from the last read of the draft. The server rejects the run with a conflict if the draft has changed since. The upstream API treats this check as optional; the SDK requires it so a test run can never silently execute source the caller has already replaced. |
2878
+ | ​ ↳ `input` | `unknown` | ❌ | — | — | Input data passed to the workflow. Accepts any JSON value, or its JSON-string encoding. Omit for a workflow that takes no input. |
2810
2879
 
2811
- **Returns:** `Promise<ConnectionItem>`
2880
+ **Returns:** `Promise<RunWorkflowDraftResponse>`
2812
2881
 
2813
- | Name | Type | Required | Possible Values | Description |
2814
- | ------------------------------ | --------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
2815
- | `data` | `object` | ✅ | — | |
2816
- | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
2817
- | ​ ↳ `date` | `string` | ✅ | — | Date created |
2818
- | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
2819
- | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
2820
- | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
2821
- | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
2822
- | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
2823
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
2824
- | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
2825
- | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
2826
- | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
2827
- | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
2828
- | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
2829
- | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
2830
- | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
2831
- | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
2832
- | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
2833
- | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
2834
- | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
2835
- | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
2836
- | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
2837
- | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
2838
- | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
2839
- | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
2840
- | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
2841
- | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
2842
- | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
2843
- | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
2844
- | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
2882
+ | Name | Type | Required | Possible Values | Description |
2883
+ | ----------------------- | --------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
2884
+ | `data` | `object` | ✅ | — | |
2885
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow run ID (UUIDv7). Unique across live and draft runs. |
2886
+ | ​ ↳ `kind` | `string` | ✅ | `draft` | A run launched from a workflow draft. |
2887
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow this run belongs to |
2888
+ | ​ ↳ `durable_run_id` | `string` | ✅ | — | Linked code-substrate-runner run ID. Usually still null in this response — the run is accepted and launched in the background. |
2889
+ | ​ ↳ `workflow_draft_id` | `string` | ✅ | — | The draft this run was launched from. Becomes null once that draft is deleted — the run outlives its draft. |
2890
+ | ​ ↳ `draft_revision` | `number` | ✅ | — | The draft's revision at the moment this run was created. |
2891
+ | ​ ↳ `status` | `string` | ✅ | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
2892
+ | ​ ↳ `input` | `unknown` | ✅ | — | Input passed to the run |
2893
+ | ​ ↳ `output` | `unknown` | ✅ | — | Return value, present when status is `finished` |
2894
+ | ​ ↳ `error` | `unknown` | ✅ | — | Error payload when status is `failed` (null otherwise) |
2895
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the run was created (ISO-8601) |
2896
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the run was last updated (ISO-8601) |
2845
2897
 
2846
2898
  **Example:**
2847
2899
 
2848
2900
  ```typescript
2849
- const { data: connection } = await zapier.getConnection({
2850
- connection: "example-connection",
2901
+ const { data: workflowRun } = await zapier.runWorkflowDraft({
2902
+ workflow: "example-workflow",
2903
+ draft: "example-draft",
2904
+ draftRevision: 100,
2851
2905
  });
2852
2906
  ```
2853
2907
 
2854
- #### `getConnectionStartUrl`
2855
-
2856
- Mint a short-lived URL that begins an SDK-initiated connection flow. The URL is signed by zapier.com and bound to the current user/account — opening it in a different browser session will fail the binding check. Returns the URL as data so the caller decides what to do with it.
2857
-
2858
- Use this directly (rather than the higher-level `create-connection`) when you want either of: (a) hand off the URL and _not_ block waiting for completion — call this alone, skip `wait-for-new-connection` entirely, or (b) do something custom between minting the URL and waiting for the connection — call this, then email or DM the URL, render it as a QR code for mobile sign-in, etc., then call `wait-for-new-connection`. For the common case where you'd just print and poll back-to-back, `create-connection` is one call.
2859
-
2860
- Pair with `wait-for-new-connection` to detect completion: pass the `startedAt` returned here straight through (it's the server's mint time, so polling isn't affected by client clock skew). Example (JS):
2908
+ #### `triggerWorkflow` 🧪 _experimental_
2861
2909
 
2862
- ```ts
2863
- const {
2864
- data: { url, app, startedAt },
2865
- } = await zapier.getConnectionStartUrl({ app: "slack" });
2866
- // hand `url` off — print it, DM it, email it, render a button, whatever
2867
- const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
2868
- ```
2910
+ Look up a workflow's trigger URL and fire it manually, as the authenticated account.
2869
2911
 
2870
2912
  **Parameters:**
2871
2913
 
2872
- | Name | Type | Required | Default | Possible Values | Description |
2873
- | --------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
2874
- | `options` | `object` | ✅ | — | — | |
2875
- | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
2914
+ | Name | Type | Required | Default | Possible Values | Description |
2915
+ | -------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2916
+ | `options` | `object` | ✅ | — | — | |
2917
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
2918
+ | ​ ↳ `input` | `unknown` | ❌ | — | — | JSON payload delivered as the trigger body. Accepts any JSON value, or its JSON-string encoding. Sent as `application/json`; omit to fire with an empty body. |
2876
2919
 
2877
- **Returns:** `Promise<ConnectionStartUrlItem>`
2920
+ **Returns:** `Promise<WorkflowRunItem>`
2878
2921
 
2879
- | Name | Type | Required | Possible Values | Description |
2880
- | --------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2881
- | `data` | `object` | ✅ | — | |
2882
- | ​ ↳ `url` | `string` | ✅ | — | URL the user should open in their browser to complete the auth flow. Single-use, time-limited. |
2883
- | ​ ↳ `expiresAt` | `number` | ✅ | — | Unix timestamp (seconds) after which the URL's signature is rejected by zapier.com. |
2884
- | ​ ↳ `startedAt` | `number` | ✅ | — | Unix timestamp (seconds) when the server minted the URL. Use it as the `startedAt` for `wait-for-new-connection` so polling is anchored to server time rather than a possibly-skewed client clock. |
2885
- | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the URL was minted for (e.g., 'SlackCLIAPI'). Useful for downstream filtering. |
2922
+ | Name | Type | Required | Possible Values | Description |
2923
+ | ----------------- | -------- | -------- | --------------- | ---------------------------------------- |
2924
+ | `data` | `object` | ✅ | — | |
2925
+ | ​ ↳ `id` | `string` | ✅ | — | Trigger ID (UUID) |
2926
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow that was triggered (UUID) |
2927
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the trigger was received (ISO-8601) |
2886
2928
 
2887
2929
  **Example:**
2888
2930
 
2889
2931
  ```typescript
2890
- const { data: connectionStartUrl } = await zapier.getConnectionStartUrl({
2891
- app: "example-app",
2932
+ const { data: workflowRun } = await zapier.triggerWorkflow({
2933
+ workflow: "example-workflow",
2892
2934
  });
2893
2935
  ```
2894
2936
 
2895
- #### `listConnections`
2937
+ #### `updateAgenticManagementConfig` 🧪 _experimental_
2896
2938
 
2897
- List available connections with optional filtering
2939
+ Change the modes a workflow runs, whether fixes are applied without approval, or both. A `modes` list replaces the whole current set rather than adding to it.
2898
2940
 
2899
2941
  **Parameters:**
2900
2942
 
2901
- | Name | Type | Required | Default | Possible Values | Description |
2902
- | ------------------- | --------- | -------- | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
2903
- | `options` | `object` | ✅ | — | — | |
2904
- | ​ ↳ `search` | `string` | ❌ | — | — | Search term to filter connections by title |
2905
- | ​ ↳ `title` | `string` | ❌ | — | — | Filter connections by exact title match (searches first, then filters locally) |
2906
- | ​ ↳ `owner` | `string` | ❌ | — | — | Filter by owner, 'me' for your own connections or a specific user ID |
2907
- | ​ ↳ `app` | `string` | ❌ | — | — | App key of connections to list (e.g., 'SlackCLIAPI' or slug like 'github') |
2908
- | ​ ↳ `connections` | `array` | ❌ | — | — | List of connection IDs to filter by |
2909
- | ​ ↳ `account` | `string` | ❌ | — | — | Account to filter by |
2910
- | ​ ↳ `includeShared` | `boolean` | ❌ | — | — | Include connections shared with you. By default, only your own connections are returned (owner=me). Set to true to also include shared connections. |
2911
- | ​ ↳ `status` | `string` | ❌ | — | `active`, `expired`, `all` | Filter connections by expiry: 'active' (default) returns only non-expired connections, 'expired' only expired ones, and 'all' returns both. |
2912
- | ​ ↳ `pageSize` | `number` | ❌ | — | — | Number of connections per page. The upstream API may cap this and reject values above its limit. |
2913
- | ​ ↳ `maxItems` | `number` | ❌ | — | — | Maximum total items to return across all pages |
2914
- | ​ ↳ `cursor` | `string` | ❌ | — | — | Cursor to start from |
2943
+ | Name | Type | Required | Default | Possible Values | Description |
2944
+ | ----------------- | --------- | -------- | ------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2945
+ | `options` | `object` | ✅ | — | — | |
2946
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to update. |
2947
+ | ​ ↳ `modes` | `array` | ❌ | — | — | The modes to run. The list you pass replaces the whole current set in one step; it is not added to what is already active. Omit it to leave the active modes as they are. A mode is what Agentic Management watches for and what it changes in response. `heal` monitors runs for errors and, when something breaks, diagnoses the cause and drafts and tests a fix; it is the mode a workflow gets by default. `expand` grows what the workflow covers: it reviews runs that succeeded without actually doing anything — a lookup that matched nothing, a filter that passed no items, a trigger payload no branch handles — and proposes a new branch or step to handle that case, rather than rewriting the ones that already work. `harden` watches the AI steps: when an AI step keeps doing the same work the same way, it converts that step into fixed code, so the workflow runs faster, costs less, and behaves the same way every time. Modes stack — each one you name runs alongside the others, and a mode you leave out does nothing, so a workflow on `expand` alone does not repair failed runs. Whether a change goes live on its own or waits for someone to approve it is `autoApprove`, not the mode. |
2948
+ | ​ ↳ `autoApprove` | `boolean` | ❌ | — | — | Apply the fixes Agentic Management proposes without asking first. Set it to false and each fix waits for someone to approve it before anything changes. Omit it to leave the current setting alone. |
2915
2949
 
2916
- **Returns:** `Promise<PaginatedResult<ConnectionItem>>`
2950
+ **Returns:** `Promise<AgenticManagementConfigItem>`
2917
2951
 
2918
- | Name | Type | Required | Possible Values | Description |
2919
- | ------------------------------ | ---------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
2920
- | `data[]` | `object[]` | ✅ | — | |
2921
- | ​ ↳ `id` | `string` | ✅ | — | Unique identifier for the connection |
2922
- | ​ ↳ `date` | `string` | ✅ | — | Date created |
2923
- | ​ ↳ `lastchanged` | `string` | ❌ | — | Date last changed |
2924
- | ​ ↳ `account_id` | `string` | ✅ | — | Account ID associated with this connection |
2925
- | ​ ↳ `slug` | `string` | ❌ | — | Human-readable app slug for this connection's integration (e.g. 'google-sheets'). Null when no slug is registered for the app. |
2926
- | ​ ↳ `destination_selected_api` | `string` | ❌ | — | Destination API key (if applicable) |
2927
- | ​ ↳ `is_invite_only` | `boolean` | ✅ | — | Whether the connection is invite-only |
2928
- | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the connection is private |
2929
- | ​ ↳ `shared_with_all` | `boolean` | ✅ | — | Whether the connection is shared with all users |
2930
- | ​ ↳ `is_stale` | `string` | ❌ | — | Stale status string |
2931
- | ​ ↳ `is_shared` | `string` | ❌ | — | Shared status string |
2932
- | ​ ↳ `marked_stale_at` | `string` | ❌ | — | Date when marked stale |
2933
- | ​ ↳ `label` | `string` | ❌ | — | User label for the connection |
2934
- | ​ ↳ `identifier` | `string` | ❌ | — | Identifier |
2935
- | ​ ↳ `title` | `string` | ❌ | — | Title of the connection |
2936
- | ​ ↳ `url` | `string` | ❌ | — | URL to the connection resource |
2937
- | ​ ↳ `groups` | `array` | ❌ | — | Array of groups associated with the connection |
2938
- | ​ ↳ `members` | `string` | ❌ | — | Members associated with the connection |
2939
- | ​ ↳ `permissions` | `object` | ❌ | — | Permissions for the connection |
2940
- | ​ ↳ `public_id` | `string` | ❌ | — | Public UUID for the connection |
2941
- | ​ ↳ `account_public_id` | `string` | ❌ | — | Public UUID for the associated account |
2942
- | ​ ↳ `customuser_public_id` | `string` | ❌ | — | Public UUID for the associated custom user |
2943
- | ​ ↳ `implementation_id` | `string` | ❌ | — | Implementation ID (was selected_api) |
2944
- | ​ ↳ `profile_id` | `string` | ❌ | — | Profile ID (was customuser_id) |
2945
- | ​ ↳ `is_expired` | `string` | ❌ | — | Whether the connection is expired (mapped from is_stale) |
2946
- | ​ ↳ `expired_at` | `string` | ❌ | — | Date when connection expired (mapped from marked_stale_at) |
2947
- | ​ ↳ `app_key` | `string` | ❌ | — | App Key extracted from implementation_id |
2948
- | ​ ↳ `app_version` | `string` | ❌ | — | App Version extracted from implementation_id |
2949
- | ​ ↳ `is_managed` | `boolean` | ❌ | — | Whether this connection is managed by account admins (no individual owner) |
2950
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
2952
+ | Name | Type | Required | Possible Values | Description |
2953
+ | ------------------ | --------- | -------- | --------------- | ------------------------------------------------------------- |
2954
+ | `data` | `object` | ✅ | — | |
2955
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow whose config was updated. |
2956
+ | ​ ↳ `modes` | `array` | ✅ | — | The modes the workflow runs after this update. |
2957
+ | ​ ↳ `auto_approve` | `boolean` | ✅ | — | Whether fixes are applied without approval after this update. |
2951
2958
 
2952
2959
  **Example:**
2953
2960
 
2954
2961
  ```typescript
2955
- // Get first page and a cursor for the second page
2956
- const { data: connections, nextCursor } = await zapier.listConnections();
2962
+ const { data: agenticManagementConfig } =
2963
+ await zapier.updateAgenticManagementConfig({
2964
+ workflow: "example-workflow",
2965
+ });
2966
+ ```
2957
2967
 
2958
- // Or iterate over all pages
2959
- for await (const page of zapier.listConnections().pages()) {
2960
- // Do something with each page
2961
- }
2968
+ #### `updateAgenticManagementIntent` 🧪 _experimental_
2962
2969
 
2963
- // Or iterate over individual items across all pages
2964
- for await (const connection of zapier.listConnections().items()) {
2965
- // Do something with each connection
2966
- }
2967
- ```
2970
+ Record what one workflow version is meant to do. Writing again for the same version replaces the text already stored, so there is no separate create and update.
2968
2971
 
2969
- #### `waitForNewConnection`
2972
+ **Parameters:**
2970
2973
 
2971
- Wait for a new connection to appear for the given app. Polls the connections list newest-first until the most recent matching row's `date` is at or after the started-at timestamp, then returns it. Pair with `get-connection-start-url` — that mints the URL the user opens, this waits for the resulting connection to land. Errors with a timeout after the configured timeout (default 5 min). Example (JS):
2974
+ | Name | Type | Required | Default | Possible Values | Description |
2975
+ | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2976
+ | `options` | `object` | ✅ | — | — | |
2977
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to write to. |
2978
+ | ​ ↳ `intent` | `string` | ✅ | — | — | What this version of the workflow is for, in your own words: the outcome it produces, what sets it off, and anything that must always hold true. Plain prose, not code. |
2979
+ | ​ ↳ `version` | `string` | ❌ | — | — | The workflow version the intent belongs to. Each version stores its own intent, and a version never picks up the intent of another, so publishing a new version starts it with none. Omit this to use the workflow's current published version. |
2972
2980
 
2973
- ```ts
2974
- const {
2975
- data: { url, app, startedAt },
2976
- } = await zapier.getConnectionStartUrl({ app: "slack" });
2977
- // show `url` to the user via the channel they're reading from
2978
- const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
2981
+ **Returns:** `Promise<AgenticManagementIntentItem>`
2982
+
2983
+ | Name | Type | Required | Possible Values | Description |
2984
+ | ------------------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2985
+ | `data` | `object` | ✅ | — | |
2986
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow the intent belongs to. |
2987
+ | ​ ↳ `workflow_version_id` | `string` | ✅ | — | The version this read or write actually landed on, so you can tell which one answered when you omitted `version`. `null` only when you read a workflow that has nothing published yet. |
2988
+ | ​ ↳ `intent` | `string` | ✅ | — | The intent stored for this version, or `null` when this version has none. Intent is never carried over from another version. |
2989
+ | ​ ↳ `updated_at` | `string` | ❌ | — | When the intent was last written; `null` when never captured. |
2990
+
2991
+ **Example:**
2992
+
2993
+ ```typescript
2994
+ const { data: agenticManagementIntent } =
2995
+ await zapier.updateAgenticManagementIntent({
2996
+ workflow: "example-workflow",
2997
+ intent: "example-intent",
2998
+ });
2979
2999
  ```
2980
3000
 
3001
+ #### `updateWorkflow` 🧪 _experimental_
3002
+
3003
+ Update a durable workflow's name and/or description
3004
+
2981
3005
  **Parameters:**
2982
3006
 
2983
- | Name | Type | Required | Default | Possible Values | Description |
2984
- | ------------------------------ | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2985
- | `options` | `object` | ✅ | — | — | |
2986
- | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
2987
- | ​ ↳ `startedAt` | `number` | ✅ | — | — | Unix timestamp (seconds). Only connections whose `date` is at or after this value count as 'new'. Prefer the `startedAt` returned by `get-connection-start-url` — it's server-stamped, so the comparison isn't thrown off by client clock skew. If you mint the timestamp yourself, capture it _before_ showing the start URL so a fast OAuth completion isn't missed. |
2988
- | ​ ↳ `timeoutSeconds` | `number` | ❌ | — | — | How long to wait before giving up. Default 5 minutes (300). |
2989
- | ​ ↳ `pollIntervalMilliseconds` | `number` | ❌ | — | — | Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults). |
3007
+ | Name | Type | Required | Default | Possible Values | Description |
3008
+ | ----------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------- |
3009
+ | `options` | `object` | ✅ | — | — | |
3010
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
3011
+ | ​ ↳ `name` | `string` | ❌ | — | — | New name for the workflow |
3012
+ | ​ ↳ `description` | `string` | ❌ | — | — | New description for the workflow (pass null to clear) |
2990
3013
 
2991
- **Returns:** `Promise<ConnectionItem>`
3014
+ **Returns:** `Promise<WorkflowItem>`
2992
3015
 
2993
- | Name | Type | Required | Possible Values | Description |
2994
- | ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2995
- | `data` | `object` | ✅ | — | |
2996
- | ​ ↳ `id` | `string` | ✅ | — | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
2997
- | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the connection was created for (e.g., 'SlackCLIAPI'). |
2998
- | ​ ↳ `title` | `string` | ❌ | — | Human-readable connection title set by the auth flow, when available. |
3016
+ | Name | Type | Required | Possible Values | Description |
3017
+ | ------------------------ | --------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3018
+ | `data` | `object` | ✅ | — | |
3019
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
3020
+ | ​ ↳ `name` | `string` | ✅ | — | Workflow name (post-update) |
3021
+ | ​ ↳ `description` | `string` | ✅ | — | Workflow description, post-update (null if unset) |
3022
+ | ​ ↳ `trigger_url` | `string` | ✅ | — | Public URL that fires this workflow when POSTed to. Embeds a trigger token in the path — treat as sensitive. Requests must also be authenticated as the account. |
3023
+ | ​ ↳ `editor_url` | `string` | ✅ | — | URL to the Zapier workflow editor for this workflow |
3024
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
3025
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
3026
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
3027
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
3028
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When this update was applied (ISO-8601) |
2999
3029
 
3000
3030
  **Example:**
3001
3031
 
3002
3032
  ```typescript
3003
- const { data: connection } = await zapier.waitForNewConnection({
3004
- app: "example-app",
3005
- startedAt: 100,
3033
+ const { data: workflow } = await zapier.updateWorkflow({
3034
+ workflow: "example-workflow",
3006
3035
  });
3007
3036
  ```
3008
3037
 
3009
- ### HTTP Requests
3010
-
3011
- #### `fetch`
3038
+ #### `updateWorkflowDraft` 🧪 _experimental_
3012
3039
 
3013
- Make authenticated HTTP requests to any API through Zapier. Pass a connectionId to automatically inject the user's stored credentials (OAuth tokens, API keys, etc.) into the outgoing request. Mirrors the native fetch(url, init?) signature with additional Zapier-specific options.
3040
+ Update (autosave) an open workflow draft
3014
3041
 
3015
3042
  **Parameters:**
3016
3043
 
3017
- | Name | Type | Required | Default | Possible Values | Description |
3018
- | -------------------- | ------------------------ | -------- | ------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3019
- | `url` | `string, custom` | ✅ | — | — | The full URL of the API endpoint to call (proxied through Zapier's API Proxy) |
3020
- | `init` | `object` | ❌ | — | — | Request options including method, headers, body, and authentication |
3021
- | ​ ↳ `method` | `string` | ❌ | — | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method for the request (defaults to GET) |
3022
- | ​ ↳ `headers` | `object` | ❌ | — | — | HTTP headers to include in the request |
3023
- | ​ ↳ `body` | `string, custom, record` | ❌ | — | — | Request body — plain objects and JSON strings are auto-detected and Content-Type is set accordingly |
3024
- | ​ ↳ `connection` | `string, number` | ❌ | — | — | Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. |
3025
- | ​ ↳ `callbackUrl` | `string` | ❌ | — | — | URL to send async response to (makes request async) |
3026
- | ​ ↳ `idempotencyKey` | `string` | ❌ | — | — | Key used to make API Proxy retries safe from duplicate side effects |
3027
- | ​ ↳ `maxTimeSeconds` | `number` | ❌ | — | — | Maximum seconds to wait for a response. Honored on a best-effort basis; the server may silently enforce a lower ceiling. |
3044
+ | Name | Type | Required | Default | Possible Values | Description |
3045
+ | -------------------------- | --------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3046
+ | `options` | `object` | ✅ | — | — | |
3047
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | Durable workflow ID |
3048
+ | ​ ↳ `draft` | `string` | ✅ | — | — | Workflow draft ID |
3049
+ | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Source files keyed by filename → contents |
3050
+ | ​ ↳ `zapierDurableVersion` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"), or "latest". Leaves the stored pin unchanged if omitted. A draft stores what you pass verbatim, so "latest" is recorded as-is and resolved to an exact version when the draft is published -- reading the draft back shows "latest", not a version. Ranges (^1.2.3, ~1.2) are rejected at publish. |
3051
+ | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies. A version of "latest" is resolved by the server for @zapier/zapier-durable and @zapier/zapier-sdk only; every other value, including a "latest" on any other package, is passed to the install as written. |
3052
+ | ​ ↳ `draftRevision` | `number` | ❌ | — | — | Expected draft revision for optimistic concurrency. Pass the revision from the last read; the server rejects the save with a conflict if the draft has changed since. Omit to skip the check. |
3053
+ | ​ ↳ `trigger` | `object` | ❌ | — | — | Trigger configuration. Omit to leave the stored trigger unchanged, pass null to clear it, or pass an object to replace it; for an on-demand, triggerless workflow, clear this and pass `manual: true` instead. |
3054
+ | ​ ↳ `connections` | `object` | ❌ | — | — | Map of connection aliases to Zapier connections used by the workflow. Pass `null` to clear an existing binding. |
3055
+ | ​ ↳ `appVersions` | `object` | ❌ | — | — | Map of app keys to pinned app implementation/version used by the workflow. Pass `null` to clear an existing binding. |
3056
+ | ​ ↳ `manual` | `boolean` | ❌ | — | — | Declare this draft on-demand and triggerless. Pass `manual: true` only when omitting `trigger` (or clearing it with `trigger: null`); passing both is a contradiction the API rejects with a 400. Setting a `trigger` later clears a previously stored `manual: true`. |
3028
3057
 
3029
- **Returns:** `Promise<Response>`
3058
+ **Returns:** `Promise<WorkflowDraftItem>`
3059
+
3060
+ | Name | Type | Required | Possible Values | Description |
3061
+ | ---------------------------- | -------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
3062
+ | `data` | `object` | ✅ | — | |
3063
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow draft ID (UUID) |
3064
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
3065
+ | ​ ↳ `slug` | `string` | ✅ | — | Human-friendly display name, not an identifier: two open drafts of a workflow may share one |
3066
+ | ​ ↳ `base_version_id` | `string` | ✅ | — | The version this draft was forked from (the live version at draft creation), or null when the workflow had no published version yet |
3067
+ | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
3068
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this draft |
3069
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this draft (or null) |
3070
+ | ​ ↳ `draft_revision` | `number` | ✅ | — | Monotonic revision counter for optimistic concurrency. Echo it back on draft updates to detect concurrent edits. |
3071
+ | ​ ↳ `status` | `string` | ✅ | `open`, `discarded` | Lifecycle status of a workflow draft. |
3072
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who created (forked) this draft |
3073
+ | ​ ↳ `last_edited_by_user_id` | `string` | ✅ | — | ID of the user who last saved this draft (or null) |
3074
+ | ​ ↳ `last_edited_at` | `string` | ✅ | — | When the draft was last edited (ISO-8601, or null) |
3075
+ | ​ ↳ `discarded_at` | `string` | ✅ | — | When the draft was discarded (ISO-8601), or null while open |
3076
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the draft was created (ISO-8601) |
3077
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the draft row was last updated (ISO-8601) |
3078
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration held on this draft, or null for webhook-only workflows. |
3079
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this draft (or null). |
3080
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this draft (or null). |
3030
3081
 
3031
3082
  **Example:**
3032
3083
 
3033
3084
  ```typescript
3034
- const result = await zapier.fetch("https://example.com", {});
3085
+ const { data: workflowDraft } = await zapier.updateWorkflowDraft({
3086
+ workflow: "example-workflow",
3087
+ draft: "example-draft",
3088
+ sourceFiles: {},
3089
+ });
3035
3090
  ```
3036
3091
 
3037
- ### Human Inputs (Experimental)
3038
-
3039
- > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
3040
-
3041
- #### `createForm` 🧪 _experimental_
3092
+ #### `validateWorkflow` 🧪 _experimental_
3042
3093
 
3043
- Create a Zapier Form from a title and optional fields. Forms publish by default and return a shareable `hosted_url`; set `draft` to save without publishing.
3094
+ Validate durable workflow source without publishing it. Returns source diagnostics; issue kinds are extensible and may be unfamiliar to the client.
3044
3095
 
3045
3096
  **Parameters:**
3046
3097
 
3047
- | Name | Type | Required | Default | Possible Values | Description |
3048
- | ------------------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3049
- | `options` | `object` | ✅ | — | — | |
3050
- | ​ ↳ `title` | `string` | ✅ | — | — | The title shown in the Forms UI and on the form. |
3051
- | ​ ↳ `description` | `string` | ❌ | — | — | An optional description of the form. |
3052
- | ​ ↳ `fields[]` | `object[]` | ❌ | — | — | Initial fields to add to the form. |
3053
- | ​   ↳ `label` | `string` | ✅ | — | — | Human-readable label shown above the input. |
3054
- | ​   ↳ `type` | `string` | ✅ | — | `short_text`, `long_text`, `email`, `number`, `yes_no`, `url`, `date`, `date_range`, `currency`, `phone_number`, `dropdown`, `integration_backed` | The type of field. |
3055
- | ​   ↳ `required` | `boolean` | ❌ | — | — | Whether the field must be answered before the form can submit. |
3056
- | ​   ↳ `disabled` | `boolean` | ❌ | — | — | When true, the field is rendered read-only — shown but not editable. A rendering hint only; it is not enforced during submission validation. |
3057
- | ​   ↳ `variant` | `string` | ❌ | — | `checkbox`, `radio` | For `yes_no` fields: `checkbox` renders a single toggle, `radio` renders explicit yes/no buttons. Defaults to `checkbox`. |
3058
- | ​   ↳ `multiUrl` | `boolean` | ❌ | — | — | For `url` fields: when true the field accepts a list of URLs, otherwise a single URL. Defaults to false. |
3059
- | ​   ↳ `includeTime` | `boolean` | ❌ | — | — | For `date` and `date_range` fields: when true the picker also captures a time. Defaults to false. |
3060
- | ​   ↳ `currencyFormat` | `string` | ❌ | — | — | For `currency` fields: ISO 4217 currency code (e.g. `usd`, `eur`). Controls the symbol shown in the form UI. |
3061
- | ​   ↳ `decimals` | `literal` | ❌ | — | — | For `currency` fields: allowed decimal places. `0` for whole numbers, `2` for up to two decimal places. Defaults to `2`. |
3062
- | ​   ↳ `defaultCountry` | `string` | ❌ | — | — | For `phone_number` fields: ISO 3166-1 alpha-2 code for the default selected country (e.g. `US`). Defaults to `US`. |
3063
- | ​   ↳ `phoneNumberFormat` | `string` | ❌ | — | `national`, `international` | For `phone_number` fields: `national` omits the country-code prefix, `international` includes it. Defaults to `national`. |
3064
- | ​   ↳ `acceptedCountries` | `array` | ❌ | — | — | For `phone_number` fields: restrict input to specific ISO 3166-1 alpha-2 country codes. Omit to allow all countries. |
3065
- | ​   ↳ `options[]` | `object[]` | ❌ | — | — | For `dropdown` fields: the selectable options. At least one is required. |
3066
- | ​     ↳ `value` | `string` | ✅ | — | — | The value submitted when this option is selected. |
3067
- | ​     ↳ `label` | `string` | ✅ | — | — | Human-readable label shown to the user. |
3068
- | ​   ↳ `multiSelect` | `boolean` | ❌ | — | — | For `dropdown` fields: when true the user may select multiple options. Defaults to false. |
3069
- | ​   ↳ `dataSource` | `object` | ❌ | — | — | For `integration_backed` fields: where to fetch the field's options from at render time. |
3070
- | ​     ↳ `app` | `string` | ✅ | — | — | Zapier app to pull options from. See `listApps` for the catalog. |
3071
- | ​     ↳ `actionType` | `string` | ✅ | — | `read`, `read_bulk` | Whether the data source returns a single record (`read`) or a collection (`read_bulk`). |
3072
- | ​     ↳ `resource` | `string` | ✅ | — | — | Resource name within the app — typically a trigger or search key from the app's definition. |
3073
- | ​     ↳ `valueKey` | `string` | ❌ | — | — | Property on each returned record to use as the submitted option value. Defaults to `id`. |
3074
- | ​     ↳ `labelKey` | `string` | ❌ | — | — | Property on each returned record to use as the displayed option label. Defaults to a sensible name field. |
3075
- | ​ ↳ `draft` | `boolean` | ❌ | — | — | When true, save without publishing. Omit to publish immediately, making `hosted_url` live. |
3076
- | ​ ↳ `confirmationTitle` | `string` | ❌ | — | — | Heading shown to the respondent after they submit. Omit to use the form renderer's default. |
3077
- | ​ ↳ `confirmationMessage` | `string` | ❌ | — | — | Message shown to the respondent after they submit, below the confirmation title. Omit to use the form renderer's default. |
3078
- | ​ ↳ `callbackUrl` | `string` | ❌ | — | — | Absolute http/https URL notified with the submission JSON each time the form is answered. |
3079
- | ​ ↳ `consumerAuth` | `string` | ❌ | — | `none`, `zapier` | Who may open the published form. `none` (the default) leaves it public to anyone with the link; `zapier` requires the visitor to be signed in to Zapier on the form's owning account. |
3080
- | ​ ↳ `document` | `object` | ❌ | — | — | Escape hatch: a complete form document tree, sent as-is. When supplied it replaces the document built from `fields`, and `title`, `description`, `confirmationTitle`, and `confirmationMessage` are ignored. Use only for structures the flat field list cannot express, such as approval decisions or multi-column row layout. |
3081
- | ​   ↳ `id` | `string` | ✅ | — | — | |
3082
- | ​   ↳ `type` | `string` | ✅ | — | `root` | |
3083
- | ​   ↳ `attrs` | `object` | ✅ | — | — | |
3084
- | ​     ↳ `schema_version` | `number` | ✅ | — | — | |
3085
- | ​     ↳ `title` | `string` | ✅ | — | — | |
3086
- | ​   ↳ `children` | `array` | ❌ | — | — | |
3098
+ | Name | Type | Required | Default | Possible Values | Description |
3099
+ | -------------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------- |
3100
+ | `options` | `object` | ✅ | — | — | |
3101
+ | ​ ↳ `sourceFiles` | `object` | ✅ | — | — | Exact TypeScript sources keyed by absolute logical path. |
3102
+ | ​ ↳ `entrypointFile` | `string` | ❌ | — | — | Absolute logical path of the entry file in sourceFiles. Defaults to /workflow.ts. |
3087
3103
 
3088
- **Returns:** `Promise<FormItem>`
3104
+ **Returns:** `Promise<WorkflowValidationItem>`
3089
3105
 
3090
- | Name | Type | Required | Possible Values | Description |
3091
- | ----------------------- | --------- | -------- | --------------- | ----------- |
3092
- | `data` | `object` | ✅ | — | |
3093
- | ​ ↳ `id` | `string` | ✅ | — | |
3094
- | ​ ↳ `title` | `string` | ✅ | — | |
3095
- | ​ ↳ `description` | `string` | ❌ | — | |
3096
- | ​ ↳ `hosted_url` | `string` | ✅ | — | |
3097
- | ​ ↳ `submission_count` | `number` | ✅ | — | |
3098
- | ​ ↳ `account_id` | `number` | ✅ | — | |
3099
- | ​ ↳ `owner_id` | `string` | ✅ | — | |
3100
- | ​ ↳ `created_at` | `string` | ✅ | — | |
3101
- | ​ ↳ `updated_at` | `string` | ✅ | — | |
3102
- | ​ ↳ `document` | `unknown` | ✅ | — | |
3103
- | ​ ↳ `last_published_at` | `string` | ✅ | — | |
3104
- | ​ ↳ `consumer_auth` | `unknown` | ✅ | — | |
3105
- | ​ ↳ `callback_url` | `unknown` | ✅ | — | |
3106
+ | Name | Type | Required | Possible Values | Description |
3107
+ | ---------------------- | ---------- | -------- | ---------------------------------- | ----------------------------------------------------------------------------------- |
3108
+ | `data` | `object` | ✅ | — | |
3109
+ | ​ ↳ `issues[]` | `object[]` | ✅ | — | Source diagnostics, or an empty array when validation passes. |
3110
+ | ​   ↳ `kind` | `string` | ✅ | — | Extensible diagnostic category; clients must accept unfamiliar values. |
3111
+ | ​   ↳ `message` | `string` | ✅ | — | Safe human-readable explanation. |
3112
+ | ​   ↳ `severity` | `string` | ✅ | `error`, `warning`, `info`, `hint` | Diagnostic severity. |
3113
+ | ​   ↳ `suggestion` | `string` | ❌ | — | Actionable fix hint. |
3114
+ | ​   ↳ `source` | `object` | ❌ | — | Affected source location. |
3115
+ | ​     ↳ `file_id` | `string` | ✅ | — | Source file containing the diagnostic. |
3116
+ | ​     ↳ `start_line` | `number` | ✅ | — | Inclusive 1-based start line. |
3117
+ | ​     ↳ `start_column` | `number` | ✅ | — | Inclusive 1-based start column. |
3118
+ | ​     ↳ `end_line` | `number` | ✅ | — | Inclusive 1-based end line. |
3119
+ | ​     ↳ `end_column` | `number` | ✅ | — | Inclusive 1-based end column. |
3120
+ | ​   ↳ `source_excerpt` | `string` | ❌ | — | Source text the diagnostic was raised against, truncated to 240 characters. |
3121
+ | ​   ↳ `syntax_kind` | `string` | ❌ | — | TypeScript AST node kind the diagnostic was raised against (e.g. `CallExpression`). |
3106
3122
 
3107
3123
  **Example:**
3108
3124
 
3109
3125
  ```typescript
3110
- const { data: form } = await zapier.createForm({
3111
- title: "example-title",
3126
+ const { data: workflowValidation } = await zapier.validateWorkflow({
3127
+ sourceFiles: {
3128
+ "/workflow.ts":
3129
+ 'import { defineDurable } from "@zapier/zapier-durable"; export default defineDurable("hello-world", async (ctx, input) => { return ctx.step("greet", async () => "Hello, world!"); });',
3130
+ },
3112
3131
  });
3113
3132
  ```
3114
3133
 
3115
3134
  ### Tables
3116
3135
 
3136
+ Tables is Zapier's database tool for storing and managing data. Use these to manage tables, their fields, and their records.
3137
+
3117
3138
  #### `createTable`
3118
3139
 
3119
3140
  Create a new table
@@ -3575,6 +3596,8 @@ const { data: records } = await zapier.updateTableRecords({
3575
3596
 
3576
3597
  ### Triggers
3577
3598
 
3599
+ A trigger is an event in an app that starts your automation, like a new email received. Use these to find an app's triggers and receive their events directly in your code, outside a Zap.
3600
+
3578
3601
  #### `ackTriggerInboxMessages`
3579
3602
 
3580
3603
  Acknowledge messages from a lease. Acked messages are removed from the inbox; unacked ones return to the available pool when the lease expires.
@@ -4377,6 +4400,8 @@ await zapier.watchTriggerInbox({
4377
4400
 
4378
4401
  ### Virtual File System (Experimental)
4379
4402
 
4403
+ The Virtual File System is file storage hosted by Zapier. Use these to read, write, and organize files and folders.
4404
+
4380
4405
  > ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
4381
4406
 
4382
4407
  #### `appendVfsFile` 🧪 _experimental_