> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/interfaces-and-conversations/human-input-and-approval-controls.md).

# Human Input and Approval Controls

Human-input controls pause a workflow for a person’s response or approval. Use them when the next step requires a deliberate decision.

![Send the person’s decision to the paused run](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FikbjdZupC3zTZJrJfpY8%2Fhuman-input-and-approval-controls.png?alt=media)

Authenticated v2 operation excerpt. Use the response form required by the pending step. Do not create a second run to answer a paused run, and do not reuse a consumed token. Follow the same run after resumption is accepted.

<details>

<summary>Copy the example</summary>

```http
# First display the pending decision to the intended person.
# Then submit that person's response for this pause only.
POST /v2/runs/{run_id}/resume
Content-Type: application/json

{
  "resume_token": "<token-for-this-pending-request>",
  "response": "<the-persons-response>"
}

GET /v2/runs/{run_id}
```

</details>

## Before you begin

A workflow with a supported human-input step and permission to respond.

## Key concepts

| Term          | Definition                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Paused        | A run state that waits for a supported response before it can continue. Respond to the existing run instead of starting a new one.                                |
| Response type | The supported form of human input, such as text, approval, or choice. Match the submitted response to the pending request’s requirements.                         |
| Resume token  | A value supplied for a particular pending human-input request. Use it for that request only and keep it out of logs or public links.                              |
| Interface     | The user-facing form, chat, batch view, or other supported access surface for a project. Its fields and security settings are distinct from editing the workflow. |
| Side effect   | A change outside the returned answer, such as creating a record or sending email. Cancellation or release rollback does not undo a completed side effect.         |

## Respond to a request for human input

1. Configure the prompt and supported response type.
2. Run the workflow until it pauses and display the available options.
3. Submit the response for that pending request and follow the same run to its next state.

The workflow continues with the person’s recorded response.

## Behavior and limitations

Approval applies to the pending request, not to every later action. An expired or already-used response token cannot be reused. Do not start another run to answer a paused one. Keep the decision wording clear about what the following step will do.

## Related resources

[Interface Inputs and Output Mapping](/technical-reference/interfaces-and-conversations/interface-inputs-and-output-mapping.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/interfaces-and-conversations/human-input-and-approval-controls.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.