Budgets API

All endpoints require authentication and budgets tool permissions.

List Budgets

GET /api/budgets

Query parameters:

Param	Type	Description
`resource_type`	string	Filter by resource type
`resource_id`	string	Filter by resource ID
`company_id`	string	Filter by company ID
`status`	string	Filter by status

Response: { budgets }

Each budget includes joined company_name, owner_name, computed line_item_count, spent_amount (sum of line item amounts), and logged_hours (sum of time entry hours).

Get Budget Detail

GET /api/budgets/:id

Path parameters:

Param	Type	Description
`id`	string	Budget ID

Response: { budget, line_items, time_entries }

budget includes joined company_name and owner_name.
line_items includes service_type_name, task_title, computed logged_hours (approved time entries only), and invoiced_amount (from non-voided invoices). Ordered by position, then created_at.
time_entries includes user_name and task_title. Ordered by date descending.

Create Budget

POST /api/budgets

Requires update permission.

Body:

{
  "name": "string (required)",
  "resource_type": "string (required)",
  "resource_id": "string (required)",
  "po_number": "string",
  "currency": "string (default: AUD)",
  "status": "string (default: draft)",
  "total_amount": "number",
  "company_id": "string",
  "notes": "string"
}

Response: 201 { budget }

Sets owner_id and created_by to the authenticated user. Logs a created history event.

Update Budget

PUT /api/budgets/:id

Requires update permission.

Path parameters:

Param	Type	Description
`id`	string	Budget ID

Body: Any subset of updatable fields:

Field	Type	Description
`name`	string	Budget name
`po_number`	string	Purchase order number
`currency`	string	Currency code
`status`	string	Budget status
`total_amount`	number	Total budget amount
`company_id`	string	Associated company ID
`owner_id`	string	Budget owner user ID
`budget_type`	string	Budget type
`forecast_date`	string	Forecast date
`created_at`	string	Creation timestamp
`resource_type`	string	Resource type
`resource_id`	string	Resource ID
`notes`	string	Notes

At least one field must be provided.

Response: { budget }

Automatically sets updated_at. Logs status_changed when status is updated and updated for all other field changes.

Delete Budget

DELETE /api/budgets/:id

Requires manage permission.

Path parameters:

Param	Type	Description
`id`	string	Budget ID

Response: { ok: true }

Logs a deleted history event before removing the record.

Line Items

Create Line Item

POST /api/budgets/:id/line-items

Requires update permission.

Path parameters:

Param	Type	Description
`id`	string	Budget ID

Body:

{
  "description": "string (required)",
  "quantity": "number (default: 1)",
  "unit_price": "number (default: 0)",
  "service_type_id": "string",
  "task_id": "string",
  "position": "number (default: 0)"
}

amount is computed automatically as quantity * unit_price.

Response: 201 { item }

Logs a line_item_added history event on the parent budget.

Reorder Line Items

PUT /api/budgets/:id/line-items/reorder

Requires update permission.

Path parameters:

Param	Type	Description
`id`	string	Budget ID

Body:

{
  "item_ids": ["string (required) - ordered array of line item IDs"]
}

Sets each item’s position to its index in the provided array. Uses a batched D1 operation for atomicity.

Response: { ok: true }

Update Line Item

PUT /api/budgets/:id/line-items/:itemId

Requires update permission.

Path parameters:

Param	Type	Description
`id`	string	Budget ID
`itemId`	string	Line item ID

Body: Any subset of updatable fields:

Field	Type	Description
`service_type_id`	string	Service type ID
`description`	string	Line item description
`task_id`	string	Linked task ID
`position`	number	Sort position
`quantity`	number	Quantity
`unit_price`	number	Unit price

amount is always recomputed as quantity * unit_price (using existing values for any field not provided).

Response: { item }

Logs a line_item_updated history event on the parent budget.

Delete Line Item

DELETE /api/budgets/:id/line-items/:itemId

Requires update permission.

Path parameters:

Param	Type	Description
`id`	string	Budget ID
`itemId`	string	Line item ID

Response: { ok: true }

Logs a line_item_removed history event on the parent budget.