Draft a fix, or test your own change

POST
/v1/agents/{id}/proposals

Starts a proposed change. With problemId the platform drafts a new prompt from the problem's name and counts and the prompt you have now: no conversation text reaches the drafting model. With change you give the new prompt yourself and ask for evidence on it. Either way the draft and the replays of real conversations on both versions are charged, so quote.maxUsd is the most it can cost. Pass quoteOnly to get the price and start nothing; pass quotedMaxUsd to refuse a price that moved (409 price_changed). A prompt owned by an agent's code answers 422 field_code_owned.

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.

Request Body

application/json
  1. body
problemId?string

The problem to draft a fix for. Give this or change.

Formatuuid
change?

The new prompt, as { "kind": "system_prompt", "text": "..." }. Give this or problemId.

quoteOnly?boolean

Answer the price and start nothing.

quotedMaxUsd?number

The most you saw and agreed to. A start whose ceiling is now higher is refused price_changed.

Range0 <= value

Response Body

The most the draft and its replays can cost, and the proposal once it is started

application/json
  1. response
quote*
proposal*|null
Example Request
curl -X POST "https://api.vlayers.ai/v1/agents/$AGENT_ID/proposals" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "problemId": "3f1c0a52-7d41-4b8e-9a3e-5c2b6d1f0a77",    "quoteOnly": true  }'
Example Response
{  "quote": {    "maxUsd": 1.4,    "typicalUsd": 0.4,    "draftMaxUsd": 0.2,    "evidenceMaxUsd": 1.2  },  "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": "testing",    "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"  }}