# PoliteChase draft API v1 (preview)

Base URL: `https://politechase.com`. A locally installed preview can override it with `POLITECHASE_BASE_URL` or `configure --base-url http://localhost:3000`. Only HTTPS or loopback HTTP is accepted. The production endpoint requires a deployment containing this feature.

- `GET /api/agent/usage`: Bearer token; returns plan, used, remaining, limit and reset timestamp. No charge.
- `POST /api/agent/drafts`: Bearer token, JSON body, UUID `Idempotency-Key` header.
- Keys are issued/revoked from the signed-in settings page, not from these Bearer endpoints.

Required fields: `clientName`, `senderName`, `work`, `amount` (include currency), `situation`.

`situation`: `before_due`, `overdue`, `no_agreed_date`, `promised_payment`, `claimed_paid`, `disputed`.
Optional: `channel` (`email` or `message`, default email), `tone` (`friendly`, `neutral`, `firm`, default friendly), `dueDate`, `relationship`, `region`, `context` (all strings). Do not invent absent facts. For money not yet agreed, clarify the amount before calling.

Example synthetic input:

```json
{
  "clientName": "Alex",
  "senderName": "Sam",
  "work": "Website design final balance",
  "amount": "USD 500",
  "situation": "no_agreed_date",
  "channel": "email",
  "context": "Work was accepted. No payment date was agreed. Ask for a date."
}
```

Success: `{ "ok": true, "requestId": "...", "draft": { "subject": "...", "message": "...", "reasons": ["..."], "checkBeforeSending": ["..."] }, "replayed": false, "usage": { "remaining": 4 } }` (other usage fields omitted here).

Error: `{ "ok": false, "error": { "code": "...", "message": "..." } }`.

- 400: invalid input/request ID. Correct it before making a new call.
- 401/403: configure a valid key / verify the account. Never ask for a password or key in chat.
- 402: allowance exhausted. Stop; no automatic payment.
- 409 `request_in_progress`: wait, then retry once with the same ID and input.
- 409 `idempotency_conflict`: changed input with a reused ID. Do not reuse that ID.
- 409 `request_failed` / `request_expired`: no charge; a new ID can start a new attempt if the user still wants it.
- 429: five new requests/minute/account; respect `Retry-After`.
- Network/5xx: outcome may be unknown; retry the same ID once. Never create a new ID merely because the response was lost.

Preview limits: five lifetime drafts per verified account; an eligible existing Personal subscription includes 100 drafts per subscription period. Limits are shared across key rotation. Pending requests temporarily reserve capacity. Failed requests do not consume drafts. Replaying a saved successful request does not consume a second draft. No standalone credit-pack purchase or MCP transport is included in this version.