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

# Human approval

> Which steps only a person can take in DevTune, which a credential can take on its own, and which approvals the caller attests to.

Use this page to decide what your agent may do on its own and where a person has to act. A few steps need a person signed in to DevTune, GitHub or GitBook. Everything else a credential with the right scope can do by itself; for some of those writes, DevTune checks only that your agent says a person approved.

Most writes act as the person who created the API key or signed in to the OAuth connection. That person answers for what their agent sends, including an approval it attests to. Attaching a Results URL or claiming or unclaiming a detected content change requires Member or higher on the project, or ownership of the personal account for a personal API key. See [Code mode operations](https://docs.devtune.ai/api-reference/mcp-code-mode.md#other-writes) for the roles other writes require.

## Steps only a person can take

| Step | Who can act | What DevTune checks |
| - | - | - |
| Merging a pull request or change request | Whoever your GitHub repository or GitBook space lets merge | DevTune never merges. It writes only to its own `devtune/action-…` branch or change request |
| Granting `agents.review` | The person creating or editing an API key in **Settings**, or approving an OAuth connection | The scope starts unselected, and a claimed [agent registration](https://docs.devtune.ai/api-reference/agent-registration.md) never receives it |
| Claiming an agent registration | The signed-in DevTune user with the claim's email, who manages the team's settings | They enter the 6-digit code DevTune emailed them. Five wrong codes lock the attempt |
| Approving or discarding an agent draft in the app or in Slack | A project Member or Admin; in Slack, with a linked Slack identity, for a run started from a Slack thread | The project Member role or above, checked on every decision |
| Applying a prompt change Dex proposes on a card | The member who owns the Dex chat, in the app | The member can manage prompts, and the card still matches the proposal. Cards can't be decided over the API, MCP or Slack |

DevTune doesn't publish or edit your live site. A content draft becomes a pull request on your content repository or a change request in your GitBook space, opened by you or, if you turn it on, automatically. See [GitHub pull requests](https://docs.devtune.ai/integrations/github-pull-requests.md) and [GitBook change requests](https://docs.devtune.ai/integrations/gitbook-change-requests.md).

## Steps a credential can take on its own

These need the right scope and pass the checks each operation lists. No person has to see the change.

* **Approving or dismissing an agent draft** with [Review a managed-agent draft](https://docs.devtune.ai/api-reference/review-a-managed-agent-draft.md) or `devtune_review_agent_run`, given `agents.review`. The decision is recorded against the key's creator or the signed-in member. Code mode can't review drafts. Grant `agents.review` only to an agent you trust to decide for its owner.
* **Adding or deleting tracked prompts** with `devtune_create_prompt`, `devtune_delete_prompt`, their REST endpoints or code mode. Only Dex's own proposals wait on a card.
* **Confirming a Dex handoff** with `devtune_decide_dex_handoff` or its REST endpoint, which starts the specialist run and spends credits.
* **Starting a credit-spending run** against an estimate (see [Credit estimates](#credit-estimates)).
* **Any write that takes an attestation field** (see [Approvals the caller attests to](#approvals-the-caller-attests-to)).

## Credit estimates

Some starts spend credits only against an estimate the caller passes back. DevTune checks the estimate, not that a person saw it.

* **Prompt-set analysis.** `approvedEstimatedCredits` must equal the current `creditState.estimatedCredits`. A changed estimate returns 409, and nothing starts. See [Prompt-set analysis](https://docs.devtune.ai/api-reference/prompt-set-analysis.md#human-approval).
* **Agent Picks tests and schedules.** A start needs a `quote_token` from an earlier quote and a `max_credits` ceiling. It returns 409 `estimate_changed` when the setup or baseline changed since the quote, and 409 `over_max_credits` when the fresh high estimate is above `max_credits`. A test token starts one test; a retry with it returns that test while it is queued or running, and 409 `test_finished` once it has ended. A schedule token saves once; reusing it returns 409 `quote_token_used`. See [Start a test](https://docs.devtune.ai/agent-picks/api-and-mcp.md#start-a-test).

Code mode can't start an Agent Picks test or turn on a schedule, so one execution can't quote and spend.

## Approvals the caller attests to

These fields carry your agent's statement that a person approved or confirmed. DevTune refuses the request without them, but only checks their value.

| Field | Where | Send it after a person approves |
| - | - | - |
| `humanApproved` | Writes in [MCP code mode](https://docs.devtune.ai/api-reference/mcp-server.md#approved-writes), with `executionId` | the exact changes the program makes |
| `humanApproved` | [Prompt-set analysis](https://docs.devtune.ai/api-reference/prompt-set-analysis.md#human-approval) start and proposal review | the credit estimate, or the proposal and operation |
| `acknowledgeHighStakes` | `accept` on a high-stakes page, in [Change an action status](https://docs.devtune.ai/api-reference/change-an-action-status.md) or `devtune_change_action_status` | the change to that page |
| `acknowledgedHighStakes` | Creating an action for a high-stakes page from a prompt, with `devtune_create_prompt_action` or its REST endpoint | the change to that page |
| `acknowledgeHighStakes` | Creating an action for a high-stakes page from an Audit finding, in [Create an action from an Audit finding](https://docs.devtune.ai/api-reference/create-an-action-from-an-audit-finding.md) or `devtune_create_action_from_audit_finding` | the change to that page |
| `confirmedIntent` | [Acknowledge or reconsider a retrieval restriction](https://docs.devtune.ai/api-reference/acknowledge-or-reconsider-a-retrieval-restriction.md) and the matching MCP tools | the restriction is, or is no longer, intentional |
| `confirm` | [Archive a brand](https://docs.devtune.ai/api-reference/archive-a-brand.md) or `devtune_delete_brand` on a current positioning competitor | archiving it and the change to future comparisons |

Other write tools, such as claiming a detected content change, ask your agent to get approval first but have no approval field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.