Approve a change and publish it

POST
/v1/agents/{id}/proposals/{pid}/approve

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.

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.

pid*string

The proposal id.

Request Body

application/json
  1. body
note?string

A note kept with the decision.

Lengthlength <= 500

Response Body

The proposal, now shipped: the change is published

application/json
  1. response
proposal*
Example Request
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"  }}