List an agent's proposed changes

GET
/v1/agents/{id}/proposals

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.

Authorization

apiKey
headerAuthorizationBearer <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.

Path Parameters

id*string

The agent id.

Query Parameters

status?string

Only proposals in this status.

Value in"drafted""testing""ready""approved""shipped""rejected""superseded""refused"
problemId?string

Only proposals for this problem.

Formatuuid
cursor?string

The nextCursor of the previous page.

Lengthlength <= 512
limit?integer

How many items to return, 1–100. Default 25.

Range1 <= value <= 100

Response Body

A page of the agent's proposed changes, newest first

application/json
  1. response
proposals*array<>
nextCursor*string|null
Example Request
curl "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}