Waitpoints: Pause a Run for Human Input

Waitpoints let a running agent pause and wait for external input before continuing. Learn how to detect and respond to waitpoints.

During a run, the agent may emit a waitpoint when it needs a human response before continuing. This is useful for approval flows, clarifying questions, or any scenario where the agent cannot proceed autonomously.

This page uses the public, API-key-authenticated surface at https://api.vyomflow.co.in/api/public/v1 — see Authentication.

Kinds

There are two kinds of waitpoint, each with its own request/response shape:

• CREDIT_APPROVAL — the agent wants to run a tool that will consume more credits than the auto-approval threshold. Request payload: { toolName, estimatedCredits, threshold }. You respond with { approved: true | false }.
• CLARIFICATION — the agent needs additional information to proceed. Request payload: { question, options? }. You respond with { answer: "<text>" }.

When waitpoints appear

The event stream (Streaming) emits a waitpoint.created event carrying the waitpoint’s id, kind, and request payload. While the waitpoint is open, the run stays in the waiting status. The run resumes only after you respond to the waitpoint or cancel the run. A waitpoint.resolved event follows once it’s answered.

Responding to a waitpoint

Send your response with a single POST call (requires the waitpoints:respond scope). The run resumes automatically once the API receives it. Responding is idempotent — a repeat call on an already-resolved waitpoint still returns 200 with its current state, not an error.

Endpoint

POST /api/public/v1/waitpoints/{waitpointId}/respond

Examples

cURL — CREDIT_APPROVAL

curl -X POST https://api.vyomflow.co.in/api/public/v1/waitpoints/wp_abc123/respond \
  -H "Authorization: Bearer $VYOMFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "CREDIT_APPROVAL", "approved": true}'

A waitpoint is owned by the same user as its parent run. If you try to respond with a different user’s key, the API returns 404 Not Found instead of 403 Forbidden.

Next steps

• Learn how runs work and how to cancel one in Runs
• Review the Errors page for response codes you may see when responding to a waitpoint