People, money lent and borrowed, paybacks and balances.
Base URL https://app.heybmo.comFor agents: llms.txt · OpenAPI
Operations
WritePOST /api/ops/debts.add
Record money lent or borrowed
Record up to 100 debts in one call. Each has a person (a saved name, see debts.people), a way (theyOwe: they owe me; iOwe: I owe them), an amount, a currency (default: the home currency), a day (default: today), an optional due day and note. Paybacks go through debts.payBack, never a new debt the other way. Lending is not spending: nothing is logged in expenses. If the person has no home currency yet, the first currency given becomes it; say so.
debtsrequiredlist of objectUp to 100 items.Each item:
personrequiredtextA saved name, exactly. If the name given is close to saved ones but not the same, ask which person they mean instead of choosing one. Up to 60 characters.
wayrequiredtheyOwe | iOwetheyOwe: the person owes me (I lent). iOwe: I owe the person (I borrowed).
amountrequirednumberHow much, in the currency’s normal units (45.5 means 45.50), always positive.
currencytextA three-letter currency code (ISO 4217), e.g. MAD, USD, EUR, GBP. A currency named without its country is the home currency when the names match; otherwise ask which one.
daydateA day, as YYYY-MM-DD.
dueDaydateThe day it should be paid back by (an event fires that day).
notetextDefault "". Up to 500 characters.
ratenumberThe rate really used: units of the home currency per one unit of this currency. Without it, the stored rate of that day is used.
addMissingPeopletrue or falseAdd people who are not saved yet instead of refusing them. Default false.
Change up to 100 debts: person, way, amount, currency, day, due day (null clears it), note, or the rate really used (null goes back to the day’s stored rate). Only what is given changes. A payback is not a change: use debts.payBack.
debtsrequiredlist of objectUp to 100 items.Each item:
debtIdrequiredidA debt id (from debts.list or debts.add).
revisionnumberThe revision you last read. If it changed since, the change is refused so nothing is overwritten.
persontextA saved name, exactly. If the name given is close to saved ones but not the same, ask which person they mean instead of choosing one. Up to 60 characters.
waytheyOwe | iOwetheyOwe: the person owes me (I lent). iOwe: I owe the person (I borrowed).
amountnumberHow much, in the currency’s normal units (45.5 means 45.50), always positive.
currencytextA three-letter currency code (ISO 4217), e.g. MAD, USD, EUR, GBP. A currency named without its country is the home currency when the names match; otherwise ask which one.
daydateA day, as YYYY-MM-DD.
dueDaydate or null
notetextUp to 500 characters.
ratenumber or null
addMissingPeopletrue or falseAdd people who are not saved yet instead of refusing them. Default false.
Debts with their paybacks, newest first (or oldest first), filtered by person, way, status (open by default), due days, currency, words in the note or ids. For who owes what in total use debts.balances instead of adding up pages.
MCP tool debts_listCLI heybmo debts listLimit readSafe to retryInput
persontextOnly this person (a saved name). Up to 60 characters.
personIdidOnly this person, by id.
waytheyOwe | iOwetheyOwe: the person owes me (I lent). iOwe: I owe the person (I borrowed).
statusopen | closed | allopen (default), closed or all. Default "open".
dueAfterdateOnly debts due on or after this day.
dueBeforedateOnly debts due on or before this day.
currencytextOnly debts in this currency.
querytextWords in the note. Up to 200 characters.
debtIdslist of idOnly these debts, by id (with status all to find closed ones too). Up to 100 items.
ordernewest | oldestnewest first (default) or oldest first, by day. Default "newest".
What each person still owes me and what I still owe them, and the difference, over open debts, in the home currency (each debt at the rate of its day), plus the totals. One call answers how much one person owes, or who still owes money.
MCP tool debts_balancesCLI heybmo debts balancesLimit readSafe to retryInput
persontextOnly this person (a saved name). Up to 60 characters.
Where things stood at the end of past days: what was still owed to me, what I still owed, and the difference. Give up to 12 days, such as month ends; amounts are in the home currency, each debt at the rate of its day, and a closed debt counts until the day it closed. For today use debts.balances.
MCP tool debts_balanceHistoryCLI heybmo debts balanceHistoryLimit readSafe to retryInput
daysrequiredlist of dateThe days to answer for, oldest first or in any order. Up to 12 items.
Everything that happened on the debts with one person, newest first: money lent or borrowed, each payback, and what was forgiven. Debts in the trash are left out.
MCP tool debts_historyCLI heybmo debts historyLimit readSafe to retryInput
personIdrequiredidA person id (from debts.people).
Record money paid back, in part or in full, by them or by me. Name the debt (debtId) or the person; with a person, it goes to their oldest open debts first (the answer says which), the way given (theyOwe: they paid me; iOwe: I paid them; needed only when debts go both ways). The amount is in the debt’s currency and can never be more than what is left (refused with what is left). A debt closes by itself when nothing is left.
paybacksrequiredlist of objectUp to 100 items.Each item:
debtIdidA debt id (from debts.list or debts.add).
persontextA saved name, exactly. If the name given is close to saved ones but not the same, ask which person they mean instead of choosing one. Up to 60 characters.
waytheyOwe | iOwetheyOwe: the person owes me (I lent). iOwe: I owe the person (I borrowed).
amountrequirednumberHow much, in the currency’s normal units (45.5 means 45.50), always positive.
currencytextThe debt’s currency (default: that of the oldest open debt).
Remove a payback recorded by mistake, for good. Its debt owes that amount again, and reopens if it had closed as paid.
Deletes for good. The first call changes nothing and answers CONFIRMATION_REQUIRED with what would be deleted; call again with confirm: true once the person agrees.
MCP tool debts_removePaybackCLI heybmo debts removePaybackLimit deleteSafe to retryInput
paybackIdrequiredidA payback id (from a debt’s paybacks).
confirmtrue or falseSet to true once the person agreed. Without it nothing is deleted and you get a description of what would be.
The people debts are with (names only, never HeyBMO accounts), with where you stand with each in the home currency: people with open debts first, the biggest difference first, then by name. Each has the earliest due day of their open debts. Search by name with query; open keeps only people with open debts. Archived people are left out unless archived is include or only. Use these names when recording debts and paybacks.
MCP tool debts_peopleCLI heybmo debts peopleLimit readSafe to retryInput
querytextLetters in the name. Up to 60 characters.
archivedhide | include | onlyhide archived people (default), include them, or only them. Default "hide".
personIdidOnly this person.
opentrue or falsetrue: only people with open debts. Default false.
Rename a person (their debts follow) or archive them: no longer offered, their debts kept. archived: false brings them back. Two names for the same person: debts.mergePeople.
MCP tool debts_updatePersonCLI heybmo debts updatePersonLimit writeSafe to retryInput
personIdrequiredidA person id (from debts.people).
When two saved names turn out to be the same person: every debt of personId moves to intoPersonId, then personId is removed. Check with the person first: names that only look alike are often different people.
Move debts (with their paybacks) to the trash. They no longer count in balances, and can be restored with debts.restore for 30 days, then they are deleted for good. To close a debt without payback, use debts.forgive instead.
Goes to the trash: it can be restored for 30 days.
MCP tool debts_deleteCLI heybmo debts deleteLimit deleteSafe to retryInput
Delete debts that are in the trash for good, with their paybacks: the ones named (debtIds), or the whole trash (all: true). It cannot be undone, so ask the person first. Debts not in the trash are refused: debts.delete moves a debt there.
Deletes for good. The first call changes nothing and answers CONFIRMATION_REQUIRED with what would be deleted; call again with confirm: true once the person agrees.
MCP tool debts_deleteForeverCLI heybmo debts deleteForeverLimit deleteSafe to retryInput
debtIdslist of idDebts in the trash to delete for good (from debts.trash). Up to 100 items.
alltrue or falsetrue: empty the whole trash instead.
confirmtrue or falseSet to true once the person agreed. Without it nothing is deleted and you get a description of what would be.
Delete a person for good, with any of their debts that are in the trash. Refused while they still have debts outside the trash. It cannot be undone, so ask the person first; to just hide someone, archive them with debts.updatePerson.
Deletes for good. The first call changes nothing and answers CONFIRMATION_REQUIRED with what would be deleted; call again with confirm: true once the person agrees.
MCP tool debts_deletePersonCLI heybmo debts deletePersonLimit deleteSafe to retryInput
personIdrequiredidA person id (from debts.people).
confirmtrue or falseSet to true once the person agreed. Without it nothing is deleted and you get a description of what would be.