Starts tracking a budget on a project you already have. A project has at most one budget, so creating a second one returns 422.

calculation_mode sets the unit of every number in the budget: fee counts money in the project's currency, time counts hours. amount is a plain decimal in that unit, not cents — "5000" on a fee budget is 5,000.00 and "37.5" on a time budget is 37.5 hours.

calculation_base has to be one the mode can count, and any other is rejected:

Every setting you leave out is taken from the company's budget settings in Bonsai, the ones the app pre-fills. A default calculation_base the mode cannot count becomes billable_time.

The project needs a start_date, because budget cycles run from it; set one with PATCH /public-api/v1/projects/{id} first. A project that starts in the future gets its budget right away, and its first cycle opens on the start date.

A project the token cannot see returns 404. One it can see returns 403 when the token may not change the project or see its budget, or when the plan does not include budgets.

{
  "budget": {
    "calculation_mode": "fee",
    "amount": "5000",
    "calculation_base": "billable_time_and_expenses",
    "expenses_calculation_base": "billable",
    "reset_frequency": "monthly",
    "over_budget_notification": "enabled",
    "over_budget_notification_threshold": "80"
  }
}

{
  "data": {
    "id": 41,
    "amount": "5000.0",
    "over_budget_notification_threshold": "80.0",
    "calculation_mode": "fee",
    "calculation_base": "billable_time_and_expenses",
    "expenses_calculation_base": "all",
    "reset_frequency": "monthly",
    "over_budget_notification": "enabled",
    "current_cycle": {
      "opening_date": "2026-03-01",
      "closing_date": "2026-03-31",
      "consumed_amount": "1250.0",
      "consumed_percentage": 25
    }
  },
  "meta": {
    "request_id": "b1f0d2c4-7a9e-4c3b-8d5f-1e2a3b4c5d6e"
  }
}