Axiomatic Docs

Create and manage budget versions, set account-level budget lines per period, and compute budget-vs-actual variance.

All endpoints require entityId and the budgets feature to be enabled on the entity.

List Budget Versions

GET /api/budgets?entityId=...

Optional query parameters:

Parameter	Type	Description
`bookId`	uuid	Filter by book
`fiscalYear`	integer	Filter by fiscal year

Response: Array of budget versions with a lineCount indicating how many budget lines each version contains.

[
  {
    "id": "uuid",
    "name": "FY2026 Operating Budget",
    "fiscalYear": 2026,
    "bookId": "uuid",
    "status": "DRAFT",
    "notes": null,
    "approvedBy": null,
    "approvedAt": null,
    "copiedFromId": null,
    "lineCount": 48,
    "createdAt": "2026-01-15T00:00:00.000Z",
    "updatedAt": "2026-01-15T00:00:00.000Z"
  }
]

Create a Budget Version

POST /api/budgets

{
  "action": "create_version",
  "entityId": "uuid",
  "bookId": "uuid",
  "name": "FY2026 Operating Budget",
  "fiscalYear": 2026,
  "notes": "Initial draft"
}

Returns the created version in DRAFT status.

Update a Budget Version

POST /api/budgets

{
  "action": "update_version",
  "entityId": "uuid",
  "id": "uuid",
  "name": "Updated Name",
  "notes": "Revised targets",
  "status": "DRAFT"
}

Approve a Budget Version

POST /api/budgets

{
  "action": "approve_version",
  "entityId": "uuid",
  "id": "uuid"
}

Sets the version status to APPROVED and records the approving user and timestamp.

Archive a Budget Version

POST /api/budgets

{
  "action": "archive_version",
  "entityId": "uuid",
  "id": "uuid"
}

Copy a Budget Version

POST /api/budgets

{
  "action": "copy_version",
  "entityId": "uuid",
  "sourceId": "uuid",
  "name": "FY2027 Operating Budget",
  "fiscalYear": 2027
}

Duplicates all budget lines from the source version into a new DRAFT version.

Upsert a Budget Line

POST /api/budgets

{
  "action": "upsert_line",
  "entityId": "uuid",
  "budgetVersionId": "uuid",
  "accountId": "uuid",
  "periodId": "uuid",
  "amount": "15000.00",
  "dimensionFilter": { "department": "Engineering" },
  "notes": "Headcount increase"
}

Creates or updates a budget line for the given account-period combination. The dimensionFilter is an optional key-value object for dimension-scoped budgets.

Bulk Upsert Budget Lines

POST /api/budgets

{
  "action": "bulk_upsert_lines",
  "entityId": "uuid",
  "budgetVersionId": "uuid",
  "lines": [
    { "accountId": "uuid", "periodId": "uuid", "amount": "15000.00" },
    { "accountId": "uuid", "periodId": "uuid", "amount": "8000.00" }
  ]
}

Delete a Budget Line

POST /api/budgets

{
  "action": "delete_line",
  "entityId": "uuid",
  "id": "uuid"
}

Delete a Budget Version

DELETE /api/budgets?id=...&entityId=...

Only DRAFT versions can be deleted.

Budget Variance

GET /api/budgets/variance?entityId=...&budgetVersionId=...&bookId=...&fromDate=...&toDate=...

Query parameters:

Parameter	Required	Description
`entityId`	Yes	Entity ID
`budgetVersionId`	Yes	Budget version to compare against
`bookId`	Yes	Book for actual balances
`fromDate`	Yes	Start of the actuals date range
`toDate`	Yes	End of the actuals date range
`groupByDimension`	No	Group results by a dimension

Response:

[
  {
    "accountId": "uuid",
    "accountCode": "5100",
    "accountName": "Salaries",
    "accountType": "EXPENSE",
    "budgetAmount": 150000,
    "actualAmount": 142000,
    "variance": -8000,
    "variancePercent": -5.33
  }
]

variance = actual − budget
variancePercent = (variance / budget) × 100 when budget ≠ 0, otherwise null

Budgets