57 endpoints over HTTP, on your own instance, authenticated with a key you mint yourself. Your finances are yours: read them, write them, move them elsewhere.
Every endpoint lives under /api/v1 on the instance you run. Responses are JSON, amounts are in euros, and a month parameter is always YYYY-MM, defaulting to the current month in the server’s timezone.
curl -s https://dough.example.com/api/v1/summary \
-H "Authorization: Bearer $DOUGH_API_KEY"Create a key in the app under Settings, then API keys. It is shown once, because only its SHA-256 hash is stored: the database never holds a usable secret. Send it as a bearer token, or as x-api-key.
Authorization: Bearer dough_xxxxxxxxA key carries read, or read and write. A read key can see everything and change nothing. A missing or revoked key returns 401; a key without the scope an endpoint needs returns 403. Revoking a key in settings stops it working on its next request.
On an instance without the settings page, a key can still be minted on the machine that owns the database:
npx tsx scripts/create-api-key.ts --name "my-client" --scopes read,writeAn app can ask a person to sign in to their own instance instead of asking them for a key. Every Dough is its own authorization server, so there is nothing to register with anybody: the app reads /.well-known/oauth-authorization-server from whatever host it was pointed at, registers itself at /api/oauth/register, and sends the person to /oauth/authorize to approve it.
The flow is authorization code with PKCE, which is required: S256 only, no client secrets, no implicit grant. Codes are single use and expire in two minutes; reusing one revokes every token it produced. Access tokens last an hour, refresh tokens rotate on use, and a rotated refresh token cannot be used again.
GET /.well-known/oauth-authorization-server
POST /api/oauth/register {"client_name": "...", "redirect_uris": ["yourapp://connect"]}
GET /oauth/authorize?client_id=...&redirect_uri=...&response_type=code
&scope=read+write&state=...&code_challenge=...&code_challenge_method=S256
POST /api/oauth/token grant_type=authorization_code&code=...&code_verifier=...
POST /api/oauth/token grant_type=refresh_token&refresh_token=...
POST /api/oauth/revoke token=...The token that comes back authenticates every endpoint below exactly as an API key does, and carries the same read and write scopes. Revoke it from the app or from Settings.
The two calls that answer how things stand, without walking every account.
/api/v1/summaryreadTotal balance, and the month's income, budgeted, activity and Ready to Assign. The first call an assistant reaches for.
monthYYYY-MMDefaults to the current month in the server's timezone./api/v1/net-worthreadNet worth by kind (checking, savings, investments, debts) plus the saved snapshot history.
/api/v1/ai-statusreadEach AI service (Dougie, receipts, categorizing, summaries) with its provider and model, its state (ok, failing with the last error, or off) and the share of this month's AI allowance used, null when unlimited.
Everything the dashboard shows, in one call: the daily budget and the reason behind it, what is left today, the obligations ahead, the charts and the month's figures. Computed by the same module the web dashboard reads, so two clients looking at one instance cannot disagree.
/api/v1/dashboardreadThe whole dashboard model: daily budget with its breakdown and notice, today's spending and what is left, upcoming bills and income, spending flow against pace, categories, streak, trends, cash flow, recent transactions and net worth.
Balances as the app sees them. budget_excluded marks accounts left out of the spendable-balance figure, so a client can show the same number the UI does.
/api/v1/accountsreadEvery open account with its balance.
include_closed1Also return closed accounts./api/v1/accounts/createwriteAdd a manual account.
namestringrequiredWhat the account is called.typestringchecking, savings, otherAsset or otherDebt. Defaults to checking.balancenumberSeeds both balance and cleared balance.on_budgetbooleanDefaults to true./api/v1/accounts/updatewriteEdit an account. Only the fields sent change. Setting balance records a reconciliation transaction, so history keeps adding up.
idstringrequiredAccount id.namestringtypestringbalancenumberon_budgetbooleanclosedbooleansort_ordernumber/api/v1/accounts/deletewriteManual accounts are removed. Synced accounts are closed instead, because their history is not ours to drop.
idstringrequiredAccount id./api/v1/accounts/reorderwriteSet the order accounts are listed in.
orderstring[]requiredAccount ids, in the order wanted.Which budget category a bill, subscription, savings goal, debt or investment is linked to. Linking is set from the item's side, as the web's editors do.
/api/v1/budget-linksreadThe category an item is linked to, or null.
typestringrequiredbill, subscription, savings_goal, debt_account or investment_account.idstringrequiredThe item's id./api/v1/budget-linkswriteLink an item to a category, or unlink it.
typestringrequiredAs above.idstringrequiredThe item's id.category_idnumber | nullrequiredThe category, or null to unlink.The ledger. Writes here are local mode only: in YNAB mode transactions belong to YNAB and must be edited there.
/api/v1/payeesreadThe payees this household uses, most used first, each with the category it is usually filed under, the account it is usually paid from, what it last cost and its last description. A client can complete an entry from this without asking again, and it keeps working offline. The category is stated only when the history agrees, so an inconsistently filed payee gets none rather than a wrong guess.
limitnumber1 to 1000, default 300./api/v1/payees/merge-suggestionsreadPayees that look like one merchant written several ways, as groups of { into, from }, proposed by the quick AI model from the 300 most used payees. Asking merges nothing.
/api/v1/payees/mergewriteRename every transaction under the names in from to into. A rename is a merge of one name. Local mode only.
fromstring[]requiredThe payee names to replace.intostringrequiredThe name they all take./api/v1/transactionsreadTransactions newest first.
monthYYYY-MMDefaults to the current month in the server's timezone.account_idstringOne account.categorystringExact category name.qstringSearch payee, category, memo, account name, or the amount when a number (12,50 or 12.50).limitnumber1 to 500, default 50./api/v1/transactions/createwritelocal mode onlyAdd a transaction and apply its balance effect. Meant for rows the bank import has not seen yet, most of all pending card holds.
account_idstringrequiredWhich account it hits.amountnumberrequiredThe absolute value; inflow decides the direction.inflowbooleanDefaults to false, money out.dateYYYY-MM-DDDefaults to today.payee_namestringmemostringcategorystringCategory name.clearedstringtransfer_account_idstringWith category "Internal transfer", creates the counterpart leg./api/v1/transactions/updatewritelocal mode onlyPatch one transaction. Only the fields sent change.
transaction_idstringrequiredThe id the read endpoints return.amountnumberAbsolute value; inflow true stores it positive.inflowbooleanpayee_namestringmemostringaccount_idstringdateYYYY-MM-DDcategorystringtransfer_account_idstringFixes a misrouted transfer and maintains the opposite leg./api/v1/transactions/deletewritelocal mode onlyRemove a transaction, split siblings included, and reverse its balance effect.
transaction_idstringrequiredEnvelope budgeting: what each category has been given, spent and has left. The same maths as the budget page, carry-forward included.
/api/v1/badgesreadThe navigation's notice dots: budget_overspent (categories overspent this month), transactions_unread (1 when an expense was added by hand since this key's user last looked) and chat_unread (messages from others since then).
/api/v1/badgeswriteClear a dot when its screen is opened. The budget dot clears only when nothing is overspent.
seenstringrequiredtransactions or chat./api/v1/budgetreadThe month's income, total budgeted, Ready to Assign, age of money, every active category's budgeted, activity and available, and the hidden categories.
monthYYYY-MMDefaults to the current month in the server's timezone./api/v1/budget/assignwriteSet, not add, one category's budgeted amount for a month.
monthYYYY-MMDefaults to the current month in the server's timezone.category_idnumberEither this or category_name.category_namestringbudgetednumberrequiredThe amount the category ends up with./api/v1/budget/unassignwriteClear over-assigning: take back unspent money from this month's assignments until Ready to Assign is zero, first what sits beyond a target, then categories without a target, then targeted ones. Nothing already spent is undone.
monthstringYYYY-MM, default this month./api/v1/budget/auto-assignreadPreview funding targets from Ready to Assign. Without mode, the total each mode would assign; with mode, the full per-category plan. Writes nothing.
monthYYYY-MMDefaults to the current month in the server's timezone.modestringunderfunded, last_assigned, last_spent, or smart (overspending first, then targets, most-used categories first)./api/v1/budget/auto-assignwriteApply a plan. Capped so it never overbudgets.
monthYYYY-MMDefaults to the current month in the server's timezone.modestringrequiredunderfunded, last_assigned, last_spent, or smart (overspending first, then targets, most-used categories first)./api/v1/budget/movewriteMove assigned money from one category to another within a month.
monthYYYY-MMDefaults to the current month in the server's timezone.from_category_idnumberrequiredto_category_idnumberrequiredamountnumberrequired/api/v1/budget/snoozewriteSnooze a category for a month, so its target stops asking to be funded.
category_idnumberrequiredmonthYYYY-MMDefaults to the current month in the server's timezone./api/v1/budget/unsnoozewriteRemove a category's snooze for a month.
category_idnumberrequiredmonthYYYY-MMDefaults to the current month in the server's timezone.The envelopes themselves, and the targets that decide what auto-assign funds.
/api/v1/categories/suggestreadThe categories a picker should offer first for an entry: guess is the single best pick (a payee and amount always filed the same way, else the AI's), ranked the categories this payee or description is most often filed under.
payeestringThe payee as typed.memostringThe description, which often tells a generic payee apart.amountnumberThe amount, for the payee and amount history./api/v1/categories/createwriteAdd a category.
namestringrequiredgroup_namestringThe group it sits under.colorstring/api/v1/categories/updatewriteEdit a category, or link it to a subscription, bill, debt account, savings goal or investment account.
idnumberrequiredPlus the fields to change./api/v1/categories/deletewriteDelete a category. One with transactions needs reassign_to, and its monthly budgets merge into that target.
idnumberrequiredreassign_tonumberAnother category id./api/v1/categories/targetwriteSet or clear a category's budget target.
category_idnumberrequiredmonthly_amountnumberRequired unless clearing.cadencestringdaily, weekly, monthly, yearly or by_date.target_dateYYYY-MM-DDWith cadence by_date.due_daynumberWith cadence monthly: the day of the month it is due by, 1-31. null clears it.snooze_until_monthYYYY-MMclearbooleantrue removes the target.Recurring obligations with a due day, monthly or yearly.
/api/v1/billsreadEvery bill with amount, due day and cadence.
/api/v1/bills/createwriteAdd a recurring bill.
namestringrequiredamountnumberrequireddue_daynumberrequired1 to 31.categorystringcadencestringmonthly or yearly.interval_monthsnumberEvery how many months: 1 monthly, 12 yearly.due_monthnumber1 to 12, the month it next falls in when the interval is over one./api/v1/bills/updatewriteEdit a bill, or mark this month's instance paid.
idnumberrequiredmark_paidbooleanMarks the current month paid.paid_amountnumberWhat was actually paid.is_prioritybooleanis_activeboolean/api/v1/bills/deletewriteDelete a bill with its status, history and patterns.
idnumberrequiredThe smaller recurring charges, kept apart from bills so they can be counted on their own.
/api/v1/subscriptionsreadEvery subscription with amount, due day, how many months apart it falls (interval_months, due_month), whether it falls this month (due_this_month) and whether this month's charge is paid.
monthYYYY-MMDefaults to the current month in the server's timezone./api/v1/subscriptions/createwriteAdd a subscription.
namestringrequiredamountnumberrequireddue_daynumberrequired1 to 31.interval_monthsnumberEvery how many months: 1 monthly (default), 12 yearly.due_monthnumber1 to 12, the month it next falls in when the interval is over one.brand_colorstringbrand_logostring/api/v1/subscriptions/updatewriteEdit a subscription, or mark this month's charge paid. Only the fields sent change.
idnumberrequirednamestringamountnumberdue_daynumber1 to 31.interval_monthsnumberEvery how many months: 1 monthly, 12 yearly.due_monthnumber1 to 12, the month it next falls in when the interval is over one.brand_colorstringbrand_logostringis_prioritybooleanA must-pay subscription.is_activebooleanmark_paidbooleanThis month's charge paid or not./api/v1/subscriptions/deletewriteDelete a subscription.
idnumberrequiredWhat is expected to arrive, and whether it has. upcoming is true for an active source not yet received whose day is still ahead.
/api/v1/incomereadIncome sources with the month's received and upcoming status.
monthYYYY-MMDefaults to the current month in the server's timezone./api/v1/income/createwriteAdd an income source.
namestringrequiredamountnumberrequiredexpected_daynumberrequiredDay of month it usually lands.is_recurringbooleantarget_account_idstringWhere it arrives./api/v1/income/updatewriteEdit an income source, or mark it received this month.
idnumberrequiredmark_receivedboolean/api/v1/income/deletewriteDelete an income source.
idnumberrequiredSaved is the linked category's available balance, assigned minus spent and carried forward, never the lifetime sum of assignments.
/api/v1/savings-goalsreadActive goals with target and derived saved amount.
monthYYYY-MMDefaults to the current month in the server's timezone./api/v1/savings-goals/createwriteAdd a goal, optionally linked to a budget category.
namestringrequiredtarget_amountnumberrequiredynab_category_idstringLink to a category by id.ynab_category_namestringOr by name.target_dateYYYY-MM-DDdescriptionstring/api/v1/savings-goals/updatewriteEdit a goal. Only the fields sent change.
idnumberrequiredinclude_in_calculationsbooleanis_activeboolean/api/v1/savings-goals/deletewriteDelete a goal and clear its budget link.
idnumberrequiredOpen otherDebt accounts with the interest rate, minimum payment and due day kept beside them.
/api/v1/debtsreadEvery open debt with its override fields, the payoff plans for an extra monthly payment (extra=), and months_to_debt_free_at_minimums: when the minimums alone clear everything, or null when they never do.
/api/v1/debts/updatewriteSet a debt's override fields.
ynab_account_idstringrequiredWhich debt.interest_ratenumberAnnual percentage.minimum_paymentnumberdue_daynumberoriginal_amountnumbernotesstringis_priorityboolean/api/v1/debts/reorderwriteSet the display order.
orderstring[]requiredAccount ids, in the order wanted.otherAsset accounts with what goes in monthly and what return is assumed.
/api/v1/investmentsreadEvery investment account with its overrides.
/api/v1/investments/updatewriteEdit an override, or re-value the account.
ynab_account_idstringrequiredWhich account.monthly_contributionnumberexpected_returnnumberAnnual percentage.valuenumberRe-value the account to this.addednumberMoney put in alongside the re-valuation.tickerstringnotesstring/api/v1/investments/reorderwriteSet the display order.
orderstring[]requiredAccount ids, in the order wanted.The household's data to take away, and deleting the account the key belongs to.
/api/v1/account/exportwriteThe household's data as one SQLite file, the format Dough runs on, so it opens anywhere and can start a self-hosted instance. Left out: API keys, OAuth tokens, the saved bank and AI keys and the members' passwords. The export in the app's Settings keeps the saved keys and passwords.
/api/v1/account/deletewriteDelete the key owner's account. Their chats, keys and tokens go; what they added to the household passes to the next member. The last member's deletion removes the whole household. Answers { deleted: "left-household" | "erased-household" }, or 403 for a wrong password.
passwordstringrequiredThe account's password, as confirmation.Errors are JSON with an error string. 400 means the body was wrong, or the write is not available in the instance’s current mode. 401 means the key is missing, wrong or revoked. 403 means the key lacks the scope. 404 means the row is not there. A client should degrade per endpoint rather than per app: a read key is perfectly useful, and so is an instance in YNAB mode where transaction writes are refused.
The Dough MCP server is a thin client of this API: point it at your instance with an API key and an assistant can answer questions about your finances. It exposes each endpoint here as a tool.