Skip to main content
For the interactive workflow, see Prompt-set analysis. 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. 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:
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:
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 and returns 429 when it is reached. Stale or conflicting proposals return 409; refresh and review the current state before retrying.