API · 4 operations

Entries

Filing transactions into envelopes, splits included.

get/v1/budgets/{budget_id}/entries
post/v1/budgets/{budget_id}/entries
patch/v1/budgets/{budget_id}/entries/{id}
delete/v1/budgets/{budget_id}/entries/{id}

get /v1/budgets/{budget_id}/entries

Filed history: search entries

scope budget:read · listEntries

Parameters

budget_id path · string · required
envelope_id query · string
from query · string
to query · string
q query · string
min_cents query · string
max_cents query · string
cursor query · string
limit query · integer · ≥ 1 · ≤ 100

Returns · 200

{ entries: [{ id, envelope_id, transaction_id, amount_cents, note, filed_by, created_at, transaction: { id, date, name, merchant_name, amount_cents, currency, account_id, pending } }], next_cursor }, newest filed first. This is where past spending lives: the inbox holds only what is NOT yet filed. Filter by envelope_id, an inclusive from/to on the transaction date (YYYY-MM-DD), q (case-insensitive substring of name or merchant) and min_cents/max_cents on the entry's magnitude, so "restaurants in July" is envelope_id + from + to, and "everything over $500 this year" is min_cents=50000 + from. Page with cursor/limit (max 100).

Example

curl 'https://api.mintro.money/v1/budgets/default/entries' \ -H "Authorization: Bearer $MINTRO_KEY"

Errors · besides 401, 429, 500

400
budget_ambiguous: This tenant holds more than one budget, so the call must say which. GET /v1/budgets for the ids, then pass budget_id.
validation_failed: The request body or query is malformed. The message names the offending field; fix it and retry.
403
forbidden: The key is valid but lacks the scope this call needs. Ask the human to mint a key with the scope named in the message.
404
not_found: No such record on this budget. Re-read GET /v1/budgets/{id} (or the relevant list) for current ids rather than reusing a remembered one.

post /v1/budgets/{budget_id}/entries

File a transaction into envelopes (splits = several elements)

scope budget:write · fileTransaction

Parameters

budget_id path · string · required

Body · JSON

transaction_id string · required
splits object[] · required · ≤ 50 items
splits[].envelope_id string · required
splits[].amount_cents integer · required · ≥ -9007199254740991
splits[].note string | null · ≤ 1000 chars

Returns · 201

{ transaction_id, entries[] }: the entries just written. On an inflow that is ready to assign, what the entries hold leaves ready to assign and the rest stays there (YNAB's split with Inflow: Ready to Assign): file $50 of a $150 paycheque and $100 is still ready to assign, and the row keeps ready_to_assign: true. Filed in full, it was a refund and its income row goes.

Example

curl -X POST 'https://api.mintro.money/v1/budgets/default/entries' \ -H "Authorization: Bearer $MINTRO_KEY" \ -H 'Content-Type: application/json' \ -d '{ "transaction_id": "txn_01J8Z3X0M4COSTCO00000000", "splits": [ { "envelope_id": "env_01J8Z3W6Q2GROCERIES00000", "amount_cents": -8412 }, { "envelope_id": "env_01J8Z3W6Q2HOUSEHOLD00000", "amount_cents": -2150, "note": "bulbs" } ] }'

Errors · besides 401, 429, 500

400
validation_failed: The request body or query is malformed. The message names the offending field; fix it and retry.
403
forbidden: The key is valid but lacks the scope this call needs. Ask the human to mint a key with the scope named in the message.
404
not_found: No such record on this budget. Re-read GET /v1/budgets/{id} (or the relevant list) for current ids rather than reusing a remembered one.
409
idempotency_conflict: This Idempotency-Key was used for a different request, or the first request is still in flight. Retry the in-flight case after a second; use a fresh key for a genuinely different request.
envelope_closed: Closed envelopes reject new entries. File into an open envelope.
422
currency_mismatch: The envelope's currency differs from the transaction's. Currency is immutable after creation, so file into an envelope of the matching currency or create one.
over_filed: The transaction is already fully filed; splits cannot exceed its amount. GET /v1/transactions/{id} to see the existing entries, then PATCH or DELETE them instead of filing again.

patch /v1/budgets/{budget_id}/entries/{id}

Move or adjust an entry

scope budget:write · updateEntry

Parameters

budget_id path · string · required
id path · string · required

Body · JSON

envelope_id string
amount_cents integer · ≥ -9007199254740991
note string | null · ≤ 1000 chars

Returns · 200

The updated entry. On an inflow that is partly ready to assign, ready to assign moves the other way by what the amount changed: whatever the entries do not hold is ready to assign.

Example

curl -X PATCH 'https://api.mintro.money/v1/budgets/default/entries/<id>' \ -H "Authorization: Bearer $MINTRO_KEY" \ -H 'Content-Type: application/json' \ -d '{ "envelope_id": "<envelope_id>", "amount_cents": 45000 }'

Errors · besides 401, 429, 500

400
validation_failed: The request body or query is malformed. The message names the offending field; fix it and retry.
403
forbidden: The key is valid but lacks the scope this call needs. Ask the human to mint a key with the scope named in the message.
404
not_found: No such record on this budget. Re-read GET /v1/budgets/{id} (or the relevant list) for current ids rather than reusing a remembered one.
409
idempotency_conflict: This Idempotency-Key was used for a different request, or the first request is still in flight. Retry the in-flight case after a second; use a fresh key for a genuinely different request.
envelope_closed: Closed envelopes reject new entries. File into an open envelope.
422
currency_mismatch: The envelope's currency differs from the transaction's. Currency is immutable after creation, so file into an envelope of the matching currency or create one.
over_filed: The transaction is already fully filed; splits cannot exceed its amount. GET /v1/transactions/{id} to see the existing entries, then PATCH or DELETE them instead of filing again.

delete /v1/budgets/{budget_id}/entries/{id}

Undo an entry

scope budget:write · deleteEntry

Parameters

budget_id path · string · required
id path · string · required

Returns · 200

{ deleted: true }. On an inflow still partly ready to assign, the entry's money goes back to ready to assign (all of it once the last entry goes). Any other row returns to the inbox once its last entry goes.

Example

curl -X DELETE 'https://api.mintro.money/v1/budgets/default/entries/<id>' \ -H "Authorization: Bearer $MINTRO_KEY"

Errors · besides 401, 429, 500

403
forbidden: The key is valid but lacks the scope this call needs. Ask the human to mint a key with the scope named in the message.
404
not_found: No such record on this budget. Re-read GET /v1/budgets/{id} (or the relevant list) for current ids rather than reusing a remembered one.
409
idempotency_conflict: This Idempotency-Key was used for a different request, or the first request is still in flight. Retry the in-flight case after a second; use a fresh key for a genuinely different request.