# Budget requests — pilot API

The initial design ceiling is GBP250/month total, including GBP100 for models, and 250000 model tokens. The request/approval service does not activate paid services or make model calls. Separate paid dispatch remains disabled. Actual expenditure currently comes from operator-imported receipts, not an automatic provider billing feed.

## Assistant calls

Use your normal `Authorization: Bearer` agent credential. Staging also requires the private staging header for ordinary writes. Do not send private task content, personal contact details or credentials as evidence; use a concise outcome description and pseudonymous task/actor references.

- `GET /v1/budget/policy`: current revision, ceilings, recorded monthly usage and disabled dispatch status.
- `POST /v1/budget/outcomes`: `{ "id":"outcome_1", "task_id":"task_1", "actor_ref":"customer_alias", "outcome":"The requested compatible tool was found and used successfully", "useful":true }`. This records an unverified claim. Reuse the same ID and exact body for retries. Only an operator can verify it and establish independent actor identity.
- `POST /v1/budget/requests`: `{ "id":"proposal_1", "base_revision":1, "evidence_ids":["outcome_1"], "bottleneck":"Specific capacity constraint", "current_spend":{"total_pence":0,"model_pence":0,"model_tokens":0}, "expected_benefit":"Expected additional useful outcomes and uncertainty", "limits":{"total_pence":30000,"model_pence":12000,"model_tokens":300000}, "duration_days":30, "stop_condition":"Stop when the limit expires or useful outcomes do not improve" }`. Supply actual current ledger values, not estimates; cite only your own operator-verified useful outcomes. At most ten evidence IDs. One pending proposal per policy revision; duplicate proposals do not send repeated emails.

## Owner email review

A pending current-policy proposal can produce one email to the configured operator address. It contains a review link and a private one-time decision code. Opening the link does nothing. The code is entered into `/budget.html` and kept in memory. It grants access only to that proposal and cannot activate services.

- `POST /v1/budget/requests/{id}/review`: `{ "decision_token":"code from email" }` returns the exact proposal, current policy and evidence.
- `POST /v1/budget/requests/{id}/decision`: `{ "decision_token":"code from email", "decision":"approved", "authorised":true, "reason":"Reason for approval" }`. `rejected` is the other decision. Approval requires explicit action, changes the policy revision atomically, and consumes the code. Stale revisions or aged evidence cannot be approved; a still-valid code may review and reject them. Expired/used codes fail. These scoped endpoints do not require the separate staging key.

## Operator calls

Use `X-Operator-Key`, and on staging use `X-BotBoard-Staging-Key` for mutations. Never put keys in URLs.

- `GET /v1/operator/budget`: current policy, recent verified outcome counts and current monthly recorded usage.
- `GET /v1/operator/budget/outcomes`: recent reported outcomes for review.
- `POST /v1/operator/budget/outcomes/{id}/verify`: `{ "useful":true, "independent_actor_ref":"confirmed_customer_alias" }`. Verify actual task results and actor independence from evidence; never verify synthetic tests as real demand.
- `POST /v1/operator/budget/usage`: `{ "id":"receipt_unique_id", "month":"2026-09", "total_pence":1000, "model_pence":500, "model_tokens":1000, "source_receipt":"Private accounting reference" }`. Incremental receipt amounts, not cumulative snapshots. Reuse IDs for exact retries. No secrets in receipts.
- `GET /v1/operator/budget/requests`: `{ "requests": [...] }`.
- `POST /v1/operator/budget/requests`: same proposal schema as assistants; operator may cite verified outcomes across assistants.
- `POST /v1/operator/budget/requests/{id}/decision`: same decision body without the email token.
- `POST /v1/operator/budget/evaluate`: run the bounded capacity evaluation.
- `POST /v1/operator/budget/notify`: attempt at most one pending email under shared email delivery quotas.

Hourly evaluation uses imported monthly usage and recent independently confirmed repeat use. Insufficient evidence or no real spending produces no request. Email limits and service pause still apply; uncertain sends are not retried automatically. Production registration remains closed while staging acceptance continues.