Cashora API, as shipped in the download

Cashora REST API & Webhooks (v2.0)

Cashora ships a JSON REST API and signed webhooks so a petty-cash tin can be read and topped up from your own code — a kiosk that records a payout, a nightly job that pulls every box balance into a spreadsheet, a Slack notice when the float runs low.

Authentication

Create a key in API & Webhooks. A key belongs to a user and can do exactly what that user can do in the app. Send it on every call:

Authorization: Bearer csk_...

The key is shown once at creation and stored as a SHA-256 hash. Revoke any time.

/api/* is CSRF-exempt by design — the key is the credential, and browsers never send it implicitly.

Endpoints

Record a payout

curl -X POST https://your-install/api/boxes/1/entries \
  -H "Authorization: Bearer csk_..." -H "Content-Type: application/json" \
  -d '{"direction": "out", "amount": "12.50", "payee": "Stationers",
       "date": "2026-02-03", "category_id": 4, "receipt_ref": "R-118"}'

Money is decimal in, integer cents out.

The one rule that matters

A tin cannot hold less than nothing. A payout larger than the box balance is refused — by the API and by the form, using the same function: disbursement_refusal(). It is defined once in controllers/app.php; the API calls it rather than re-deriving the comparison, so the rule can never apply on screen and not over HTTP. A refusal returns 422 with the sentence the form would have shown:

{"error": "unprocessable",
 "detail": "This box holds €430.00 — a payout of €500.00 would take it below zero, which a
            cash box cannot do. If the cash was there, record the replenishment that topped
            the box up first, then this disbursement."}

Balances are never recomputed in the API layer either: every balance_cents, variance_cents and status comes from _box_snapshot() + Cash::balance() / Cash::variance() / Cash::statusLabel() — the same core the dashboard and the box page render. /api/report calls the report's own _report_params() + _report_data(), so the API, the HTML report and the CSV cannot disagree.

Webhooks

Add receiver URLs in API & Webhooks. Event:

• entry.recorded — a disbursement or replenishment is recorded, on the form, through the API or by the AI tool (carries the entry and the box's balance after it, so a receiver can act on a low float without a second call). A CSV import records its rows without sending an event per row.

Every delivery is signed:

X-Cashora-Event: entry.recorded
X-Cashora-Signature: sha256=<hmac_sha256(body, your endpoint secret)>

Verify by recomputing the HMAC over the raw body with the endpoint's secret. Deliveries are logged (newest 200 per endpoint) with the response code, so "did it fire?" is answerable from the admin page.

Delivery is best-effort with a short timeout: a slow receiver must never block someone recording a payout at the tin.

MCP — the agent surface (new in 3.0)

Cashora speaks MCP (Model Context Protocol) at POST /mcp, so an AI assistant can read your floats and record movements without anyone writing an integration. Same server, same data, same rules — an agent is just another client.

Authentication is the API key you already have. Send it exactly as you would to /api/*:

Authorization: Bearer <your api key>

The transport is stateless streamable-HTTP: one JSON-RPC request per POST, no session to keep alive. GET /mcp answers 405 with Allow: POST so a misconfigured client is told what to do rather than left guessing.

Connect it to an assistant

Mint the key in the app first: Settings → API keys. Choose Read only when the assistant should answer questions but never change anything — the endpoint then lists only the read tools and refuses the rest by name, so a careless prompt cannot write. Full access behaves as before.

Every client needs the same three facts, and nothing in the handshake is vendor-specific:

Claude — one command, or the same URL and header as a custom connector in the desktop and web apps:

claude mcp add --transport http cashora https://your-install/mcp \
  --header "Authorization: Bearer apk_xxxx"

ChatGPT and the OpenAI API — one entry in the Responses API's tools array (in ChatGPT itself, the same URL and key go in as a connector):

{
  "type": "mcp",
  "server_label": "cashora",
  "server_url": "https://your-install/mcp",
  "authorization": "apk_xxxx",
  "require_approval": "never"
}

**Every other client spells the same three facts differently — copy the shape from its own documentation, not from here.** VS Code is the clearest example of why: its configuration reference (read 6 September 2026) puts servers in .vscode/mcp.json under a "servers" object — *"an object that maps server names to their configurations"*. Pasted as-is, a block written for another client will not load there. The id, the URL and the token are what travel; the JSON around them belongs to whichever client you are configuring.

A local model, n8n, or your own code — n8n's MCP Client node takes the URL and the same Authorization: Bearer header; a model running on your own machine reaches it through any MCP client, so nothing leaves your network at all. Writing it yourself is one POST of JSON-RPC 2.0:

curl -X POST https://your-install/mcp \
  -H "Authorization: Bearer apk_xxxx" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Any client that speaks MCP's streamable-HTTP transport works, including ones that do not exist yet: Cashora implements the protocol, not an integration with a particular vendor.

Tools

Every description in tools/list states plainly whether the tool writes, because that is what an agent needs in order to decide whether it is allowed to call it.

The one rule does not relax for agents

record_entry calls the same disbursement_refusal() the payout screen calls. A payout of one cent more than the box holds comes back as a tool error carrying the same sentence a person at the tin would read:

{"content":[{"type":"text","text":"This box holds \u20ac267.10 \u2014 a payout of \u20ac267.11 would take it below zero, which a cash box cannot do. If the cash was there, record the replenishment that topped the box up first, then this disbursement."}],
 "isError":true}

That is not a second copy of the rule phrased for machines. It is the rule, and the reason it carries the remedy is that an agent — like a person — can act on "record the replenishment first" and cannot act on "422 unprocessable".

Paying out exactly the balance succeeds and leaves the box at zero. The rule is *never below zero, not never to zero*: an emptied tin is a normal Friday.

Argument hygiene mirrors the REST API: every argument must be a single value, an unknown argument is refused by name, and an out-of-enum kind lists the valid options (kind must be one of: disbursement, replenishment.). Roles apply exactly as in the browser — a viewer's key is refused record_entry.

Domain refusals come back as tool errors (isError: true) rather than protocol errors, because those are the ones a model can read and correct. Protocol mistakes — bad JSON, an unknown tool — are JSON-RPC errors.

Quick check

curl -s -X POST http://your-install/mcp \
  -H "Authorization: Bearer <key>" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

There is no close_month tool

Closing a month is a decision, not a calculation — it is the moment someone says the count on the table matches the count on the screen. month_report gives an agent every figure needed to prepare that decision. Making it is still yours.

Month-end pack (new in 3.0)

GET /report/export.pdf?month=YYYY-MM renders the same month-end figures as the Report screen and the CSV export, as a PDF a bookkeeper can file. Requires a signed-in session or an API key.

Documented limits

• Entries are create-and-read. Deleting an entry stays in the UI — a cash ledger correction should be a deliberate act with a person's eyes on the resulting balance.
• Boxes and categories are read-only over the API. Creating a box sets a float, which is an accounting decision, not an integration one.
• No notification emails. Cashora has no per-event recipient and no in-product low-float threshold to fire on, so 2.0 ships the API, 2FA, import, backup, rate limiting and dark mode, and no SMTP block. The entry.recorded webhook — which carries the post-entry balance — is the integration point for a low-float alert.
• Report is read-only and always reflects the live ledger.

Closed months (new in 3.2)

A box's month can be counted and closed on the box page. Once it is, POST /api/boxes/{id}/entries refuses an entry dated in that month with 422 and the sentence the screen shows ("<Month> is closed for this box … Record a correction in an open month …"); the MCP record_entry tool refuses it the same way. The MCP month_report gives each box a closed object for the month (closed_at, counted_cents, variance_cents, custodian, reviewer), or null while it is open. Closing and reopening are browser actions only.

Approval limit (new in 3.2, pass B)

With an approval limit set (Settings), POST /api/boxes/{id}/entries with "direction": "out" above the limit, by a key whose owner is not an administrator, records nothing in the ledger and answers 202 Accepted:

{ "pending": { "request_id": 7, "status": "pending", "amount_cents": 12000, "limit_cents": 7500 },
  "message": "Payouts above $75.00 wait for an administrator: this one ($120.00) is recorded as a request. Pay it out once it is approved." }

A payout the box could not pay now is still 422 with the same sentence as the screen. The MCP tool record_entry answers { "pending_request_id": …, "status": "pending", "amount_cents": …, "message": … } in the same case. Approving or declining is a browser action for administrators only; no API route or MCP tool decides a request.

The journal export (/report/journal.csv) and receipt reading are browser features; neither has an API route.

Connect it to Zapier, Make or n8n

Cashora talks to other tools without a plugin: it sends a webhook (an HTTPS message) the moment something happens, and it accepts calls to the API above. Zapier, Make and n8n can use both.

Before you start

• In Cashora, open API & Webhooks. Mint an API key (choose Read only if the other tool only reads), and add a webhook when you have its URL (below).
• Use your install's full address, for example https://cashora.yourcompany.com.

When something happens in Cashora: send it to another tool

1. In the other tool, create the trigger that gives you a URL to receive webhooks: - Zapier: the "Webhooks by Zapier" app, trigger Catch Hook (Webhooks by Zapier needs a paid Zapier plan). - Make: module Webhooks → Custom webhook. - n8n: the Webhook node.
2. Copy that URL into Cashora under API & Webhooks, and choose the event or events below.
3. Make the event happen once in Cashora, so the other tool receives a sample and you can map its fields.

Every delivery carries X-Cashora-Signature, an HMAC-SHA256 signature over the raw body. Zapier and Make accept the delivery without checking it, so keep the webhook URL private. In n8n you can check it in a Code node before using the data.

When something happens elsewhere: act in Cashora

• Zapier: "Webhooks by Zapier", action POST (or Custom Request).
• Make: module HTTP → Make a request.
• n8n: the HTTP Request node.

Send the request to your install's address plus the path from the Endpoints table above, with the header Authorization: Bearer <your API key> and a JSON body. A read-only key cannot write.

The endpoints that change something:

• POST /api/boxes/{id}/entries: Record a disbursement (out) or a replenishment (in)

Example recipes

• entry.recorded → a row in Google Sheets: webhook trigger on entry.recorded (A disbursement or replenishment is recorded, on the form, through the API or by the AI tool (carries the entry and the box's balance…), then the Google Sheets "Create row" action with the fields you want.
• entry.recorded → a message in Slack or Teams: webhook trigger on entry.recorded (A disbursement or replenishment is recorded, on the form, through the API or by the AI tool (carries the entry and the box's balance…), then the Slack or Microsoft Teams "Send message" action.

These recipes use only the events and endpoints documented above. We have not run them inside Zapier, Make or n8n ourselves; Cashora's own automated tests check its API.