API reference

Budgets

A plan for a fiscal year by month, account and department, in versions and scenarios, and budget vs. actual read from the ledger.

GET/v1/budgetsList budgets
POST/v1/budgetsStart a budget
GET/v1/budgets/{budget_id}Get a budget and its lines
PATCH/v1/budgets/{budget_id}Rename a budget
DELETE/v1/budgets/{budget_id}Delete a budget that is not current
PUT/v1/budgets/{budget_id}/linesSet a budget's lines
POST/v1/budgets/{budget_id}/make_currentMake a budget version current
POST/v1/budgets/{budget_id}/versionsStart a new version of a budget
GET/v1/budgets/{budget_id}/vs_actualCompare a budget with actuals

Guides: Plan a budget and compare it with actuals

List budgets

GET/v1/budgets

client.budgets.list()

The books' budgets, the newest first, with what each budgets for income and expense.

Parameters

Name	Type	Description
`fiscal_year`Query	integer or null	Only this fiscal year's budgets.
`scenario`Query	string or null	Only this scenario. One of `base`, `upside`, `downside`
`status`Query	string or null	Only budgets in this state. One of `draft`, `current`, `superseded`
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200BudgetPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/budgets" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Start a budget

POST/v1/budgets· Idempotent

client.budgets.create()

Start a budget for a fiscal year and scenario: blank, copied from another budget, or from last year's actuals.

It is the next version of its year and scenario. The first one is made current; later ones are drafts until made current. Refused with budget_terms for a budget to copy that is not in these books.

Request body

BudgetCreate

Response

201BudgetDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/budgets" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fiscal_year":0,"name":"…"}'

Get a budget and its lines

GET/v1/budgets/{budget_id}

client.budgets.get()

A budget with every budgeted cell: an amount per account, department and month.

Parameters

Name	Type	Description
`budget_id`Path · Required	string	An id that starts with `budget_`.

Response

200BudgetDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/budgets/{budget_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Rename a budget

PATCH/v1/budgets/{budget_id}· Idempotent

client.budgets.update()

Rename a budget or change its memo. Refused with budget_frozen for a superseded version.

Parameters

Name	Type	Description
`budget_id`Path · Required	string	An id that starts with `budget_`.

Request body

BudgetChange

Response

200BudgetDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PATCH "https://api.ledgerit.ai/v1/budgets/{budget_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a budget that is not current

DELETE/v1/budgets/{budget_id}· Idempotent

client.budgets.delete()

Delete a draft or superseded budget and its lines. Refused with budget_frozen for the current version: make another current first.

Parameters

Name	Type	Description
`budget_id`Path · Required	string	An id that starts with `budget_`.

Response

204No content

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X DELETE "https://api.ledgerit.ai/v1/budgets/{budget_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Set a budget's lines

PUT/v1/budgets/{budget_id}/lines· Idempotent

client.budgets.setLines()

Replace every line of a budget with these: what saving the grid does.

Each line is one month's amount for an income or expense account, a department, or both, once per account, department and month. Refused with budget_terms for a month outside the budget or an account that is not a postable P&L account, budget_frozen for a superseded version, and budget_changed when expected_row_version is stale.

Parameters

Name	Type	Description
`budget_id`Path · Required	string	An id that starts with `budget_`.

Request body

BudgetLinesIn

Response

200BudgetDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PUT "https://api.ledgerit.ai/v1/budgets/{budget_id}/lines" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"lines":[{"amount":0,"month":"2026-09-30"}]}'

Make a budget version current

POST/v1/budgets/{budget_id}/make_current· Idempotent

client.budgets.makeCurrent()

Make a draft the current version of its year and scenario. The version it replaces is superseded and no longer changes. Refused with budget_frozen for a superseded version.

Parameters

Name	Type	Description
`budget_id`Path · Required	string	An id that starts with `budget_`.

Response

200BudgetDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/budgets/{budget_id}/make_current" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Start a new version of a budget

POST/v1/budgets/{budget_id}/versions· Idempotent

client.budgets.newVersion()

A new draft version of a budget's year and scenario, with its lines: a reforecast. It stays a draft until made current.

Parameters

Name	Type	Description
`budget_id`Path · Required	string	An id that starts with `budget_`.

Request body

NewVersionIn

Response

201BudgetDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/budgets/{budget_id}/versions" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Compare a budget with actuals

GET/v1/budgets/{budget_id}/vs_actual

client.budgets.vsActual()

Budget vs. actual: each month's budget beside what the ledger says happened, closing entries left out as on the income statement.

Rows are the budget's accounts, their parts by department, and every other P&L account with actuals. Totals and variances run through actual_through, so a month still to come does not count as under budget.

Parameters

Name	Type	Description
`budget_id`Path · Required	string	An id that starts with `budget_`.
`through`Query	string (date) or null	Count actuals through this day; today if not given.

Response

200BudgetComparisonOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/budgets/{budget_id}/vs_actual" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Objects

The objects these operations take and return.

BudgetPage

Name	Type	Description
`data`Required	array of BudgetOut
`has_more`Required	boolean
`next_cursor`Required	string or null

BudgetCreate

Name	Type	Description
`copy_from_budget_id`	string or null	An id that starts with `budget_`.
`fiscal_year`Required	integer	The fiscal year, named for the calendar year it ends in.
`memo`	string or null
`name`Required	string	What to call it.
`scenario`	string	`base`, `upside` or `downside`. One of `base`, `upside`, `downside`Default base
`start`	string	`blank`; `copy` the lines of `copy_from_budget_id`, moved to this year's months; or `last_year_actuals`, each account's actual for the same month a year earlier. One of `blank`, `copy`, `last_year_actuals`Default blank

BudgetDetailOut

Name	Type	Description
`copied_from_id`Required	string or null	An id that starts with `budget_`.
`created_at`Required	string (date-time)
`fiscal_year`Required	integer	The fiscal year it plans, named for the calendar year it ends in.
`id`Required	string	An id that starts with `budget_`.
`lines`Required	array of BudgetLineOut	Every budgeted cell.
`memo`	string or null
`months`Required	integer	How many months it covers, from `starts_on`.
`name`Required	string	What it is called, e.g. `FY2027 plan`.
`row_version`Required	integer	Send it back as `expected_row_version` when setting lines.
`scenario`Required	string	`base`, `upside` or `downside`. One of `base`, `upside`, `downside`
`starts_on`Required	string (date)	The first day of its first month.
`status`Required	string	`current` is the version budget vs. actual reads; `draft` is being worked on; `superseded` was current once and no longer changes. One of `draft`, `current`, `superseded`
`total_expense`Required	string	Budgeted expense across its months.
`total_income`Required	string	Budgeted income across its months.
`updated_at`Required	string (date-time)
`version`Required	integer	Its version within its year and scenario, from 1.

BudgetChange

Name	Type	Description
`memo`	string or null	A new memo; null clears it.
`name`	string or null	A new name.

BudgetLinesIn

Name	Type	Description
`expected_row_version`	integer or null	The budget's `row_version` as you read it; refused with `budget_changed` if it moved on.
`lines`Required	array of BudgetLineIn	Every cell; the rest are removed.

NewVersionIn

Name	Type	Description
`name`	string or null	Its name; the source's if empty.

BudgetComparisonOut

Name	Type	Description
`actual_through`Required	string (date)	The last day whose actuals are counted.
`budget`Required	BudgetOut
`department_rows`Required	array of ComparisonRowOut	Departments budgeted on their own: their operating expenses on any account. Not in the totals.
`months`Required	array of string (date)	The first day of each month, in order.
`net_actual`Required	string	Actual income less expense through `actual_through`.
`net_budget`Required	string	Budgeted income less expense through `actual_through`.
`rows`Required	array of ComparisonRowOut	Accounts, and their parts by department, by section.

BudgetOut

Name	Type	Description
`copied_from_id`Required	string or null	An id that starts with `budget_`.
`created_at`Required	string (date-time)
`fiscal_year`Required	integer	The fiscal year it plans, named for the calendar year it ends in.
`id`Required	string	An id that starts with `budget_`.
`memo`	string or null
`months`Required	integer	How many months it covers, from `starts_on`.
`name`Required	string	What it is called, e.g. `FY2027 plan`.
`row_version`Required	integer	Send it back as `expected_row_version` when setting lines.
`scenario`Required	string	`base`, `upside` or `downside`. One of `base`, `upside`, `downside`
`starts_on`Required	string (date)	The first day of its first month.
`status`Required	string	`current` is the version budget vs. actual reads; `draft` is being worked on; `superseded` was current once and no longer changes. One of `draft`, `current`, `superseded`
`total_expense`Required	string	Budgeted expense across its months.
`total_income`Required	string	Budgeted income across its months.
`updated_at`Required	string (date-time)
`version`Required	integer	Its version within its year and scenario, from 1.

BudgetLineOut

Name	Type	Description
`account_id`Required	string or null	An id that starts with `gla_`.
`amount`Required	string	Signed the way the P&L reads: income and expense both positive.
`department_value_id`Required	string or null	An id that starts with `dimv_`.
`month`Required	string (date)	The first day of the month.

BudgetLineIn

Name	Type	Description
`account_id`	string or null	An id that starts with `gla_`.
`amount`Required	number \| string	Signed the way the P&L reads: income and expense both positive.
`department_value_id`	string or null	An id that starts with `dimv_`.
`month`Required	string (date)	The first day of one of the budget's months.

ComparisonRowOut

Name	Type	Description
`account`Required	ComparisonAccountRef or null	The account, or null for a department's row.
`actual`Required	array of string	Actual, one per month; zero after `actual_through`.
`actual_total`Required	string	Actual through `actual_through`.
`budget`Required	array of string	Budgeted, one per month.
`budget_total`Required	string	Budgeted through `actual_through`.
`department`Required	ComparisonDepartmentRef or null	The department part, if the row has one.
`favorable`Required	boolean	Income at or above budget, or expense at or below it.
`kind`Required	string	Income is favourable above budget, expense below it. One of `income`, `expense`
`section`Required	string	The income statement section: `revenue`, `operating_expenses`, …
`variance`Required	string	Actual less budget through `actual_through`.
`variance_percent`Required	string or null	Variance over budget, as a fraction; null with no budget.

ComparisonAccountRef

Name	Type	Description
`code`Required	string
`id`Required	string	An id that starts with `gla_`.
`name`Required	string

ComparisonDepartmentRef

Name	Type	Description
`code`Required	string
`id`Required	string	An id that starts with `dimv_`.
`name`Required	string