> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vyomflow.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/concepts/runs), 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.

<Note>
  This page uses the public, API-key-authenticated surface at `https://api.vyomflow.co.in/api/public/v1` — see [Authentication](/authentication).
</Note>

## 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](/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

```text theme={null}
POST /api/public/v1/waitpoints/{waitpointId}/respond
```

### Examples

<CodeGroup>
  ```bash cURL — CREDIT_APPROVAL theme={null}
  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}'
  ```

  ```bash cURL — CLARIFICATION theme={null}
  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": "CLARIFICATION", "answer": "Yes, proceed with that plan."}'
  ```

  ```js JavaScript theme={null}
  const res = await fetch(
    'https://api.vyomflow.co.in/api/public/v1/waitpoints/wp_abc123/respond',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.VYOMFLOW_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ kind: 'CREDIT_APPROVAL', approved: true }),
    }
  );
  const data = await res.json();
  ```
</CodeGroup>

<Note>
  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`.
</Note>

## Next steps

* Learn how runs work and how to cancel one in [Runs](/concepts/runs)
* Review the [Errors](/errors) page for response codes you may see when responding to a waitpoint