Set or replace a budget

PUT https://api.dairo.app/v1/budgets

Creates or replaces the budget for a scope: account (omit scopeId), or key/agent (each requires a scopeId you own — an API key id (a UUID) for key, or an agent's id or portable agt_… id for agent). The call is an idempotent upsert keyed on the (scope, scopeId) pair, so re-sending the same target updates the existing budget instead of creating a duplicate. limits must set at least one ceiling — maxSendsPerDay, maxNewRecipientsPerHour, maxSpendPerDayCents (each an integer in 0–1000000, where 0 is enforced as a cap), or hardStopOnComplaint: true — and unknown limit keys are rejected so a typo can't silently widen the ceiling. maxSpendPerDayCents is the account's daily spend cap on calls, letters, and AI generations; it is accepted on the account scope only (a 400 on a key or agent budget), and a request that would cross it is refused with spend_cap_reached. Once set, every send under the budget is checked before it is accepted and re-checked at scheduled fire time, and a send over the line is rejected with a budget_exceeded error and emits a budget.tripped event to your webhooks and the event stream. Requires the budgets:write scope.

Scope: budgets:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X PUT "https://api.dairo.app/v1/budgets" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "account",
    "limits": {}
  }'

Body

Required, application/json: BudgetSetRequest.

Response

200 Success. Body: application/json, BudgetResponse.

{
  "budget": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scope": "account",
    "scopeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "enabled": true,
    "limits": {
      "maxSendsPerDay": null,
      "maxNewRecipientsPerHour": null,
      "hardStopOnComplaint": true,
      "maxSpendPerDayCents": null
    },
    "usage": {
      "sendsLast24h": 0,
      "newRecipientsLastHour": 0,
      "accountHasComplaint": true
    },
    "createdAt": "2026-10-19T09:30:00Z",
    "updatedAt": "2026-10-19T09:30:00Z"
  }
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.