# Draft a fix, or test your own change

Source: https://docs.vlayers.ai/reference/agents/draft-agent-proposal

`POST /v1/agents/{id}/proposals` · scope `workspace:write`

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.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The agent id. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `problemId` | body | string | no | The problem to draft a fix for. Give this or `change`. |
| `change` | body | object | no | The new prompt, as `{ "kind": "system_prompt", "text": "..." }`. Give this or `problemId`. |
| `quoteOnly` | body | boolean | no | Answer the price and start nothing. |
| `quotedMaxUsd` | body | number | no | The most you saw and agreed to. A start whose ceiling is now higher is refused `price_changed`. |

## Request

cURL:

```bash
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
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { quote } = await voicelayer.agents.draftProposal('<agent-id>', {
  problemId: '3f1c0a52-7d41-4b8e-9a3e-5c2b6d1f0a77',
  quoteOnly: true
});
console.log(quote.maxUsd);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.agents.draft_proposal(
    "<agent-id>",
    problem_id="3f1c0a52-7d41-4b8e-9a3e-5c2b6d1f0a77",
    quote_only=True,
)
print(result.quote.max_usd)
```

## Response `202`

```json
{
  "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"
  }
}
```
