REST API
A documented, versioned REST API for reading your budget and recording and editing transactions from outside the web UI — a phone app, a script, or an automation platform like n8n. It uses standard Nextcloud app passwords, so nothing new to set up and nothing extra to revoke.
Overview#
The API lives at:
https://<your-nextcloud>/ocs/v2.php/apps/budget/api/v1
It is an OCS API — the same style Nextcloud's own clients use. That means two things in practice: every response is wrapped in an ocs envelope, and every request must carry the OCS-APIRequest: true header.
Version 1 is deliberately small. It covers reading your accounts and categories, browsing recent transactions, checking how much of the month's budget is left and which bills are due, recording a new transaction with a receipt photo, and editing or deleting one. Everything else stays in the web UI, see What v1 does not do.
A machine-readable OpenAPI 3.0 description ships with the app at openapi.json in the app directory, and is on GitHub at otherworld-dev/budget — point a client generator at it if you would rather not write the HTTP calls by hand.
Authentication#
Use a Nextcloud app password, not your login password.
- Open your Nextcloud personal settings > Security.
- Under Devices & sessions, type a name (e.g.
Budget on my phone) and click Create new app password. - Copy the generated password. It is shown once.
Authenticate with HTTP Basic auth: your Nextcloud username plus that app password. Revoking the entry in Devices & sessions immediately cuts off whatever was using it, without touching your account.
Apps can also obtain a token through Nextcloud's standard Login flow v2 — the browser-based flow where the user approves the app in Nextcloud rather than typing credentials into it. The resulting token is used exactly like an app password.
Two-factor authentication does not get in the way: app passwords bypass it by design.
Required headers#
| Header | Value | Why |
|---|---|---|
OCS-APIRequest | true | Required on every request. Without it Nextcloud answers 412 Precondition Failed. It is also what stops a malicious web page from calling this API with your browser session. |
Accept | application/json | Without it you get XML. |
A first request#
curl -u 'USER:APP_PASSWORD' \
-H 'OCS-APIRequest: true' \
-H 'Accept: application/json' \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1'
{
"ocs": {
"meta": { "status": "ok", "statuscode": 200, "message": "OK" },
"data": {
"api_version": "1.0",
"app_version": "2.41.0",
"user_id": "alice",
"base_currency": "GBP",
"features": {
"accounts": true,
"categories": true,
"transactions": true,
"create_transaction": true,
"edit_transaction": true,
"delete_transaction": true,
"receipt_upload": true,
"budget_status": true,
"upcoming_bills": true,
"tags": true,
"reconcile_transaction": true,
"create_transfer": true,
"set_tags": true,
"runway": true,
"receipt_ocr": false
},
"limits": {
"max_receipt_bytes": 26214400,
"receipt_mime_types": ["image/jpeg", "image/png", "image/webp", "image/heic", "application/pdf"],
"receipt_ocr_mime_types": ["image/jpeg", "image/png", "image/webp"],
"transactions_max_limit": 200
}
}
}
}
Call this endpoint first. It confirms the app is installed and your credentials work, and it tells you which optional features this particular server has — so a client can hide a flow the server cannot serve instead of failing halfway through it. receipt_ocr is true only when the administrator has configured an OCR provider; it can flip either way as the server's configuration changes, so re-check it rather than caching it forever.
GET /capabilities#
A minimal view of the server, made for a capture app's first call:
{ "ocr_available": false, "splits_available": true, "check_available": true, "edit_available": true,
"tags_available": true, "reconcile_available": true, "transfers_available": true, "tag_ids_available": true, "runway_available": true,
"transaction_filters": ["accountId", "categoryId", "dateFrom", "dateTo", "search", "type", "status",
"reconciled", "uncategorized", "tagId", "amountMin", "amountMax"],
"currency": "GBP", "version": "2.41.0" }
It has six keys. ocr_available, currency and version are always there. The *_available flags were added as the features they describe arrived, so an older server leaves them out, and a missing one should be read as false. GET / also describes the server and you, with feature flags of its own, but it does not repeat every flag found here.
ocr_available mirrors features.receipt_ocr. splits_available says whether this server accepts per-item splits — gate your per-item UI on this, not on version, and treat the key's absence as false (older servers omit it). check_available works the same way for the read-only check routes: GET /budget/status, GET /bills/upcoming, and the transfer links and split parts on transactions. edit_available does the same for editing and deleting transactions and undoing a split. currency is your base currency. version is the installed app version, or null when it cannot be resolved — treat it as advisory, never as a gate.
Four more flags work the same way: tags_available for tags on transactions, reconcile_available for marking a transaction reconciled, transfers_available for transfers on create and tag_ids_available for setting tags. runway_available says whether this server has GET /runway; GET / carries the same thing as features.runway. Check transfers_available and tag_ids_available before sending transfer_account_id or tag_ids: an older server does not refuse a field it does not know, it ignores it, and you would get a plain transaction where you asked for a transfer, or a transaction without its tags.
transaction_filters names every filter GET /transactions takes on this server. A server ignores a query parameter it does not know and answers with the unfiltered list, so look a filter up here before you rely on it. An older server leaves the key out, and has accountId, categoryId, dateFrom, dateTo and search.
New keys may be added here; ignore ones you do not recognise.
Responses#
Everything is wrapped:
{ "ocs": { "meta": { "status": "ok", "statuscode": 200, "message": "OK" }, "data": ... } }
The payload you want is always ocs.data. For the API's own answers the HTTP status matches ocs.meta.statuscode, however a few errors come from Nextcloud itself and follow its own conventions (see Errors from Nextcloud itself), so branch on the HTTP status, never on statuscode. Field names are snake_case throughout.
Machine-readable failures carry data.error_code alongside the human-readable data.error — switch on error_code (and the status), never on the prose, which is translated and will change.
| Status | Meaning |
|---|---|
200 | Success. |
201 | Created — returned by the recording POSTs (/transactions and receipt upload). The extract endpoint returns 200: it creates nothing. |
400 | Invalid input. ocs.data.error says what. |
401 | Not authenticated, or the app password has been revoked. |
403 | You can see that account but cannot write to it (a read-only share). |
404 | No such transaction, or one you cannot see. When recording, an account you cannot see, answered with Account not found. |
409 | A change the web UI would ask about first, such as editing one side of a transfer. data.error_code says which, see PATCH /transactions/{id}. |
412 | The OCS-APIRequest: true header is missing. |
429 | Rate limited — see Rate limits. |
500 | The body is not valid JSON. Nothing was changed. |
Errors carry a human-readable message:
{ "ocs": { "meta": { "status": "failure", "statuscode": 400, "message": "" },
"data": { "error": "Date must be in YYYY-MM-DD format" } } }
A database fault also carries detail, so it can be diagnosed. When the fault is a table or column missing from the database because an update of the app did not finish, hint says what an administrator can run to finish it, as described in If an Update Did Not Finish.
A list or an object sent for a field that takes a single value, such as a JSON array, or a form field sent as vendor[]=a&vendor[]=b, is refused with 400 and an error such as vendor must be a single value, and nothing is recorded or changed.
Errors from Nextcloud itself#
Some requests are answered by Nextcloud before they reach the API, and these answers follow Nextcloud's conventions rather than the API's:
| Status | When | Body |
|---|---|---|
401 | Not authenticated, or the app password was revoked. | An OCS envelope with ocs.meta.statuscode 997. |
404 | A route the API does not have. | An OCS envelope with statuscode 998. |
500 | The body is not valid JSON. Nothing was changed. | An OCS envelope with statuscode 996. |
412 | The OCS-APIRequest: true header is missing. | {"message": "CSRF check failed"} with no OCS envelope. |
429 | A rate limit was reached. | Empty. After repeated failed logins Nextcloud's brute-force protection also answers 429, with an OCS envelope whose ocs.meta.message is Reached maximum delay. |
Money#
Every amount is a string, never a JSON number — "42.50", "-1246.50", "0.00". There is no currency symbol or thousands separator, and an amount has its currency's own number of decimal places, never fewer than two: two for most currencies, and for those such as the Japanese yen that have no decimals at all, three for the Jordanian dinar, and up to eight for crypto, so 0.015 BTC reads "0.01500000". Sending an amount back as you read it therefore never rounds it.
This is deliberate. Budget stores money as an exact decimal and does its arithmetic accordingly, so a penny cannot go astray. JSON numbers are floating point in most parsers, which would quietly undo that at the last step: add 0.1 and 0.2 as JSON numbers and you get 0.30000000000000004.
Parse them into whatever exact decimal type your language offers — BigDecimal in Java and Kotlin, decimal in C#, decimal.Decimal in Python, BigDecimal in Ruby. If you are only displaying the figure, print it as it arrives. Avoid parsing amounts into a float or a double, and never do money arithmetic in one.
The currency itself is a property of the account, not the amount: read currency from GET /accounts, or account_currency on a transaction from a list response.
When sending an amount, either form is accepted — amount=42.50 and amount=42.5 mean the same thing. Up to eight decimal places are accepted, and the amount comes back in the account currency's places, so 42.5 on a pound account comes back as "42.50".
Endpoints#
All paths below are relative to /ocs/v2.php/apps/budget/api/v1.
GET / — server info#
Described above. No parameters. It answers with or without the trailing slash, at /api/v1 and /api/v1/, as client generators working from the OpenAPI description send it to the second.
GET /accounts#
Every account you own, plus every account shared with you. Balances are as of today, for shared accounts as well as your own: future-dated transactions are excluded, matching what the web UI shows.
[
{
"id": 36,
"name": "Current Account",
"type": "checking",
"currency": "GBP",
"balance": "-1246.50",
"balance_in_base_currency": null,
"base_currency": null,
"institution": "NatWest",
"owner": "alice",
"shared": false,
"closed": false,
"last_reconciled_at": "2026-07-28 19:14:07",
"updated_at": "2026-08-01 03:20:02"
}
]
type is one of checking, savings, credit_card, investment, loan, cash, money_market, cryptocurrency, mortgage or line_of_credit; treat a type you do not recognise as an asset account. Liability accounts (credit_card, loan, mortgage, line_of_credit) carry a negative balance for the amount owed; a positive value means the account is in credit. balance_in_base_currency and base_currency are set only when the account is not already in your base currency, and a shared account is converted to your base currency, not its owner's. shared is true for accounts someone else shared with you — you may or may not be able to write to them, so handle a 403 when creating, and a 404 if the share has since ended. closed is true once the user has closed the account: it keeps its history and its balance is zero, so leave it out of any picker for new transactions. owner is the Nextcloud user id of the account's owner, which is you for your own accounts and the person who shared it otherwise. last_reconciled_at is when a reconciliation of the account was last completed, in the same format as updated_at, and null for an account that has never been reconciled. It is the time you finished reconciling, not the date of the statement.
Account numbers, IBANs, and sort codes are not exposed. A capture client does not need them.
GET /categories#
Your categories plus any shared with you, as a flat list. Build the tree yourself from parent_id.
| Parameter | Type | Description |
|---|---|---|
type | string | Optional. expense or income. |
[
{ "id": 415, "name": "Bank Fees", "type": "expense", "parent_id": null,
"icon": null, "color": "#ef4444", "owner": "alice", "shared": false }
]
owner is the user id of the category's owner. A transaction is filed in its account owner's ledger, so for an account shared with you, offer only the categories whose owner matches the account's owner. This list only holds the owner's categories that have been shared with you, which are the ones you may use there. Any other category is refused when you record or edit the transaction, apart from the category the transaction already has, which can always be sent back.
Note that categories are typed expense/income while transactions are typed debit/credit. The two vocabularies are separate; the API passes each through unchanged rather than inventing a third.
GET /tags#
Your tags, the global ones first, then each tag set in the order you gave them in the web UI.
[
{ "id": 12, "name": "Holiday", "color": "#3b82f6",
"tag_set_id": null, "tag_set_name": null, "category_id": null,
"hidden": false, "owner": "alice" },
{ "id": 27, "name": "Tesco", "color": null,
"tag_set_id": 4, "tag_set_name": "Shop", "category_id": 415,
"hidden": false, "owner": "alice" }
]
There are two kinds of tag. A global tag has tag_set_id, tag_set_name and category_id all null and can be put on any transaction. A category tag belongs to a tag set of one category, and can only be put on a transaction in that category, which is what category_id tells you. hidden is true for a tag you have hidden in the web UI: it stays on the transactions that carry it and is left out of the pickers for new entries, so leave it out of yours.
After your own tags come the category tags of categories other people have shared with you, with owner saying whose each one is. These are the tags you can put on transactions in their shared accounts (see setting tags). Their global tags are not listed, as they can't be used.
Creating, renaming and deleting tags stays in the web UI.
GET /budget/status#
How much of a month's budget is left, with the same figures the Budget page shows you for that month, including categories someone has shared with you.
| Parameter | Type | Description |
|---|---|---|
month | string | Optional. YYYY-MM. Left out, it is the budget month running today, which follows your budget start day. A malformed month is a 400. |
{
"month": "2026-09",
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"currency": "GBP",
"totals": { "budgeted": "1450.00", "spent": "912.40", "remaining": "537.60" },
"categories": [
{
"category_id": 12, "name": "Groceries", "parent_id": null,
"type": "expense", "period": "monthly",
"budgeted": "400.00", "carried": "0.00", "spent": "431.20", "remaining": "-31.20",
"period_to_date": null, "shared": false
},
{
"category_id": 18, "name": "Car", "parent_id": null,
"type": "expense", "period": "yearly",
"budgeted": "100.00", "carried": "0.00", "spent": "35.00", "remaining": "65.00",
"period_to_date": { "start_date": "2026-01-01", "end_date": "2026-09-30",
"budgeted": "1200.00", "spent": "400.00" },
"shared": false
}
]
}
start_date and end_date are the dates the month covers, which with a start day other than the 1st run across two calendar months.
totals are the three summary cards at the top of the Budget page, and cover expense categories only. budgeted is each budgeted category's budget turned into a monthly amount, spent is what was spent in every expense category, whether it has a budget or not, and remaining is the difference, so an overspent category brings it down.
categories lists every category that has a budget, in the order the page shows them, income categories included. For each one:
budgetedincludes any envelope carry-over, whichcarriedrepeats so you can show it.spentis net of refunds, andremainingisbudgetedlessspent, negative when the category is overspent.- The figures are the month's for every
period, as on the page. A budget set for another period is counted as its share of the month: a weekly budget times 52 divided by 12, a third of a quarterly one and a twelfth of a yearly one, andspentis the month's spending. period_to_dateis a quarterly or yearly budget's whole quarter or year so far, which the page shows on the row as "£400.00 of £1,200.00 this year". It holdsstart_date, the first day of the quarter's or year's first budget month (following your budget start day),end_date, the last day of the month asked for,budgeted, the budget for the whole quarter or year, andspent, the spending between those dates. It isnullfor a weekly or monthly budget, and older servers leave it out.- A parent category's figures take in its subcategories, as the page adds them up, so don't add a parent and its subcategories together.
parent_idis where the category sits on the Budget page. For a shared category that can differ from where it is stored: one whose parent was not shared with you sits at the top.sharedistruefor a category someone shared with you. Its budget is theirs.
Amounts are in your base currency, currency, with its decimal places. When your accounts are in more than one currency, spending in each is converted to the base currency at your exchange rate before it is added up, the same as the page does.
GET /bills/upcoming#
Bills that are overdue or due in the next days days, your own and those shared with you, overdue first and then by due date.
| Parameter | Type | Description |
|---|---|---|
days | int | Optional, default 14. Clamped to 1-90; anything that isn't a number gets the default. |
{
"days": 14,
"bills": [
{
"id": 3, "name": "Netflix", "amount": "12.99", "amount_type": "fixed",
"currency": "GBP", "frequency": "monthly", "next_due_date": "2026-09-28",
"overdue": false, "account_id": 1, "account_name": "Current account",
"category_id": 9, "is_transfer": false, "auto_pay": true, "shared": false
}
]
}
days in the response is the window that was actually used. overdue is true once next_due_date has passed without the bill being marked as paid. amount is the amount stored on the bill: for a credit card bill whose amount_type is statement, current_balance or minimum_payment, the real amount is only worked out from the card when the bill is paid, so show it as an estimate. currency is the currency of the account the bill is paid from, and account_name is only given when you can see that account. Marking a bill paid stays in the web UI.
GET /transactions#
Most recent first, across every account you can see.
| Parameter | Type | Description |
|---|---|---|
accountId | int | Restrict to one account. (Query parameters are camelCase; only field names in bodies and responses are snake_case.) |
categoryId | int | Restrict to one category. Also matches a split transaction with a part in this category. |
dateFrom | date | Inclusive lower bound, YYYY-MM-DD. |
dateTo | date | Inclusive upper bound, YYYY-MM-DD. |
search | string | Free-text match on description and vendor. |
type | string | debit (money out) or credit (money in). |
status | string | cleared, scheduled (dated in the future) or pending (reported by the bank and not yet posted). |
reconciled | bool | true for reconciled transactions only, false for all the rest. |
uncategorized | bool | true for transactions with no category that are not split, and false for all the rest: those with a category, and split ones, whose categories are on their parts. The two never overlap and together are the whole list. true cannot be combined with categoryId. |
tagId | int | Transactions carrying this tag. An id that does not exist gives an empty list. |
amountMin / amountMax | decimal | Inclusive bounds on amount, as plain digits with an optional decimal part (20 or 20.50). amount is positive, with type carrying the direction. |
limit | int | Default 50. Clamped to 1-200, never rejected, and a value that is not a number gets the default. |
offset | int | Default 0. A negative value, or one that is not a number, reads as 0. |
{
"transactions": [
{
"id": 20070, "account_id": 36, "category_id": 427,
"date": "2026-08-08", "description": "Monthly plan", "vendor": "Practice Plan",
"amount": "15.00", "type": "debit", "reference": null, "notes": null,
"status": "scheduled", "reconciled": false, "is_split": false,
"created_at": "2026-07-31 22:49:45", "updated_at": "2026-07-31 22:49:45",
"linked_transaction_id": null, "linked_account_name": null, "splits": [], "tags": [], "has_receipt": false,
"account_name": "Current Account", "account_currency": "GBP",
"category_name": "Health & Fitness"
}
],
"total": 6346,
"limit": 50,
"offset": 0
}
Before using a filter from type down, check that it is listed in transaction_filters on GET /capabilities, as a server that does not have it ignores it and answers with everything. A value that cannot be read (status=done, reconciled=maybe, amountMin=1e3) is a 400, never a guess.
Split shares#
A split transaction has no category of its
own — its categories live on its parts — so categoryId matches one through
those parts. The row that comes back is still the whole transaction, and
amount is still the whole amount. What tells you it matched through a part is
split_amount:
{
"id": 20144, "category_id": null, "description": "Tesco",
"amount": "82.40", "type": "debit", "is_split": true,
"split_amount": "12.40"
}
Total split_amount where it is present, and amount everywhere else.
Summing amount alone credits the category the entire receipt, when only
£12.40 of it was spent there. The key appears only on rows matched this way, so
its absence means the row's whole amount belongs to the category. It can be
negative — a loyalty discount is a real, negative part of a split.
Without categoryId no row carries split_amount; every split row lists its
parts in splits instead, as described below.
total is the full match count, not the page size — use it to drive paging. account_name, account_currency, and category_name are conveniences so a list view needs no second round-trip; category_name is absent on uncategorised rows.
amount is always positive, and a string — see Money. type carries the direction: debit is money out, credit is money in.
Transfers and split parts#
A transfer between two accounts is recorded as two transactions, one in each account. linked_transaction_id is the id of the other half, or null for anything that isn't a linked transfer, and linked_account_name is the name of the account the other half is in. The name is only given when you can see that account, your own or one shared with you. The other half of a transfer on a shared account can be in one of the owner's accounts that was never shared with you, and then linked_account_name is null while linked_transaction_id is still set.
A split transaction lists its parts in splits, in the same shape POST /transactions/{id}/splits returns them. splits is [] for a transaction that isn't split.
{
"id": 20144, "category_id": null, "description": "Tesco", "amount": "82.40",
"type": "debit", "is_split": true,
"linked_transaction_id": null, "linked_account_name": null,
"splits": [
{ "id": 41, "transaction_id": 20144, "amount": "70.00", "category_id": 12, "category_name": "Groceries", "description": "Weekly shop" },
{ "id": 42, "transaction_id": 20144, "amount": "12.40", "category_id": 13, "category_name": "Household", "description": null }
]
}
Tags#
Every transaction has a tags list, in the same shape as GET /tags, global tags first, and [] when it has none. Tags are on the whole transaction, never on the parts of a split. On an account shared with you they are the owner's tags, so a tag's category_id can be a category of the owner's that is not in your own GET /categories. A transaction keeps a category tag when it is moved to another category, so a tag's category_id is not always the transaction's own.
{
"id": 20144, "description": "Tesco", "amount": "82.40", "type": "debit",
"tags": [
{ "id": 12, "name": "Holiday", "color": "#3b82f6", "tag_set_id": null,
"tag_set_name": null, "category_id": null, "hidden": false, "owner": "alice" }
]
}
Receipts#
Every transaction has has_receipt, so a list can mark the ones with a receipt without calling GET /transactions/{id}/receipts for each row. It is true when that call would list at least one receipt, and false when it would list none. A receipt whose file was deleted from Files still counts, as the receipts call still lists it with missing: true. On a transaction in an account shared with you it is null: receipts stay in the owner's Files and the receipts call is a 404 for you. A split transaction's receipts are on the transaction itself, never on its parts. GET /transactions/recent, GET /transactions/{id} and the create and edit responses carry it too. A server older than the field leaves it out, so read a missing has_receipt like null and fall back to the receipts call.
GET /transactions/recent#
The newest transactions across every account you can see, flat and merchant-first — made for a capture app's glanceable list. limit defaults to 50 and is clamped to 1-200 in the same way as on GET /transactions.
[
{ "id": 20070, "merchant": "Tesco", "date": "2026-08-01",
"amount": "15.00", "currency": "GBP", "account_name": "Current Account",
"account_id": 36, "type": "debit", "category_name": "Groceries",
"is_split": false, "splits": [],
"linked_transaction_id": null, "linked_account_name": null, "has_receipt": true }
]
merchant is the recorded vendor when there is one, else the description. type says which way the money went, as on GET /transactions, and category_name is null for an uncategorised or split transaction. The parts of a split and the transfer link are the same as on GET /transactions. Only recorded activity up to today appears — scheduled future payments would bury a fresh capture. For filtering, paging and the full field set, use GET /transactions.
GET /transactions/{id}#
One transaction, from any account you can see. Returns the same shape as a row of GET /transactions, including splits and the transfer link, but without the joined account_name, account_currency and category_name. 404 if it does not exist or is not yours.
POST /transactions#
Record a transaction. Send application/x-www-form-urlencoded, or multipart/form-data when attaching a photo.
| Field | Type | Required | Description |
|---|---|---|---|
account_id | int | yes | Must be an open account you can write to. One you cannot see answers 404 with Account not found, and one shared with you read-only answers 403. A closed account is refused with 400 and error_code: account_closed until it is reopened in the web UI; nothing is recorded and the idempotency key is not used up. A retry of a key that already recorded the transaction is answered 201 with it instead. |
date | date | yes | YYYY-MM-DD. A future date is stored as scheduled. |
merchant | string | yes* | Becomes the description and the vendor. |
amount | decimal | yes | Always positive. 42.50 or "42.50", with up to eight decimal places; returned as a string in the account currency's places. A negative amount is refused with 400 and error_code: invalid_amount, as type is what says which way the money went. |
type | string | no | debit (money out, the default) or credit (money in). |
category_id | int | no | Leave empty to file it as uncategorised. Must be a category the account owner can use: one of their own, or one shared with them. On an account shared with you that means the owner's categories that have been shared with you, not yours (compare the owner fields). Any other id is left off: the transaction is still recorded, uncategorised, and the response carries category_error saying why, so a capture is never lost. |
transfer_account_id | int | no | Makes this a transfer: the other account. |
tag_ids | string | no | Tags, as a JSON array of tag ids such as [12,27]. A JSON body may send the array itself. |
description / vendor | string | no* | Finer-grained alternative to merchant; each wins over it when both are sent. One of merchant/description is required. |
reference / notes | string | no | |
photo | file | no | A receipt image, attached to the transaction after it is recorded. Omit the part entirely when there is none — do not send it empty. |
splits | string | no | Per-item splits as a JSON array, e.g. [{"amount":"3.40","category_id":12},{"amount":"20.37"}]. The parts must sum to amount, minimum two. See POST /transactions/{id}/splits. |
idempotency_key | string | no | See below. Also accepted as an Idempotency-Key header. |
curl -u 'USER:APP_PASSWORD' \
-H 'OCS-APIRequest: true' -H 'Accept: application/json' \
-F account_id=36 -F date=2026-08-01 -F merchant=Tesco \
-F amount=42.50 -F photo=@receipt.jpg \
-F idempotency_key=8f14e45f-ceea-4671-9ef0-2b1f5c1a7a01 \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions'
Returns 201 with the created transaction, including its id. The account balance is recalculated automatically. Writing into an account someone shared with you records the transaction against their ledger, as it should — you get a 403 if the share is read-only, and a 404 with Account not found if the account is not shared with you at all. A photo sent with it is saved in the owner's Files and counts against their quota, and the owner gets a Nextcloud notification naming who added it. If the transaction is recorded but the photo cannot be attached, the response still succeeds and carries a photo_error — never re-post in that case; attach the photo separately via POST /transactions/{id}/receipts. A photo_error_code comes with it, saying why:
photo_error_code | Meaning |
|---|---|
files_access_denied | The app password has Allow filesystem access switched off (Settings → Security in Nextcloud). It can record transactions but cannot save files, so retrying won't help until the user turns it on. |
receipt_folder_not_writable | The receipts folder, or a folder above it, refuses writes. |
not_enough_space | The owner's Files are full. |
invalid_file | Too big, a type not listed by GET /, or a broken upload. |
upload_failed | Anything else. |
Switch on the code, never on the photo_error text, which is translated.
A category_id the account owner cannot use is treated the same way. The transaction is recorded without a category, and the 201 carries category_error with the reason, usually Category not found. It must be one of the account owner's categories, or Category not found for one of the owner's categories that was never shared with you. Set the right category afterwards with PATCH /transactions/{id}.
splits behaves the same way. The response always has a splits array: when the parts are accepted it lists them and is_split is true, and when they are rejected it is empty, is_split is false and splits_error says why, on an otherwise successful 201. A splits field that cannot be read as a list of parts at all is rejected in the same way. Check for splits_error, not for whether splits is there: since 3.0 every transaction has a splits list, empty when it is not split, where before a create response only had one when the parts it sent were accepted. A part whose category_id the account owner cannot use is one reason a set is rejected, and splits_error then says Category not found. All of these sub-failures follow the same rule — the transaction is recorded, so do not retry the create; fix the part that failed with its own endpoint.
Transfers#
Send transfer_account_id to record a transfer between two accounts in one call. The transaction is recorded in account_id as usual, and its other side is created in transfer_account_id with the opposite type and the same date, amount, description and vendor. So the default debit moves money from account_id to transfer_account_id, and credit moves it the other way. The response is the transaction in account_id, with linked_transaction_id and linked_account_name pointing at the other side.
curl -u 'USER:APP_PASSWORD' \
-H 'OCS-APIRequest: true' -H 'Accept: application/json' \
-F account_id=36 -F transfer_account_id=37 -F date=2026-08-01 \
-F merchant='To savings' -F amount=200.00 \
-F idempotency_key=3c59dc04-8e88-4024-8be6-1a5f7c2d9e11 \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions'
You need write access to both accounts, and both must be open. These are refused before anything is recorded, so there is nothing to clean up and the idempotency key is not used up:
| Status | error_code | When |
|---|---|---|
400 | transfer_same_account | transfer_account_id is the same as account_id. |
400 | account_closed | One of the accounts is closed. Reopen it in the web UI first. |
400 | transfer_currency_mismatch | The two accounts are in different currencies. Record it in the web UI, where each side has its own amount. |
400 | transfer_split | splits was sent as well. A transfer cannot be split. |
404 | One of the accounts does not exist or is not one you can see. | |
403 | One of the accounts is shared with you read-only. |
A retry of a key that already recorded the transfer is answered 201 with it, even if an account has since been closed, unshared or made read-only.
The two sides are recorded together or not at all, so a transfer is never left with one side missing and retrying a failed request is safe. The idempotency key covers the pair, and a repeat answers with the same first side. A key that recorded a plain transaction, or a transfer into a different account, answers 409 with error_code: idempotency_key_conflict when it is sent again with transfer_account_id. Check transfers_available on GET /capabilities first, as an older server ignores the field and records a plain transaction.
The idempotency key makes retries safe. A mobile client that times out cannot know whether the POST committed — without a key its only options are duplicating the transaction or bothering the user. Generate a UUID per draft (not per attempt: the same key must ride every retry of the same purchase) and send it; a repeat of a key seen in the last 7 days answers 201 with the transaction the first attempt recorded, inserting nothing, even if the account was closed since (if you lost access to the account itself, it answers 404). The key is reserved before anything is written, so even a retry that overlaps the original request in flight cannot double-insert: the overlapper waits briefly for the winner, replays it, or answers 409 with error_code: request_in_flight — retry shortly, nothing was duplicated. A replayed retry that carries the photo also heals a receipt the first attempt failed to attach. A replay returns the transaction as it was recorded, without a category_error. Reusing a key for a different purchase (another account or amount) is answered 409 with error_code: idempotency_key_conflict — that is a client bug, not a retry. A create refused because of its account, with a 403 or a 404, records nothing and releases its key, so the same draft can be sent again straight away to the right account. Duplicate financial transactions are the worst failure this API can produce — use the key.
PATCH /transactions/{id}#
Edit a transaction. Send only the fields you want to change, as a JSON body or form fields. A field you leave out keeps its value, and vendor, reference, notes or category_id sent as null (or an empty string) is cleared.
| Field | Type | Description |
|---|---|---|
date | date | YYYY-MM-DD. |
amount | decimal | Always more than zero, type carries the direction. Zero or a negative amount is refused with 400 and error_code: invalid_amount, unless it is the stored amount sent back unchanged. On a split transaction the parts are rescaled so they still add up to the new amount. |
type | string | debit or credit. |
description / vendor | string | |
merchant | string | Sets the description and the vendor together, as on POST /transactions. A description or vendor sent as well wins over it. |
reference / notes | string | |
category_id | int | null for uncategorised. Must be a category the account owner can use and, on an account shared with you, one shared with you, as for POST /transactions. The category the transaction already has can always be sent back, even one the owner never shared with you. Unlike on a create, any other id is refused with 400 and the error Category not found. It must be one of the account owner's categories (or Category not found for one of the owner's categories that was never shared with you), and nothing is changed. |
tag_ids | int[] | The whole set of tags, up to 200; [] removes them all. A JSON array in a string is accepted too. |
confirm_reconciled | bool | Needed to change the amount, type or date of a reconciled transaction, see below. |
curl -u 'USER:APP_PASSWORD' -X PATCH \
-H 'OCS-APIRequest: true' -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"category_id": 15}' \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions/123'
Returns 200 with the updated transaction, in the same shape as GET /transactions/{id}. The account balance is recalculated, the same as for an edit in the web UI. On an account shared with you the change is made in the owner's ledger, and a read-only share gets 403.
You can also send back the whole transaction you read with one field changed. Fields that can't be edited here are ignored, apart from account_id, status and reconciled, which are refused with 400 and error_code: field_not_editable if the value differs from what is stored. Moving a transaction to another account and changing its status stay in the web UI. The reconciled flag is set with its own two calls, so that a transaction sent back whole can never carry an out-of-date one.
Where the web UI asks before making a change, the API refuses it with 409 and an error_code, as it has no way to ask:
error_code | When | What to do |
|---|---|---|
transfer_leg | Changing the amount, type or date of one side of a transfer. The other side would keep the old figure and the two would no longer match. | Change it in the web UI. The category, notes, description, vendor and reference can still be changed here. |
reconciled | Changing the amount, type or date of a transaction that has been reconciled against a statement, which would stop past reconciliations matching. | Ask the user, then send the same request again with confirm_reconciled: true. |
split | Giving a split transaction a category. Its categories are on its parts. | Change the parts with POST /transactions/{id}/splits, or undo the split with DELETE /transactions/{id}/splits. |
A value sent back unchanged never causes any of these.
Retrying is safe. The values you send are absolute, so sending the same request twice ends in the same result, and there is no idempotency key to manage.
DELETE /transactions/{id}#
Delete a transaction, along with its splits, its tags and the links to its receipts (the receipt files stay in your Files). The account balance is recalculated.
{ "id": 123, "deleted": true, "unlinked_transaction_id": null }
Deleting one side of a transfer leaves the other side in place as a plain transaction, the same as in the web UI. unlinked_transaction_id is the id of that other side, so you can offer to delete it as well, and null for anything that wasn't a transfer.
A reconciled transaction needs ?confirm_reconciled=true on the URL, otherwise the answer is 409 with error_code: reconciled, as for an edit. Shared accounts work as for an edit.
If the response is lost and you retry, the retry gets 404. The transaction is already gone, so treat that as done.
Setting tags#
tag_ids on POST /transactions and PATCH /transactions/{id} sets a transaction's tags, with the same rules as the web UI:
- On your own account: your global tags, on any transaction, and the tags of the transaction's own category.
- On an account shared with you: only the owner's category tags for the transaction's category, from categories they have shared with you. No global tag works there, yours or theirs: the transaction is in their ledger, and their global tags are never shared.
- An uncategorised transaction, or a split one (which has no category of its own), takes global tags only.
On an edit, tag_ids replaces the whole set and [] removes them all. A tag that is already on the transaction can always be sent back, even one that no longer fits because the transaction was moved to another category, and only newly added tags are checked, against the category the edit leaves it in. On an account shared with you, the owner's tags that you can't use (the ones not in your GET /tags) stay on, so you never remove tags that aren't yours to change. null or an empty string is refused rather than read as "leave them" or "remove them all": send [] to remove them, or leave tag_ids out to keep them. A tag that can't be used refuses the whole edit with 400 and error_code: invalid_tags, and nothing is changed. Sending the tags the transaction already has, in any order, changes nothing and leaves updated_at as it was; any other set moves updated_at, and the response carries the new value. The tags list of the transaction you read is ignored if you send it back; only tag_ids sets tags.
On a create, a tag that can't be used does not lose the transaction: it is recorded without tags and the response carries tags_error saying why, the same way splits_error works, so do not retry the create. Tags are checked against the transaction as it was created, so with splits only global tags fit, and on a transfer they go on the side in account_id. A repeated idempotency key answers with the transaction as it is, and does not set its tags again. Up to 200 tag ids are taken in one request.
Check tag_ids_available on GET /capabilities first.
POST /transactions/{id}/reconcile#
Mark a transaction reconciled, the same as Mark reconciled in the web UI. No body is needed. Returns 200 with the transaction, in the same shape as GET /transactions/{id}.
curl -u 'USER:APP_PASSWORD' -X POST \
-H 'OCS-APIRequest: true' -H 'Accept: application/json' \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions/123/reconcile'
A transaction that is already reconciled comes back as it stands, so retrying is safe. A transaction dated in the future (status: scheduled) has not happened yet and cannot be reconciled: the answer is 409 with error_code: scheduled. On an account shared with you the change is made in the owner's ledger, and a read-only share gets 403.
This only sets the flag on one transaction. It does not change the account's last_reconciled_at, which is set when you reconcile against a statement in the web UI.
DELETE /transactions/{id}/reconcile#
Mark a transaction unreconciled, the same as Mark unreconciled in the web UI. Returns 200 with the transaction; one that is not reconciled comes back as it stands.
The transaction leaves the statement it was reconciled against, so it can be reconciled against a later one, and the change is written to the audit log. Its amount, type and date can then be changed without confirm_reconciled, so ask the user first, as the web UI does.
Check reconcile_available on GET /capabilities before using either call: an older server answers 404.
GET /transactions/{id}/receipts#
Receipts attached to a transaction.
[
{ "id": 1, "transaction_id": 30159, "file_id": 85, "file_name": "receipt.png",
"mime_type": "image/png", "created_at": "2026-08-01 22:25:40", "missing": false }
]
missing is true when the underlying file has been deleted from your Files — the reference survives so you can see something was there.
POST /transactions/{id}/receipts#
Attach a receipt photo. Send it as multipart/form-data under the field name file.
curl -u 'USER:APP_PASSWORD' \
-H 'OCS-APIRequest: true' -H 'Accept: application/json' \
-F 'file=@receipt.jpg' \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions/30159/receipts'
The file is stored in your own Files, in your receipts folder (Budget/Receipts unless you changed it in Settings) under <year>/<month>/ of the transaction's date, named after the transaction (2026-08-05 The Corner Deli 23.77.jpg) so it is findable by shop or amount, and referenced from the transaction — it counts against your normal quota and is included in your Files backups. Allowed types and the size cap are reported by GET / (currently JPEG, PNG, WebP, HEIC, PDF, up to 25 MB). Missing folders are created.
A refused file comes back with an error_code from the table under POST /transactions: 403 with files_access_denied or receipt_folder_not_writable when Files refuses the write, 400 with not_enough_space or invalid_file otherwise.
GET /transactions/{id}/receipts/{attachmentId}/download#
The receipt file itself, for showing it in an image view or a PDF viewer. attachmentId is the receipt's id from GET /transactions/{id}/receipts, not its file_id.
curl -u 'USER:APP_PASSWORD' -H 'OCS-APIRequest: true' -o receipt.jpg 'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions/30159/receipts/1/download'
The response is the file's raw bytes, not an OCS envelope. Content-Type is the type Nextcloud detected for the file (an image type or application/pdf), and Content-Disposition is inline with the file's name. If the file's contents were swapped in Files for something that is not an image or PDF, it comes back as application/octet-stream with attachment instead, so never display it. Responses are not cached. You get a 404 for a transaction that is not yours, an attachment belonging to a different transaction, and a receipt whose file was deleted (missing: true in the list). No path or public link to the file is ever exposed.
These receipt endpoints are owner-only. Receipts live in the owner's Files, which a share recipient cannot resolve, so a transaction in a shared account returns 404 here even though GET /transactions/{id} can read it.
GET /transactions/{id}/splits#
Just the parts of a transaction, { "splits": [...] }, in the same shape as the splits on a transaction and [] when it isn't split, even if parts from an earlier split are still stored. 404 if the transaction is not in an account you can see. On a shared account the parts are read from the owner's ledger, where they are kept.
POST /transactions/{id}/splits#
Split a transaction into per-category parts. Built for the capture flow: a receipt's line items are a set of splits, so a single shop trip can put groceries, household and a treat in three different categories instead of one.
Send splits as a JSON array — either a JSON body or a form field, so it can travel in the same multipart request as a photo.
curl -u 'USER:APP_PASSWORD' \
-H 'OCS-APIRequest: true' -H 'Accept: application/json' \
--data-urlencode 'splits=[
{"amount":"3.40","category_id":12,"description":"Flat White"},
{"amount":"18.95","category_id":13,"description":"Groceries"},
{"amount":"1.42","description":"VAT"}
]' \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions/66/splits'
{
"splits": [
{ "id": 41, "transaction_id": 66, "amount": "3.40", "category_id": 12, "category_name": "Coffee", "description": "Flat White" },
{ "id": 42, "transaction_id": 66, "amount": "18.95", "category_id": 13, "category_name": "Groceries", "description": "Groceries" },
{ "id": 43, "transaction_id": 66, "amount": "1.42", "category_id": null, "category_name": null, "description": "VAT" }
]
}
Three rules, all enforced:
- The parts must sum to the transaction amount. They are the same money, divided up — not extra. A set that does not reconcile is rejected with
400and a message stating both figures. - At least two parts. One part is not a split.
- Every part has an amount, a number other than zero. A negative part is allowed, for a discount line.
category_id may be omitted or null, which is what you want for a tax line — where VAT belongs is the user's decision, not something to invent a category for. Otherwise it must be a category the account owner can use, as for POST /transactions, and on an account shared with you one shared with you as well, unless the transaction already carries it; any other id rejects the whole set with 400 and the message Category not found.
A rejected set answers 400 with the reason in error, like every other call. The same text is also in message, which is what this endpoint used before, so older clients keep working. Every part is checked before anything is written, so a rejected set changes nothing, and a transaction that was already split keeps the parts it had. A read-only share answers 403. The endpoint is limited to 60 calls a minute, and like every route it can also get Nextcloud's own 401, 412 and 429 (see Errors from Nextcloud itself).
This replaces any existing splits on the transaction, so it is safe to call again after the user edits their categories. Splitting also clears the transaction's own category: the parts carry the categories now.
Splits hold a category each. Tags still apply to the transaction as a whole — there are no per-split tags.
Like receipts, this is owner-scoped: on a shared account the splits are written to the account owner's ledger, matching where the transaction itself lives.
Doing it in one call.
POST /transactionsalso accepts asplitsfield, so a capture app can record the transaction, attach the photo and set the splits in a single request. If the splits are rejected there, the transaction is still created and the response carriessplits_errorinstead of failing — retrying would duplicate the transaction, which is exactly what the idempotency key exists to prevent. The transaction is correct and simply unsplit; call this endpoint to fix the parts.
DELETE /transactions/{id}/splits#
Undo a split. The parts are removed and the transaction goes back to one amount with one category: ?category_id=12 sets it, and leaving it out leaves the transaction uncategorised. The amount doesn't change. The category follows the same rule as a split part: on an account shared with you it has to be shared with you, unless one of the parts already carries it, and otherwise the answer is 400 Category not found.
Returns 200 with the transaction. One that isn't split comes back unchanged, so a retry after a lost response is harmless.
POST /ocr/extract#
Turn a receipt photo into a draft transaction — the capture-before-save flow. Send the image as multipart/form-data under image (JPEG, PNG or WebP; the size cap is the same 25 MB as uploads). Nothing is recorded: show the draft to the user, let them correct it, then record it with POST /transactions (which attaches the photo in the same request).
Check ocr_available on GET /capabilities first — it is true only when the server's administrator has set up an OCR provider.
curl -u 'USER:APP_PASSWORD' \
-H 'OCS-APIRequest: true' -H 'Accept: application/json' \
-F 'image=@receipt.jpg' \
'https://cloud.example.com/ocs/v2.php/apps/budget/api/v1/ocr/extract'
{
"merchant": "Tesco Express",
"date": "2026-08-01",
"total": "9.75",
"subtotal": "8.13",
"tax": "1.62",
"discount": "0.75",
"currency": "GBP",
"suggested_category_id": 427,
"suggested_category_name": "Groceries",
"line_items": [
{ "description": "Milk 2L", "amount": "1.65", "suggested_category_id": 427, "suggested_category_name": "Groceries" },
{ "description": "Bread", "amount": "1.10", "suggested_category_id": null, "suggested_category_name": null }
],
"warnings": []
}
subtotal, tax and discount are reported only when the receipt prints them, and they exist for one purpose: making the line items reconcile so you can offer them as splits. Four shapes add up, and between them they cover most real receipts:
| Shape | When |
|---|---|
items = total | Tax-inclusive prices, no offers |
items + tax = total | Tax printed separately |
items − discount = total | Loyalty savings, coupons, multibuy |
items − discount + tax = total | Both |
discount is the total money taken off, reported positive however the receipt writes it. Send it as a negative split part — a supermarket basket sums higher than what was paid, and the savings line is what closes the gap. Check the arithmetic before offering to split: a receipt that fits none of these shapes was probably misread, and warnings will say so.
total is the one field a draft always has — a scan that cannot read what was paid answers 422 ocr_extraction_failed instead of a guess. Every other field the provider could not read is null (or []) — the user fills those in, exactly as they would have typed the whole thing before. Amounts are money strings. currency is the code printed on the receipt when one was legible, which a client can compare against the target account's currency before saving — note the Nextcloud AI provider never reports one (its OCR returns plain text and the parser does not guess currencies), so treat null as "unknown", not "same as the account".
The category suggestion is produced locally by running your own rules against the extracted merchant — the provider never sees your categories, accounts, or anything else in your ledger. Only the image is sent to it.
Each line item carries its own suggested_category_id and suggested_category_name, from the rules that match the item's text only — the merchant is left out, so a rule for the shop does not claim every line. They are null when no rule matched: leave that part uncategorised rather than guessing. A client offering per-item splits can preselect them for the user to check.
warnings is a list of machine-readable flags:
| Warning | Meaning |
|---|---|
no-total | No total could be read. |
no-date | No date could be read. |
line-items-sum-mismatch | The line items do not account for the total, and the receipt's own subtotal and tax lines do not explain the gap — so something was probably misread. The printed total is reported anyway (a till adds better than an OCR reads), but show the user. Tax added on top of the items is not flagged: a receipt whose items sum to the subtotal is reconciled through its tax line, so US-style sales tax and ex-VAT invoices come back clean. |
Three failures are specific to this endpoint, each with a stable machine code in data.error_code — switch on that, never on the message text:
| Status | error_code | Meaning |
|---|---|---|
412 | ocr_not_configured | No OCR provider is configured on this server. Tell the user it is not set up, and hide the flow (ocr_available is false). A 412 without an error_code is Nextcloud itself telling you the OCS-APIRequest: true header is missing, with a bare {"message": "CSRF check failed"} and no OCS envelope, so be ready to read either body. |
422 | ocr_extraction_failed | The provider failed (unreachable, timed out, returned nonsense) or no total was readable. Retrying is safe; extraction has no side effects. |
429 | ocr_quota_exhausted | The provider's meter ran out — a relay license tier, or a paid API's cap. Retrying now will not help; tell the user. (A 429 without this code is this API's own rate limit — wait and retry.) |
Rate limits#
| Endpoint | Limit |
|---|---|
POST /transactions | 60 per minute, per user |
PATCH /transactions/{id} | 60 per minute, per user |
POST /transactions/{id}/splits | 60 per minute, per user |
DELETE /transactions/{id} | 30 per minute, per user |
DELETE /transactions/{id}/splits | 30 per minute, per user |
POST and DELETE /transactions/{id}/reconcile | 60 per minute each, per user |
POST /transactions/{id}/receipts | 10 per minute, per user |
POST /ocr/extract | 10 per minute, per user |
Reads are not rate limited by the app. Exceeding a limit returns 429 with an empty body; wait and retry.
Recipes#
n8n — record a transaction#
Use the HTTP Request node:
- Method
POST, URLhttps://cloud.example.com/ocs/v2.php/apps/budget/api/v1/transactions - Authentication > Generic Credential Type > Basic Auth (username + app password)
- Headers:
OCS-APIRequest: trueandAccept: application/json - Body Content Type
Form-Urlencoded, withaccount_id,date,merchant,amount
The response id is at {{ $json.ocs.data.id }} — or attach the receipt in the same request as a photo part.
Shell — this month's spending#
BASE='https://cloud.example.com/ocs/v2.php/apps/budget/api/v1'
curl -s -u "$USER:$APP_PASSWORD" -H 'OCS-APIRequest: true' -H 'Accept: application/json' \
"$BASE/transactions?dateFrom=$(date +%Y-%m-01)&limit=200" |
jq '[.ocs.data.transactions[] | select(.type == "debit") | (.amount | tonumber)] | add'
Stability#
v1 is a contract. Within it:
- Fields are added, never removed or renamed, and a field's type never changes.
- New optional query parameters may appear; existing ones keep their meaning.
- New endpoints may appear under
/api/v1/. featuresinGET /may flip fromfalsetotrueas capabilities land. Clients must tolerate that.
A breaking change means a new /api/v2/, and v1 keeps working through a deprecation period. Read api_version from GET / rather than assuming.
The internal endpoints the web UI itself calls (under /apps/budget/api/..., without /ocs/) are not covered by any of this. They follow the database, change without notice, and require a browser session. Do not build against them.
GET /runway#
How long the money lasts: the same figures as the Runway dashboard tiles, worked out from the setup the user saved there (accounts to count, months to average, scheduled payments). It is read-only and takes no parameters. Gate it on runway_available from GET /capabilities, or features.runway from GET /. It needs the OCS-APIRequest: true header like every call.
{
"currency": "GBP",
"total": "30250.00",
"accounts": [
{ "id": 1, "name": "Current account", "balance": "1250.00" },
{ "id": 2, "name": "Savings", "balance": "29000.00" }
],
"window": { "months": 3, "from": "2026-08-01", "to": "2026-10-31" },
"monthly_out": "1670.00",
"monthly_in": "320.00",
"excluded_count": 2,
"excluded_total": "1500.00",
"scenarios": {
"current": { "state": "running_out", "monthly_drain": "1350.00", "months": 22.4, "runs_out_on": "2028-09-14" },
"on_budget": { "state": "running_out", "monthly_drain": "1150.00", "months": 26.3, "runs_out_on": "2029-01-10" }
},
"difference_months": 3.9,
"one_offs": [
{ "id": 4, "description": "Boiler service", "amount": "-180.00", "date": "2026-12-03" }
],
"calculated_at": "2026-11-10T09:30:00Z"
}
totalis the combined balance of the counted accounts as of today, andaccountslists them. Every amount, including eachbalance, is in the basecurrency.windowis the run of full months the pace is averaged over.monthly_outandmonthly_inare the averages, andexcluded_countandexcluded_totalsay how many transactions were left out of them with Exclude from forecast.scenarios.currentis your real pace.scenarios.on_budgetis the same with each budgeted category's spending swapped for its budget. Each has astate, amonthly_drain(money out less money in) and, when the money runs out,monthsandruns_out_on.difference_monthsis how many months longer the money lasts on budget. It is negative when the budget would be shorter.one_offslists the planned one-offs dated today or later. Past ones are left out. They are read-only in v1.calculated_atis when the answer was worked out, in UTC.
state is one of:
state | Meaning |
|---|---|
running_out | The money runs out within the 120 month limit. |
not_running_out | It does not: more comes in than goes out. |
at_zero | The total is already at or below zero. |
insufficient_data | There is no full month of history to average. |
unavailable | Only for on_budget: no category budgets are set. |
New states may be added later, so treat a state you do not recognise as "no figure". months and runs_out_on are null unless the state is running_out. months is a decimal (for example 22.4) capped at 120, so round it yourself. difference_months is null unless both scenarios are running_out.
What v1 does not do#
| Not available | Use instead |
|---|---|
| Moving a transaction to another account, or changing its status | The web UI. Everything else about a transaction can be edited through the API. |
| Changing the money on one side of a transfer | The web UI, which keeps both sides in step. |
| A transfer between two accounts in different currencies | The web UI, where each side has its own amount. |
| Creating, renaming or deleting tags | The web UI. Tags can be read and put on transactions. |
| A global tag on a transaction in someone else's shared account | Not possible in the web UI either. |
| Reconciling an account against a statement | The web UI. Single transactions can be marked reconciled here. |
| Creating accounts or categories | The web UI — see Accounts and Categories. |
| Setting budgets, paying bills, reports, forecasts | The web UI. GET /budget/status and GET /bills/upcoming read budgets and bills, and changing them stays in the web UI. GET /runway reads the runway figures, but the setup and the planned one-offs are changed in the web UI. |
| Receipt OCR on an unconfigured server | Ask the administrator to set up a provider; ocr_available on GET /capabilities reports whether this server has one. |
| Webhooks / push | The API is poll-based by design. To react to changes, poll GET /transactions — every few minutes is ample, since transactions arrive at human speed. |
Troubleshooting#
| Symptom | Cause |
|---|---|
412 Precondition Failed with no error_code | The OCS-APIRequest: true header is missing. (With error_code: ocr_not_configured it is the extract endpoint telling you no provider is set up.) |
401 on every request | Wrong username, or the app password was revoked. Note the username is your Nextcloud user ID, which is not always your email address. |
| XML instead of JSON | Add Accept: application/json. |
403 when creating a transaction | That account belongs to someone else and the share is read-only. |
404 Account not found when creating a transaction | The account does not exist, or is not shared with you (any more). The idempotency key is released, so send the same draft to the right account. |
404 listing receipts on a shared transaction | Expected — the receipt endpoints are owner-only. |
photo_error_code: files_access_denied, or 403 with it attaching a receipt | The app password has Allow filesystem access switched off. Turn it on for that device under Settings → Security in Nextcloud, or create a new app password. |
404 from GET /budget/status or GET /bills/upcoming | The server's Budget app is older than these routes. Check check_available on GET /capabilities before calling them. |
A filter on GET /transactions seems to do nothing | The server's Budget app does not have that filter, and ignores it. Check it is listed in transaction_filters on GET /capabilities first. |
| A transfer was recorded as a plain transaction | The server's Budget app is older than transfer_account_id, and ignores it. Check transfers_available on GET /capabilities first. |
A transaction was saved without its tags and no tags_error | The server's Budget app is older than tag_ids, and ignores it. Check tag_ids_available on GET /capabilities first. |
404 from GET /tags or from /transactions/{id}/reconcile | The server's Budget app is older than these routes. Check tags_available and reconcile_available on GET /capabilities first. |
404 or 405 from PATCH or DELETE on a transaction | The server's Budget app is older than editing over the API. Check edit_available on GET /capabilities first. |
409 when editing or deleting | A change the web UI would have asked about. error_code says which, see PATCH /transactions/{id}. |
category_error on a new transaction in a shared account, or 400 Category not found when editing one | The category_id is one of your own categories, or one of the owner's that they never shared with you. A transaction in a shared account is filed in the owner's ledger, so it needs one of the owner's categories that they have shared with you. Offer only categories whose owner matches the account's owner. A new transaction is still recorded, uncategorised, and the category a transaction already has can always be sent back. |
400 with error_code: invalid_amount | The amount was negative (or zero on an edit). Send it positive and say which way the money went with type. |
400 ... must be a single value | A list or an object was sent for a field that takes one value: a JSON array or object, or a form field sent with [] after its name. |
500 with ocs.meta.statuscode 996 | The body is not valid JSON. Nothing was changed. |
An empty data array where you expected records | Check ocs.meta.statuscode; a failure still returns HTTP 200 on some proxies. |
Support for the API#
The v1 API is free to use, and it stays that way.
- Bugs are fixed for free. If a call doesn't do what this page says (a documented call fails, a field is missing or has the wrong type), open a bug report and it is fixed like any other bug.
- New calls and fields are built first for Developer Partner sponsors. Budget is built in spare time, so new endpoints, new fields and help wiring up your own client go to Developer Partner sponsors on GitHub Sponsors first.
- Pull requests are always welcome. If you build the call yourself, it is reviewed when time allows. Read Stability first: a new field is a promise kept for the life of v1.
- Other requests stay open with the
api-requestlabel and may be picked up later, without a date.
See also#
- Sharing — how shared accounts affect what the API returns
- Nextcloud Integration — receipts, calendar feed, dashboard widgets
- Transactions — what the fields mean in the UI