Approve a change and publish it
POST
Publishes the proposal's prompt as the agent's next version, under the same permission and balance rules as publishing. It never ships over a newer publish: if the published version moved since the proposal was drafted the answer is 409 proposal_stale and the proposal is superseded. Your own unpublished draft is left as you wrote it. A change that widens what the agent can do needs you here: it never ships by text or on its own.
Requires an API key with the workspace:write 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.
pid*stringThe proposal id.
application/json- body
note?stringA note kept with the decision.
Length
length <= 500The proposal, now shipped: the change is published
application/json- response
proposal*curl -X POST "https://api.vlayers.ai/v1/agents/$AGENT_ID/proposals/$PROPOSAL_ID/approve" \ -H "Authorization: Bearer $VOICELAYER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "note": "Looks right." }'Example Response
{ "proposal": { "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": "shipped", "decision": { "by": { "kind": "user", "id": "user_2abc" }, "door": "dashboard", "at": "2026-10-20T15:04:05.000Z", "refusalCode": null, "shippedVersionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012" }, "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" }}