List an agent's proposed changes
GET
The changes proposed for an agent's prompt, newest first: drafted by the improvement loop for a problem, or written by a person. Each carries its status, the replays before and after and the decision.
Requires an API key with the workspace:read scope.
apiKeyheader
AuthorizationBearer <token>A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.
id*stringThe agent id.
status?stringOnly proposals in this status.
Value in
"drafted""testing""ready""approved""shipped""rejected""superseded""refused"problemId?stringOnly proposals for this problem.
Format
uuidcursor?stringThe nextCursor of the previous page.
Length
length <= 512limit?integerHow many items to return, 1–100. Default 25.
Range
1 <= value <= 100A page of the agent's proposed changes, newest first
application/json- response
proposals*array<>nextCursor*string|nullcurl "https://api.vlayers.ai/v1/agents/$AGENT_ID/proposals?status=ready" \ -H "Authorization: Bearer $VOICELAYER_API_KEY"Example Response
{ "proposals": [ { "id": "0192f5fe-2736-7184-8d34-56789abcdef0", "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78", "baseVersionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012", "draftVersionId": "0192f5fb-f403-7e51-9a01-23456789abcd", "problemId": "0192f5fd-1625-7073-9c23-456789abcdef", "change": { "kind": "system_prompt", "text": "You are the booking assistant. When asked about availability, check it before answering." }, "source": { "kind": "improvement", "ref": "0192f5fd-1625-7073-9c23-456789abcdef" }, "reason": "Tells the agent to check availability before answering.", "evidence": { "before": [ "0192f5fa-e3f2-7d40-8f90-0123456789ab" ], "after": [ "0192f5f8-c1d0-7b2e-8d7e-8f9012345678" ], "distinctContacts": 9, "ownerCases": 5 }, "evidenceResult": { "problemCases": { "cases": 9, "passedBefore": 3, "passedAfter": 8 }, "regressions": 0, "refused": 0 }, "costEffect": { "beforeUsdPerSuccess": 0.12, "afterUsdPerSuccess": 0.1, "basis": "runs", "pricedFieldsChanged": [] }, "widening": { "capabilitiesAdded": [], "crossingsAdded": [], "widens": false }, "approvers": { "userIds": null }, "status": "ready", "decision": { "by": null, "door": null, "at": null, "refusalCode": null, "shippedVersionId": null }, "autoShip": null, "draftDiverged": false, "quote": { "maxUsd": 1.4, "typicalUsd": 0.4 }, "spentUsd": 0.38, "createdBy": "user_2abc", "createdAt": "2026-10-20T15:04:05.000Z", "updatedAt": "2026-10-20T15:04:05.000Z", "expiresAt": "2026-10-20T15:04:05.000Z" } ], "nextCursor": null}