Accounting

List entities

GET /api/v1/accounting/entities

Bootstraps the personal entity and its default wallet on first call.

Responses

• 200 — Entities. Entity[]
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error

curl "$API_URL/api/v1/accounting/entities" \
  -H "Authorization: Bearer $TOKEN"

Create a business entity

POST /api/v1/accounting/entities

Business only. Also creates its default cash asset, “<name> Main Wallet”, at ฿0.

Request body (application/json)

Type: object

Responses

• 201 — Entity created. Entity
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X POST "$API_URL/api/v1/accounting/entities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Get an entity

GET /api/v1/accounting/entities/{id}

Parameters

Responses

• 200 — The entity. Entity
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error

curl "$API_URL/api/v1/accounting/entities/:id" \
  -H "Authorization: Bearer $TOKEN"

Update an entity

PATCH /api/v1/accounting/entities/{id}

Partial update. The entity type cannot change.

Parameters

Request body (application/json)

Type: object

Responses

• 200 — Entity updated. Entity
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X PATCH "$API_URL/api/v1/accounting/entities/:id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete a business entity

DELETE /api/v1/accounting/entities/{id}

The personal entity cannot be deleted. Deleting cascades to all of its records.

Parameters

Responses

• 200 — Entity deleted. Ok
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X DELETE "$API_URL/api/v1/accounting/entities/:id" \
  -H "Authorization: Bearer $TOKEN"

List assets

GET /api/v1/accounting/assets

Parameters

Responses

• 200 — Assets. Asset[]
• 400 — Validation Error object
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error

curl "$API_URL/api/v1/accounting/assets" \
  -H "Authorization: Bearer $TOKEN"

Create an asset

POST /api/v1/accounting/assets

Body discriminated by kind. Fixed and investment assets accept paidFrom (creates the purchase transfer in the same write); fixed assets accept financing (creates a loan liability, paid at its level payment unless amount is given). A cash asset with isDefault clears the entity’s other defaults; an entity’s first cash asset is always the default.

Request body (application/json)

Type: object | object | object

Responses

• 201 — Asset created. Asset
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X POST "$API_URL/api/v1/accounting/assets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Get an asset

GET /api/v1/accounting/assets/{id}

Parameters

Responses

• 200 — The asset. Asset
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error

curl "$API_URL/api/v1/accounting/assets/:id" \
  -H "Authorization: Bearer $TOKEN"

Update an asset

PATCH /api/v1/accounting/assets/{id}

Partial update. kind and entityId cannot change.

Parameters

Request body (application/json)

Type: object

Responses

• 200 — Asset updated. Asset
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X PATCH "$API_URL/api/v1/accounting/assets/:id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete an asset

DELETE /api/v1/accounting/assets/{id}

Deleting the default cash asset promotes the oldest remaining cash asset of the entity.

Parameters

Responses

• 200 — Asset deleted. Ok
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X DELETE "$API_URL/api/v1/accounting/assets/:id" \
  -H "Authorization: Bearer $TOKEN"

List incomes

GET /api/v1/accounting/incomes

Parameters

Responses

• 200 — Incomes. Income[]
• 400 — Validation Error object
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error

curl "$API_URL/api/v1/accounting/incomes" \
  -H "Authorization: Bearer $TOKEN"

Create an income

POST /api/v1/accounting/incomes

employment only for kind employment; sourceAssetId only for kind investment.

Request body (application/json)

Type: object | object | object | object

Responses

• 201 — Income created. Income
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X POST "$API_URL/api/v1/accounting/incomes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Get an income

GET /api/v1/accounting/incomes/{id}

Parameters

Responses

• 200 — The income. Income
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error

curl "$API_URL/api/v1/accounting/incomes/:id" \
  -H "Authorization: Bearer $TOKEN"

Update an income

PATCH /api/v1/accounting/incomes/{id}

Parameters

Request body (application/json)

Type: object

Responses

• 200 — Income updated. Income
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X PATCH "$API_URL/api/v1/accounting/incomes/:id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete an income

DELETE /api/v1/accounting/incomes/{id}

Parameters

Responses

• 200 — Income deleted. Ok
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X DELETE "$API_URL/api/v1/accounting/incomes/:id" \
  -H "Authorization: Bearer $TOKEN"

Set the career salary

POST /api/v1/accounting/incomes/career

Updates the entity’s primary employment income (earliest startMonth), or creates one when salary > 0. A salary of 0 deactivates the primary income.

Request body (application/json)

Type: object

Responses

• 200 — Primary income, or null when none exists. object
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X POST "$API_URL/api/v1/accounting/incomes/career" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

List expenses

GET /api/v1/accounting/expenses

Parameters

Responses

• 200 — Expenses. Expense[]
• 400 — Validation Error object
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error

curl "$API_URL/api/v1/accounting/expenses" \
  -H "Authorization: Bearer $TOKEN"

Create an expense

POST /api/v1/accounting/expenses

Request body (application/json)

Type: object

Responses

• 201 — Expense created. Expense
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X POST "$API_URL/api/v1/accounting/expenses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Get an expense

GET /api/v1/accounting/expenses/{id}

Parameters

Responses

• 200 — The expense. Expense
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error

curl "$API_URL/api/v1/accounting/expenses/:id" \
  -H "Authorization: Bearer $TOKEN"

Update an expense

PATCH /api/v1/accounting/expenses/{id}

Partial update. details merges shallowly onto the stored details, so a patch for one key keeps the rest.

Parameters

Request body (application/json)

Type: object

Responses

• 200 — Expense updated. Expense
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X PATCH "$API_URL/api/v1/accounting/expenses/:id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete an expense

DELETE /api/v1/accounting/expenses/{id}

Parameters

Responses

• 200 — Expense deleted. Ok
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X DELETE "$API_URL/api/v1/accounting/expenses/:id" \
  -H "Authorization: Bearer $TOKEN"

List liabilities

GET /api/v1/accounting/liabilities

Parameters

Responses

• 200 — Liabilities. Liability[]
• 400 — Validation Error object
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error

curl "$API_URL/api/v1/accounting/liabilities" \
  -H "Authorization: Bearer $TOKEN"

Create a liability

POST /api/v1/accounting/liabilities

Body discriminated by kind. A loan without amount is paid at its level payment, calculateLoanPayment(principal, annualRate, termMonths), and its payments start in the origination month unless startMonth is given.

Request body (application/json)

Type: object | object | object

Responses

• 201 — Liability created. Liability
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X POST "$API_URL/api/v1/accounting/liabilities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Get a liability

GET /api/v1/accounting/liabilities/{id}

Parameters

Responses

• 200 — The liability. Liability
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error

curl "$API_URL/api/v1/accounting/liabilities/:id" \
  -H "Authorization: Bearer $TOKEN"

Update a liability

PATCH /api/v1/accounting/liabilities/{id}

Partial update. loan and revolving merge shallowly onto the stored details.

Parameters

Request body (application/json)

Type: object

Responses

• 200 — Liability updated. Liability
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X PATCH "$API_URL/api/v1/accounting/liabilities/:id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete a liability

DELETE /api/v1/accounting/liabilities/{id}

Parameters

Responses

• 200 — Liability deleted. Ok
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X DELETE "$API_URL/api/v1/accounting/liabilities/:id" \
  -H "Authorization: Bearer $TOKEN"

Get a liability’s month-by-month schedule

GET /api/v1/accounting/liabilities/{id}/schedule

Loans: payments, interest and principal per month, including extra-payment transfers. Revolving: opening balance, interest, card charges and payments per month. Liabilities of kind other have no schedule (400).

Parameters

Responses

• 200 — Loan or revolving schedule. LoanSchedule | RevolvingSchedule
• 400 — Validation error, or the liability has no schedule. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Liability not found. Error

curl "$API_URL/api/v1/accounting/liabilities/:id/schedule" \
  -H "Authorization: Bearer $TOKEN"

List transfers

GET /api/v1/accounting/transfers

Responses

• 200 — Transfers. Transfer[]
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error

curl "$API_URL/api/v1/accounting/transfers" \
  -H "Authorization: Bearer $TOKEN"

Create a transfer

POST /api/v1/accounting/transfers

Source: fromAssetId or fromEntityId (its default cash asset). Destination: exactly one of toAssetId, toEntityId (its default cash asset) or toLiabilityId.

Request body (application/json)

Type: object

Responses

• 201 — Transfer created. Transfer
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X POST "$API_URL/api/v1/accounting/transfers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Get a transfer

GET /api/v1/accounting/transfers/{id}

Parameters

Responses

• 200 — The transfer. Transfer
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error

curl "$API_URL/api/v1/accounting/transfers/:id" \
  -H "Authorization: Bearer $TOKEN"

Update a transfer

PATCH /api/v1/accounting/transfers/{id}

Partial update. Name a new source or destination to re-resolve that side.

Parameters

Request body (application/json)

Type: object

Responses

• 200 — Transfer updated. Transfer
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X PATCH "$API_URL/api/v1/accounting/transfers/:id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete a transfer

DELETE /api/v1/accounting/transfers/{id}

Parameters

Responses

• 200 — Transfer deleted. Ok
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Record not found. Error
• 409 — Version conflict or duplicate id. Error

curl -X DELETE "$API_URL/api/v1/accounting/transfers/:id" \
  -H "Authorization: Bearer $TOKEN"

Get wealth metrics and balance sheet per entity and consolidated

GET /api/v1/accounting/summary

Per entity: wealth metrics and balance sheet at month. Consolidated: metrics plus the balance sheet summed over all entities.

Parameters

Responses

• 200 — Summary for the month. Summary
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error

curl "$API_URL/api/v1/accounting/summary" \
  -H "Authorization: Bearer $TOKEN"

Get computed monthly ledger

GET /api/v1/accounting/ledger/{yearMonth}

Parameters

Responses

• 200 — Monthly ledger. MonthlyLedger
• 400 — Validation Error object
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Entity not found. Error

curl "$API_URL/api/v1/accounting/ledger/:yearMonth" \
  -H "Authorization: Bearer $TOKEN"

Get the cash-flow feed for a month

GET /api/v1/accounting/cash-flows

Dated money movements of one entity (default: personal) for one month. direction filters items; totals (moneyIn, moneyOut, spending) always cover every item.

Parameters

Responses

• 200 — Cash-flow feed and totals. CashFlowsResponse
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Entity not found. Error

curl "$API_URL/api/v1/accounting/cash-flows" \
  -H "Authorization: Bearer $TOKEN"

Get treasury balance per month around a centre month

GET /api/v1/accounting/projection

Parameters

Responses

• 200 — Projection points and waterfall figures. Projection
• 400 — Validation error. Error
• 401 — Missing or invalid credential (session token or API key; only when auth is configured). Error
• 404 — Entity not found. Error

curl "$API_URL/api/v1/accounting/projection" \
  -H "Authorization: Bearer $TOKEN"

Schemas

Entity

A personal or business entity that owns money flows.

Error

Ok

Asset

An asset, discriminated by kind.

Type: CashAsset | FixedAsset | InvestmentAsset

Income

An income stream.

Expense

A recurring or one-time cost.

Liability

A debt. The schedule is the planned payment.

LoanSchedule

Month-by-month loan schedule.

RevolvingSchedule

Month-by-month revolving balance.

Transfer

Money moved from an asset to an asset, or onto a liability.

Summary

Wealth metrics per entity and consolidated, for one month.

MonthlyLedger

Computed cash ledger for one entity and month.

CashFlowsResponse

Cash-flow feed of one entity for one month, with totals over all items.

Projection

Treasury balance per month around a centre month.

CashAsset

Cash and cash equivalents: bank accounts, e-wallets, cash on hand.

FixedAsset

PP&E bought once and depreciated over its useful life.

InvestmentAsset

Valued at market, grown by an expected return, never depreciated.

LoanDetails

Amortizing loan terms.

RevolvingDetails

Revolving credit: a card or credit line.

LoanScheduleEntry

One month of a loan.

RevolvingScheduleEntry

One month of a revolving balance.

BalanceSheet

Position at the end of one month.

CashFlowItem

One dated money movement in the cash-flow feed.