API reference for budget management and consumption tracking via the Dime.Sheets public API.

Budgets API

The Budgets API provides read-only access to project and task budgets, including real-time consumption tracking.

List budgets

GET /api/v1/budgets

Returns all budgets in the tenant, optionally filtered by project.

Query parameters

Parameter	Type	Description
`projectId`	int?	Filter by project ID

Example request

curl "https://app.dimesheets.com/api/v1/budgets?projectId=3" \
  -H "X-API-KEY: {your-api-key}"

Example response

[
  {
    "id": 1,
    "externalId": "budget-ws-2026",
    "projectId": 3,
    "name": "Website Redesign 2026",
    "budgetType": 0,
    "amount": 500.0,
    "currency": "EUR",
    "enforcementMode": 1,
    "warnThresholdPct": 80.0,
    "startDate": "2026-01-01T00:00:00",
    "endDate": "2026-12-31T00:00:00",
    "isActive": true,
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T10:00:00Z"
  }
]

Get budget

GET /api/v1/budgets/{externalId}

Returns a single budget by its external identifier.

Example request

curl "https://app.dimesheets.com/api/v1/budgets/budget-ws-2026" \
  -H "X-API-KEY: {your-api-key}"

Get budget consumption

GET /api/v1/budgets/{externalId}/consumption

Returns real-time consumption data for a budget, including how much has been used and what remains.

Query parameters

Parameter	Type	Default	Description
`detailed`	boolean	`false`	Include per-user/role line breakdown

Example request

curl "https://app.dimesheets.com/api/v1/budgets/budget-ws-2026/consumption?detailed=true" \
  -H "X-API-KEY: {your-api-key}"

Example response

{
  "budgetId": 1,
  "budgetExternalId": "budget-ws-2026",
  "budgetName": "Website Redesign 2026",
  "projectId": 3,
  "projectName": "Website Redesign",
  "projectExternalId": "proj-ws",
  "budgetType": 0,
  "amount": 500.0,
  "currency": "EUR",
  "consumed": 180.0,
  "autoCalculated": 175.0,
  "manualEntries": 5.0,
  "remaining": 320.0,
  "consumedPercent": 36.0,
  "enforcementMode": 1,
  "warnThresholdPct": 80.0,
  "isOverThreshold": false,
  "isExhausted": false,
  "lines": [
    {
      "budgetLineId": 1,
      "userId": 5,
      "userName": "Jane Smith",
      "roleName": "Developer",
      "allocated": 200.0,
      "consumed": 80.0,
      "remaining": 120.0,
      "consumedPercent": 40.0
    }
  ]
}

Budget model

Field	Type	Description
`id`	int	Budget ID
`externalId`	string	Stable external identifier
`projectId`	int	Parent project ID
`taskId`	int?	Optional task scope
`name`	string	Display name
`budgetType`	int	`0` = Hours, `1` = Cost, `2` = Revenue
`amount`	number	Budget cap (hours or monetary value)
`currency`	string	Currency code for cost/revenue budgets
`enforcementMode`	int	`0` = None, `1` = Warn, `2` = Block
`warnThresholdPct`	number?	Warning threshold as percentage
`startDate`	string?	Budget start date (ISO 8601)
`endDate`	string?	Budget end date (ISO 8601)
`notes`	string?	Optional notes
`isActive`	boolean	Whether the budget is active

BudgetConsumptionDto model

Field	Type	Description
`budgetId`	int	Budget ID
`budgetExternalId`	string	Budget external ID
`budgetName`	string	Budget display name
`projectId`	int	Parent project ID
`projectName`	string	Project display name
`projectExternalId`	string	Project external ID
`taskId`	int?	Task ID, if scoped
`taskName`	string?	Task name
`budgetType`	int	Budget type
`amount`	number	Total budget
`currency`	string	Currency code
`consumed`	number	Total consumed
`autoCalculated`	number	Consumed via time entries
`manualEntries`	number	Consumed via manual entries
`remaining`	number	Remaining budget
`consumedPercent`	number	Percentage consumed
`enforcementMode`	int	Enforcement mode
`warnThresholdPct`	number?	Warning threshold
`isOverThreshold`	boolean	Over warning threshold
`isExhausted`	boolean	Budget fully consumed
`lines`	BudgetLineConsumptionDto[]?	Per-user breakdown (when `detailed=true`)

Budgets API

On this page