docs(openapi): add Human in the Loop API endpoints

[waleedlatif1]

Summary

• Add HITL pause/resume endpoints to OpenAPI spec
• New endpoints: list paused executions, get paused execution detail, get pause context, resume execution
• New schemas: PausedExecutionSummary, PausedExecutionDetail, PausePoint, PauseContextDetail, ResumeQueueEntry, ResumeResult
• Covers all response variants (sync, async, stream, queued, started)
• Includes parallelScope/loopScope fields for pause points in parallel branches and loops

Type of Change

• Documentation update

Testing

Validated JSON structure, all $ref targets resolve, verified against source route handlers and TypeScript interfaces

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Apr 9, 2026 8:57pm

[cursor]

PR Summary

Low Risk
Documentation-only update to apps/docs/openapi.json; primary risk is client confusion if the spec diverges from actual API behavior (new endpoints/response variants and added error responses).

Overview
Adds a new Human in the Loop section to the OpenAPI spec, documenting endpoints to list paused executions for a workflow, fetch paused execution details (including snapshot/queue), fetch a specific pause context, and resume an execution by posting input via resume URLs.

Introduces new schemas (PausedExecutionSummary, PausedExecutionDetail, PausePoint, PauseContextDetail, ResumeQueueEntry, ResumeResult) and documents multiple resume response modes (sync result vs queued/started vs async 202 with statusUrl), along with expanded examples and additional error responses on affected routes.

^{Reviewed by Cursor Bugbot for commit 149ad9f. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds OpenAPI documentation for five new Human in the Loop endpoints covering listing paused executions, retrieving execution detail, and resuming executions with input. The 403 and 500 gaps identified in the previous review round have been addressed. A few minor spec gaps remain.

Confidence Score: 5/5

Safe to merge — documentation-only change with no runtime impact; remaining findings are P2 spec completeness improvements.

All blocking gaps from the previous review round (missing 403 and explicit 500 responses) have been resolved. The two remaining findings are minor omissions: a missing implicit 500 on one GET endpoint and the undocumented streaming response variant (consistent with the existing executeWorkflow spec pattern). Neither affects correctness of the implementation or blocks merge.

apps/docs/openapi.json — POST resume streaming response and GET paused/{executionId} 500 entry.

Vulnerabilities

No security concerns identified. This is a documentation-only change to the OpenAPI spec with no executable code.

Important Files Changed

Filename	Overview
apps/docs/openapi.json	Adds five HITL endpoints with six new schemas; 403 and explicit 500 gaps from prior review are addressed; minor gap remains: GET /api/workflows/{id}/paused/{executionId} is missing a 500 entry, and the streaming response for POST resume is undocumented.

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant PauseResumeManager

    Client->>API: GET /api/workflows/{id}/paused
    API->>PauseResumeManager: listPausedExecutions()
    PauseResumeManager-->>API: PausedExecutionSummary[]
    API-->>Client: 200 { pausedExecutions: [...] }

    Client->>API: GET /api/workflows/{id}/paused/{executionId}
    API->>PauseResumeManager: getPausedExecutionDetail()
    PauseResumeManager-->>API: PausedExecutionDetail | null
    API-->>Client: 200 PausedExecutionDetail / 404

    Client->>API: GET /api/resume/{workflowId}/{executionId}
    API->>PauseResumeManager: getPausedExecutionDetail()
    PauseResumeManager-->>API: PausedExecutionDetail | null
    API-->>Client: 200 PausedExecutionDetail / 404 / 500

    Client->>API: GET /api/resume/{workflowId}/{executionId}/{contextId}
    API->>PauseResumeManager: getPauseContextDetail()
    PauseResumeManager-->>API: PauseContextDetail | null
    API-->>Client: 200 PauseContextDetail / 404

    Client->>API: POST /api/resume/{workflowId}/{executionId}/{contextId}
    API->>PauseResumeManager: enqueueOrStartResume()
    alt queued
        API-->>Client: 200 { status: queued, queuePosition }
    else sync
        API-->>Client: 200 ResumeResult
    else stream
        API-->>Client: 200 text/event-stream (SSE — undocumented)
    else async
        API-->>Client: 202 AsyncExecutionResult
    else fire-and-forget
        API-->>Client: 200 { status: started }
    end

Loading

_{Reviews (2): Last reviewed commit: "lint" | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 149ad9f. Configure here.}