API reference

get/budgets

List budgets

Every budget this token may reach. A token narrowed to specific budgets sees only those.

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/accounts

List accounts

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/transactions

List transactions

Newest first. Filters run server-side, so the page limit applies to the FILTERED set.

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
account_id	query	string	no
category_id	query	string	no
start_date	query	string	no	YYYY-MM-DD, inclusive
end_date	query	string	no	YYYY-MM-DD, inclusive
search	query	string	no	Matches payee, memo and category. 200 characters maximum.
uncategorized	query	boolean	no
uncleared	query	boolean	no
limit	query	integer	no	1–1000.
offset	query	integer	no
cursor	query	string	no	Page by position instead of by offset: `start` for the first page, then each answer's `next_cursor`. Holds still while rows are written; a cursor works only with the token and the filters it came from.

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

post/transactions

Add a transaction, a transfer or a split

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 201 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

post/transactions/batch

Add up to 50 transactions

Each row is its own write with its own outcome in `results`. Not atomic: a retry with the same key replays what landed and runs what did not.

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

patch/transactions/{id}

Edit a transaction

Send the `version` you read. An edit of a row that moved since is a 409 with reason `superseded`; of a reconciled row, reason `reconciled`. Editing a transfer leg carries its pair.

Parameter	In	Type	Required	Notes
id	path	string	yes
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

delete/transactions/{id}

Delete a transaction

Needs the `write` scope. A transfer leg takes its pair with it, and the answer says so.

Parameter	In	Type	Required	Notes
id	path	string	yes
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	no	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

post/transactions/{id}/labels

Put a label on a transaction

Parameter	In	Type	Required	Notes
id	path	string	yes
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

delete/transactions/{id}/labels/{label_id}

Take a label off a transaction

Parameter	In	Type	Required	Notes
id	path	string	yes
label_id	path	string	yes
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	no	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/categories

List category groups with their categories

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
include_hidden	query	boolean	no
limit	query	integer	no	1–500.
offset	query	integer	no

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

post/categories

Add a category

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 201 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

patch/categories/{id}

Edit a category

Parameter	In	Type	Required	Notes
id	path	string	yes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

put/categories/{id}/target

Set a category's target

Parameter	In	Type	Required	Notes
id	path	string	yes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

delete/categories/{id}/target

Remove a category's target

Parameter	In	Type	Required	Notes
id	path	string	yes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	no	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/payees

List payees

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
limit	query	integer	no	1–500.
offset	query	integer	no

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

post/payees

Add a payee

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 201 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

patch/payees/{id}

Rename a payee, on every row that carries it

Parameter	In	Type	Required	Notes
id	path	string	yes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/labels

List labels

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
limit	query	integer	no	1–500.
offset	query	integer	no

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/months/{month}

Get one budget month

The envelope answer for a month: what is left to assign, what was assigned, what is overspent.

Parameter	In	Type	Required	Notes
month	path	string	yes	YYYY-MM
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

patch/months/{month}/categories/{id}

Set what is assigned to a category

Parameter	In	Type	Required	Notes
month	path	string	yes	YYYY-MM
id	path	string	yes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

post/months/{month}/moves

Move money between categories, or cover overspending

Parameter	In	Type	Required	Notes
month	path	string	yes	YYYY-MM
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
dry_run	query	boolean	no	Answer with what this would do, and write nothing. Needs no Idempotency-Key and spends none.
Idempotency-Key	header	string	yes	One value per intended change, the same one on a retry. A repeat replays the first answer; a different body is a 409.

Responses: 200 Written. With dry_run: what it would do, and nothing written · 202 Filed as a proposal in the person's review inbox. Nothing is written until they accept it · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 402 This write needs an active subscription · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 409 See `reason` · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/proposals

List proposals

What came of what was proposed, newest first. Needs the `propose` or `write` scope. Paged by cursor only.

Parameter	In	Type	Required	Notes
budget_id	query	string	yes	The budget to read. Required on every budget-scoped resource.
status	query	string	no	open (the default), accepted, edited, dismissed, expired or superseded.
limit	query	integer	no	1–500.
cursor	query	string	no	A `next_cursor` from the page before.

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

get/proposals/{id}

Get one proposal

Its payload and what it would change as of now. A person accepts or dismisses it in Rudopo; no token can.

Parameter	In	Type	Required	Notes
id	path	string	yes

Responses: 200 OK · 400 A parameter is missing or malformed · 401 No token, or the token is invalid, revoked or expired · 403 About the TOKEN: it lacks the scope, or is not scoped to that budget · 404 Not reachable by this token. A nonexistent id and another owner's id answer identically · 429 Rate limited — see Retry-After · 500 Something went wrong. The body never names internals

id	string
spaceId	string
spaceName	string \| null
name	string
currency	string	ISO 4217 code, e.g. USD
createdAt	string \| null	ISO-8601 UTC
archivedAt	string \| null	ISO-8601 UTC. Set when a clean slate left this budget behind as an archive; its balances also live in the successor budget.

id	string
name	string
type	string	Account type
currency	string	ISO 4217 code, e.g. USD — always populated, even for an account with no currency override
onBudget	boolean
closed	boolean
balance	string	Cleared + uncleared, budget currency, AS OF TODAY (server date, UTC). Future-dated transactions are excluded here but ARE counted by transactionCount and lastTransactionDate, so summing /transactions for this account will not equal this figure whenever one exists.
clearedBalance	string	Decimal string, major units, at the currency's ISO 4217 decimals, e.g. "-45.00" (USD), "1840" (JPY), "1.234" (KWD)
unclearedBalance	string	Decimal string, major units, at the currency's ISO 4217 decimals, e.g. "-45.00" (USD), "1840" (JPY), "1.234" (KWD)
nativeBalance	string	Balance in the account's own currency
transactionCount	integer
lastTransactionDate	string \| null	YYYY-MM-DD
createdAt	string \| null

id	string
date	string	YYYY-MM-DD, no timezone
accountId	string
accountName	string \| null
payeeId	string \| null
payeeName	string \| null
categoryId	string \| null
categoryName	string \| null
memo	string
amount	string	Negative = outflow. Budget currency.
amountNative	string \| null	Set only on foreign-currency accounts
exchangeRate	number \| null
currency	string	The account's ISO 4217 code, the budget's when the account has none of its own
type	string	Transaction kind
cleared	boolean
reconciled	boolean
transferAccountId	string \| null
splitGroupId	string \| null	Shared by every leg of a split
labels	object[]
createdAt	string \| null
version	integer	Send this back on PATCH: an edit of a row that moved since is refused
money	object	The same figures as `amount`, `amountNative` and `exchangeRate`, as the objects a write and a dry run answer with

amount	string	Decimal string, major units, at the currency's ISO 4217 decimals, e.g. "-45.00" (USD), "1840" (JPY), "1.234" (KWD)
currency	string	ISO 4217 code

id	string
kind	string	The change proposed, e.g. transaction.create
summary	string	One line, written by Rudopo from the figures
status	string
flags	string[]	ceiling_exceeded, possible_duplicate, demoted, needs_person
actorLabel	string \| null	The token or app that proposed it
dismissReason	string \| null	What the person said when they dismissed it
createdAt	string \| null
decidedAt	string \| null
resultId	string \| null	The row the accepted write made, when it made one
stale	boolean	True when an open proposal can no longer be accepted: its target moved

Endpoints

Shapes

Budget

Account

Transaction

Category

CategoryGroup

Payee

Label

Month

Money

Proposal

CreateTransaction

BatchTransactions

UpdateTransaction

LinkLabel

CreateCategory

UpdateCategory

SetTarget

CreatePayee

RenamePayee

Assign

Move

Proposed

DryRun

Pagination

Error

id	string
groupId	string
name	string
hidden	boolean
note	string \| null
emoji	string \| null	The category's picked icon, or null for the automatic one

version	integer	The row's `version` as you read it
date	string
amount	string
amount_native	string \| null
payee_id	string \| null
payee_name	string \| null
category_id	string \| null
memo	string
cleared	boolean
account_id	string
transfer_account_id	string \| null

outcome	string
reason	string	Set when a token that may write was sent to the review inbox instead
message	string
proposal	object