> ## 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.

# Prompt-set analysis API and MCP

> Read prompt assessments, start an approved analysis and review proposals through REST or MCP.

For the interactive workflow, see [Prompt-set analysis](https://docs.devtune.ai/search-tracking/prompt-set-analysis.md).

The API and MCP run the same project workflow as the app, under the usual API plan requirements. Analyses can't be started from Slack or on a schedule. MCP code mode can run the start and review operations inside an approved execution; see [MCP server](https://docs.devtune.ai/api-reference/mcp-server.md#approved-writes).

| Operation | API v2 | MCP tool | Scope |
| - | - | - | - |
| Read results and credit estimate | `GET /projects/{projectId}/prompt-set-analysis` | `devtune_get_prompt_set_analysis` | `visibility.read` |
| Start or retry analysis | `POST /projects/{projectId}/prompt-set-analysis` | `devtune_start_prompt_set_analysis` | `actions.write` |
| Apply, undo, dismiss or restore | `POST /projects/{projectId}/prompt-set-analysis/proposals` | `devtune_review_prompt_set_proposal` | `actions.write` |

API paths above are relative to `/api/v2`. Changes require a credential tied to a user who can currently manage prompts. API keys act as their creator, and OAuth MCP connections act as the signed-in user. A key without a creator can read, if its scopes allow, but cannot make changes.

### Human approval

Agents must show the human the estimate before starting analysis, and the proposal and requested operation before changing a proposal. Obtain explicit approval first. A read, analysis request or earlier approval of a different proposal does not approve a mutation.

After obtaining that approval, start the analysis, replacing `0.5` with the exact `creditState.estimatedCredits` value the human approved:

```bash theme={null}
curl -X POST -H "Authorization: Bearer dtk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"humanApproved": true, "approvedEstimatedCredits": 0.5}' \
  "https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/prompt-set-analysis"
```

The response's `data.run` is the analysis run; read its progress and proposals with `GET` on the same path. If the estimate changes before the start, the request returns 409; read the current estimate and obtain approval again. For review, send:

```json theme={null}
{
  "proposalId": "00000000-0000-4000-8000-000000000001",
  "operation": "apply",
  "humanApproved": true
}
```

`humanApproved` attests that the caller obtained human approval. It is not permission for an agent to approve its own output. `operation` also accepts `undo`, `dismiss` and `restore`. Restore returns the proposal to review without applying it.

### Results and pagination

Reads return `run`, `proposals`, `latestCompletedAnalysis`, `creditState` and `pagination`. A missing latest analysis returns `run: null`. A requested run that does not exist in the project returns 404. `meteredCredits: null` means settlement is not available yet.

Use `pageSize` or `limit` from 1 to 100 (default 25). Both assessments and proposals are paginated. While `pagination.hasMore` is true, pass `pagination.nextCursor` as `cursor`; the cursor stays on the run the first page read, even when a newer analysis starts. `nextOffset` with `offset` and `runId` still works and is deprecated. An exhausted collection can be empty while the other still has another page. Proposal states may change during review; refresh before acting.

Invalid credentials return 401. A missing scope, or a member who can't manage prompts, returns 403. Insufficient credits return 402. Starting an analysis shares the [agent-run rate limit](https://docs.devtune.ai/api-reference/rate-limits.md) and returns 429 when it is reached. Stale or conflicting proposals return 409; refresh and review the current state before retrying.


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