feat(api): add v2 workflow resume endpoint

Author: TheodoreSpeaks

apps/docs/content/docs/en/workflows/blocks/human-in-the-loop.mdx

@@ -88,14 +88,15 @@ Access resume data in downstream blocks using `<blockId.fieldName>`.
   <Tab>
     ### REST API
 
-    Programmatically resume workflows using the resume endpoint. The `contextId` is available from the block's `resumeEndpoint` output or from the `_resume` object in the paused execution response.
+    Programmatically resume workflows through the v2 execution resource. The `contextId` is available from the block's `resumeEndpoint` output or from the `_resume` object in the paused execution response.
 
     ```bash
-    POST /api/resume/{workflowId}/{executionId}/{contextId}
+    POST /api/v2/workflows/{workflowId}/executions/{executionId}/resume
     Content-Type: application/json
     X-API-Key: your-api-key
 
     {
+      "contextId": "<contextId>",
       "input": {
         "approved": true,
         "comments": "Looks good to proceed"
@@ -109,11 +110,16 @@ Access resume data in downstream blocks using `<blockId.fieldName>`.
 
     ```json
     {
-      "success": true,
-      "status": "completed",
-      "executionId": "<resumeExecutionId>",
-      "output": { ... },
-      "metadata": { "duration": 1234, "startTime": "...", "endTime": "..." }
+      "data": {
+        "executionId": "<resumeExecutionId>",
+        "workflowId": "<workflowId>",
+        "status": "completed",
+        "output": { ... },
+        "error": null,
+        "startedAt": "...",
+        "endedAt": "...",
+        "durationMs": 1234
+      }
     }
     ```
 
@@ -125,11 +131,10 @@ Access resume data in downstream blocks using `<blockId.fieldName>`.
 
     ```json
     {
-      "success": true,
-      "async": true,
-      "executionId": "<resumeExecutionId>",
-      "message": "Resume execution queued",
-      "statusUrl": "/api/v2/workflows/<workflowId>/executions/<resumeExecutionId>"
+      "data": {
+        "executionId": "<resumeExecutionId>",
+        "statusUrl": "/api/v2/workflows/<workflowId>/executions/<resumeExecutionId>"
+      }
     }
     ```
 
@@ -143,6 +148,14 @@ Access resume data in downstream blocks using `<blockId.fieldName>`.
     ```
 
     Returns the execution status and, when completed, the full workflow output.
+
+    The legacy endpoint remains available without behavior changes for existing integrations:
+
+    ```bash
+    POST /api/resume/{workflowId}/{executionId}/{contextId}
+    ```
+
+    Its async response continues to expose `jobId` and the legacy `/api/jobs/{jobId}` polling URL.
 
     To check on a paused execution's pause points and resume links:
 

apps/docs/openapi-core.json

@@ -914,9 +914,10 @@
                 "example": {
                   "success": true,
                   "async": true,
+                  "jobId": "job_4a3b2c1d0e",
                   "executionId": "f0b3d8c2-7e5a-4b9d-8c1f-6a4e2d0b9c58",
                   "message": "Resume execution queued",
-                  "statusUrl": "https://www.sim.ai/api/v2/workflows/81f661e1-d704-4861-b5c1-5bb3cf57e6a7/executions/f0b3d8c2-7e5a-4b9d-8c1f-6a4e2d0b9c58"
+                  "statusUrl": "https://www.sim.ai/api/jobs/job_4a3b2c1d0e"
                 }
               }
             }

apps/docs/openapi-v2-workflows.json

@@ -1536,6 +1536,173 @@
         }
       }
     },
+    "/api/v2/workflows/{id}/executions/{executionId}/resume": {
+      "post": {
+        "operationId": "resumeWorkflowExecutionV2",
+        "summary": "Resume a workflow execution",
+        "description": "Resumes one human-in-the-loop pause context on the parent execution. The resumed attempt receives a new execution ID. Sync attempts return the execution resource, stream attempts return Server-Sent Events, and async or serialized attempts return a 202 receipt whose `statusUrl` is the v2 execution resource.",
+        "tags": ["Workflows"],
+        "security": [
+          {
+            "apiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/WorkflowId"
+          },
+          {
+            "name": "executionId",
+            "in": "path",
+            "required": true,
+            "description": "The execution ID of the paused parent run.",
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "The pause context to resume and its optional input. Bodies over 10 MB and unknown keys are rejected.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["contextId"],
+                "properties": {
+                  "contextId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The context ID of the human-in-the-loop pause point."
+                  },
+                  "input": {
+                    "description": "Input supplied to the paused block."
+                  }
+                }
+              },
+              "example": {
+                "contextId": "ctx_123",
+                "input": {
+                  "approved": true,
+                  "comments": "Looks good to proceed"
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The completed, failed, paused, or cancelled resume execution resource.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["data"],
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/ExecutionResource"
+                    }
+                  }
+                },
+                "example": {
+                  "data": {
+                    "executionId": "resume_exec_1",
+                    "workflowId": "wf_123",
+                    "status": "completed",
+                    "output": {
+                      "result": "approved"
+                    },
+                    "error": null,
+                    "durationMs": 420
+                  }
+                }
+              }
+            }
+          },
+          "202": {
+            "description": "The resume is queued. Poll `statusUrl` using the returned resume execution ID.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["data"],
+                  "properties": {
+                    "data": {
+                      "type": "object",
+                      "required": ["executionId", "statusUrl"],
+                      "properties": {
+                        "executionId": {
+                          "type": "string"
+                        },
+                        "statusUrl": {
+                          "type": "string"
+                        },
+                        "queuePosition": {
+                          "type": "integer",
+                          "minimum": 1
+                        }
+                      }
+                    }
+                  }
+                },
+                "example": {
+                  "data": {
+                    "executionId": "resume_exec_1",
+                    "statusUrl": "https://www.sim.ai/api/v2/workflows/wf_123/executions/resume_exec_1"
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "description": "The pause context cannot be resumed in its current state.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "413": {
+            "$ref": "#/components/responses/PayloadTooLarge"
+          },
+          "423": {
+            "$ref": "#/components/responses/Locked"
+          },
+          "429": {
+            "$ref": "#/components/responses/RateLimited"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalError"
+          },
+          "503": {
+            "description": "Resume execution infrastructure temporarily unavailable.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v2/workflows/{id}/executions/{executionId}/cancel": {
       "post": {
         "operationId": "cancelExecutionV2",

apps/docs/openapi.json

@@ -874,9 +874,10 @@
                 "example": {
                   "success": true,
                   "async": true,
+                  "jobId": "job_4a3b2c1d0e",
                   "executionId": "f0b3d8c2-7e5a-4b9d-8c1f-6a4e2d0b9c58",
                   "message": "Resume execution queued",
-                  "statusUrl": "https://www.sim.ai/api/v2/workflows/81f661e1-d704-4861-b5c1-5bb3cf57e6a7/executions/f0b3d8c2-7e5a-4b9d-8c1f-6a4e2d0b9c58"
+                  "statusUrl": "https://www.sim.ai/api/jobs/job_4a3b2c1d0e"
                 }
               }
             }

apps/sim/app/api/resume/[workflowId]/[executionId]/[contextId]/route.test.ts

@@ -58,6 +58,7 @@ vi.mock('@/lib/workflows/executor/human-in-the-loop-manager', () => ({
 }))
 
 import { GET, POST } from '@/app/api/resume/[workflowId]/[executionId]/[contextId]/route'
+import { handleResumeExecution } from '@/app/api/resume/resume-handler'
 
 const WORKFLOW_ID = 'workflow-1'
 const EXECUTION_ID = 'execution-1'
@@ -240,7 +241,7 @@ describe('POST /api/resume/[workflowId]/[executionId]/[contextId]', () => {
     })
   })
 
-  it('returns the resume execution ID as the only public async polling handle', async () => {
+  it('preserves the legacy async job polling response', async () => {
     mockGetPausedExecutionDetail.mockResolvedValueOnce(
       createPausedExecution({ executionMode: 'async' })
     )
@@ -257,6 +258,52 @@ describe('POST /api/resume/[workflowId]/[executionId]/[contextId]', () => {
 
     const response = await POST(request, context)
 
+    expect(response.status).toBe(202)
+    await expect(response.json()).resolves.toEqual({
+      success: true,
+      async: true,
+      jobId: 'resume-execution:resume-execution-1',
+      executionId: 'resume-execution-1',
+      message: 'Resume execution queued',
+      statusUrl: 'https://test.sim.ai/api/jobs/resume-execution:resume-execution-1',
+    })
+    expect(mockEnqueueResume).toHaveBeenCalledWith(
+      'resume-execution',
+      expect.objectContaining({ resumeExecutionId: 'resume-execution-1' }),
+      expect.objectContaining({
+        metadata: expect.objectContaining({ workflowId: WORKFLOW_ID }),
+      })
+    )
+    expect(mockEnqueueResume.mock.calls[0]?.[2]).not.toHaveProperty('jobId')
+  })
+
+  it('uses deterministic dispatch and execution polling for the v2 surface', async () => {
+    mockGetPausedExecutionDetail.mockResolvedValueOnce(
+      createPausedExecution({ executionMode: 'async' })
+    )
+    mockEnqueueOrStartResume.mockResolvedValueOnce({
+      status: 'started',
+      resumeExecutionId: 'resume-execution-1',
+      resumeEntryId: 'resume-entry-1',
+      pausedExecution: { id: 'paused-execution-1' },
+      contextId: CONTEXT_ID,
+      resumeInput: { approved: true },
+      userId: 'current-api-key-user',
+    })
+    const { request } = makeRequest()
+
+    const response = await handleResumeExecution({
+      request,
+      workflowId: WORKFLOW_ID,
+      executionId: EXECUTION_ID,
+      contextId: CONTEXT_ID,
+      workspaceId: WORKSPACE_ID,
+      userId: 'current-api-key-user',
+      resumeInput: { approved: true },
+      isApiCaller: true,
+      pollingSurface: 'v2',
+    })
+
     expect(response.status).toBe(202)
     await expect(response.json()).resolves.toEqual({
       success: true,