Sumly API

List every record in the workspace, newest first.

curl https://YOUR_HANDLE.rooche.biz/sumly/api/orgs/YOUR_HANDLE/expenses \
  -H "Authorization: Bearer spk_your_key_here"

Create a record.

Example

curl -X POST https://YOUR_HANDLE.rooche.biz/sumly/api/orgs/YOUR_HANDLE/expenses \
  -H "Authorization: Bearer spk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "EXPENSE",
    "amountCents": 45000,
    "businessId": "biz_...",
    "categoryId": "cat_...",
    "note": "Supplies"
  }'

Response 201

{
  "expenses": [
    {
      "id": "exp_...",
      "kind": "EXPENSE",
      "amountCents": 45000,
      "categoryId": "cat_...",
      "businessId": "biz_...",
      "toBusinessId": null,
      "subcategory": null,
      "note": "Supplies",
      "spentAt": "2026-07-24T00:00:00.000Z",
      "recordedBy": "apikey_...",
      "recordedByName": "Accounting sync",
      "createdAt": "2026-07-24T01:02:03.456Z",
      "approvedBy": null,
      "approvedAt": null
    }
  ]
}

Bulk-create records from a parsed file or paste (web Import feature, charter §5). Human-only and elevated: a signed-in admin, a manager (into their own businesses), or a consumer (their own tenant) — a plain member answers 403, and an API key answers 403 (this is a signed-in desk task, not an integration surface — use the per-record POST /expenses for automation). Partial by design: good rows are created, bad rows are reported.

Response 200

{
  "imported": 47,
  "skipped": 2,
  "createdCategories": [ { "name": "Load", "kind": "EXPENSE" } ],
  "errors": [ { "index": 14, "reason": "Amount must be a positive whole number of minor units" } ],
  "truncated": false
}

Update a record. Same body as create (its kind is fixed).

Delete a record. This is a soft delete: the record stops appearing in normal reads, but the versioned API can still surface it as a tombstone so you can reconcile the removal (see below).

A record’s edit history, newest first: every mutation that reached the ledger — a create/edit/delete, plus an approver’s approve/decline of a staged change and an attachment being added/removed — as { "record": …, "events": [ { "action", "actorName", "at", "changes": [ { "field", "from", "to" } ], "note", "viaApproval" } ] }. Scoped to who may see the record (a member their own; an admin/manager per their scope).

Attach a file to a record. Multipart (not JSON): a single file part, a kind field (voice | video | image | file — must agree with the file’s actual content), and an optional durationMs for audio/video.

curl -X POST https://YOUR_HANDLE.rooche.biz/sumly/api/orgs/YOUR_HANDLE/expenses/exp_…/attachments \
  -H "Authorization: Bearer spk_your_key_here" \
  -F kind=image \
  -F file=@receipt.jpg

Response 201

{
  "attachment": {
    "id": "att_…", "expenseId": "exp_…", "kind": "image",
    "mimeType": "image/jpeg", "filename": "receipt.jpg",
    "sizeBytes": 184230, "durationMs": null, "createdAt": "2026-08-25T01:02:03.456Z",
    "hasPoster": false
  },
  "storage": { "usedBytes": 184230, "quotaBytes": 2147483648 }
}

Fetch an attachment’s bytes (the only way to them — there is no public URL). Served with the sniffed Content-Type, Range support for audio/video seeking, and images/audio/video inline vs. everything else as a download.

A video attachment’s poster frame — a JPEG of a representative frame, for previews. Video attachments advertise it with "hasPoster": true in their metadata. Same permission as the bytes (whoever may see the record). Answers 404 for a non-video attachment or when a poster could not be generated.

Remove an attachment (frees its bytes from the storage quota immediately). Returns the caller’s refreshed { "expenses", "storage" }.

List records with cursor pagination, delta sync, and deletion tombstones.

Record fields

Each record carries the same fields as the write API plus:

Example — walk a delta feed

# first sync: no watermark yet, page through everything
curl "https://YOUR_HANDLE.rooche.biz/sumly/api/v1/orgs/YOUR_HANDLE/expenses?limit=200" \
  -H "Authorization: Bearer spk_your_key_here"
# → { "data": [...], "page": { "hasMore": true, "nextCursor": "…" } }
# follow nextCursor until hasMore is false, remembering the max updatedAt you saw.

# later: fetch only what changed (incl. deletes) since that watermark
curl "https://YOUR_HANDLE.rooche.biz/sumly/api/v1/orgs/YOUR_HANDLE/expenses?updatedSince=2026-08-03T09:15:04.000Z" \
  -H "Authorization: Bearer spk_your_key_here"

Fetch one record: { "data": record }. A soft-deleted record answers 404 unless ?includeDeleted=true. Supports ?expand=category.

Create a record. Returns 201 with { "data": record } — or 202 staged, for an approval-required member’s session (see above).

Idempotency

Send an Idempotency-Key header (any unique string, ≤ 200 chars) so a retried create after a dropped response never makes a duplicate — the first response is stored per workspace and replayed verbatim for the same key.

curl -X POST https://YOUR_HANDLE.rooche.biz/sumly/api/v1/orgs/YOUR_HANDLE/expenses \
  -H "Authorization: Bearer spk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9c1a7e-order-4821" \
  -d '{ "kind": "EXPENSE", "amountCents": 45000, "businessId": "biz_…", "categoryId": "cat_…" }'

Update a record (its kind is fixed). Returns { "data": record } — or 202 staged, for an approval-required member’s session.

Soft-delete a record. Returns { "data": record } with the record as a tombstone (deletedAt set) — or 202 staged, for an approval-required member’s session (the record keeps counting until the removal is approved).

The current balance of a business, computed server-side (admin only).

Every consumer gets the same number instead of re-implementing the opening-balance + transfer math:

{
  "data": {
    "businessId": "biz_…",
    "currency": "PHP",
    "openingBalanceCents": 239177326,
    "incomeCents": 19919958,
    "expenseCents": 3300058,
    "transferInCents": 0,
    "transferOutCents": 0,
    "balanceCents": 255797226
  }
}

balanceCents = openingBalanceCents + incomeCents − expenseCents + transferInCents − transferOutCents, over live records only (tombstones don't move money).

List categories and sub-category suggestions.

{
  "categories": [
    { "id": "cat_...", "kind": "EXPENSE", "label": "Food", "emoji": "🍜", "color": "#FF7043", "position": 0 }
  ],
  "subcategories": [
    { "id": "sub_...", "categoryId": "cat_...", "label": "Lunch", "position": 0 }
  ]
}

Create a category.

Update a category (label, emoji, color).

Delete a category. The last category of a kind can't be deleted (400); records of a deleted category fall back to a grey “Other”.

List businesses.

{ "businesses": [ { "id": "biz_...", "name": "Acme Cafe", "emoji": "🏢", "position": 0, "openingBalanceCents": 5200000, "openingBalanceNote": "Cash on hand" } ] }

openingBalanceCents / openingBalanceNote are admin-only figures: they are absent from a plain member's payload.

Create a business. Body: { "name": "Acme Cafe", "emoji": "🏢" }.

Rename / re-emoji a business (admins; a consumer-face user, their own business).

Set the business’s opening (starting) balance — the floor the running balance is computed from. Admins any business; a manager, one assigned to them; a consumer-face user, their own. No date is stored (the balance is simply “as of now”).

Returns your (role-scoped) { "businesses": [...] } list, updated.

Delete a business. Refused (400) while it still has records.

Rename what the workspace calls a “business” (e.g. Store/Stores). Body: { "singular": "Store", "plural": "Stores" } — both blank restores the default; a missing plural is derived; over 40 characters answers 400. Admins (workspace-wide; a consumer-face user sets their own). Returns { "businessLabel": { "singular": "Store", "plural": "Stores" } } (null when default). The current label is on the org info (GET /api/orgs/YOUR_HANDLE) as businessLabel.

List members and the businesses each is assigned to.

{ "members": [ { "id": "...", "username": "carlos", "displayName": "Carlos", "businessIds": ["biz_..."], "approvalRequired": false } ] }

Set a member’s businesses. Body: { "businessIds": ["biz_..."] }.

Set whether a member’s ledger writes need approval. Body: { "approvalRequired": true }. Members only (400 for an admin/manager target); signed-in admins — or a manager, for members within their own businesses — an API key answers 403.

The caller-scoped list of staged changes. An admin (or API key) sees every item AWAITING approval; a manager, those in their businesses; a member, only their own submissions — awaiting and declined.

{
  "approvals": [
    {
      "id": "apr_...",
      "action": "EDIT",                    // CREATE | EDIT | DELETE
      "expenseId": "exp_...",              // null for a CREATE
      "kind": "EXPENSE",
      "amountCents": 45000,                // proposed values (null for a DELETE)
      "categoryId": "cat_...",
      "businessId": "biz_...",             // the record's current business (a CREATE: the proposed one)
      "proposedBusinessId": null,          // set when an EDIT moves the record
      "subcategory": null,
      "note": "corrected amount",
      "spentAt": "2026-08-10T00:00:00.000Z",
      "status": "AWAITING",                // AWAITING | DECLINED
      "declineReason": "", "declinedBy": null, "declinedByName": "", "declinedAt": null,
      "submittedBy": "...", "submittedByName": "Ana",
      "submittedAt": "2026-08-10T09:00:00.000Z", "updatedAt": "2026-08-10T09:00:00.000Z",
      "current": { "…the live record as it stands (null for a CREATE)…": "…" }
    }
  ]
}

The submitter edits their own still-awaiting item in place (same body as a record write; its kind is fixed). Only the submitter — approvers approve or decline, never rewrite.

Approve a staged change: it is applied to the ledger (webhooks fire now) with the approver’s approvedBy/approvedAt stamp, and leaves the queue. Signed-in admins, or a manager whose businesses cover the change (both ends of a move) — an API key answers 403. If the record was deleted underneath a staged edit, answers 409 and discards the item. Approve with changes: send a record body (same shape as a create) to amend the proposal before approving — the amended values are what land, and the record’s history notes the amendment.

Discard a staged item. The submitter withdraws their awaiting item (or dismisses a declined notice); an approver declines an awaiting item — optional body { "reason": "…" } (≤ 280 chars) — leaving the ledger exactly as it was. Signed-in people only.

List the supported currencies and the workspace’s current one.

{ "currency": "PHP", "currencies": [ { "code": "PHP", "symbol": "₱", "name": "Philippine Peso", "decimals": 2 }, … ] }

Set the currency. Body: { "currency": "USD" }. Admins and managers set the workspace currency; on a consumer instance each user sets their own (it never affects anyone else). Signed-in only (an API key answers 403); an unsupported code answers 400. Returns { "currency": "USD" }.

List alert rules.

{ "rules": [ { "id": "thr_…", "enabled": true, "type": "record_over", "businessId": null, "kind": "EXPENSE", "thresholdCents": 5000000, "createdAt": "…", "updatedAt": "…" } ] }

Create a rule. Body: { "type": "record_over", "thresholdCents": 5000000, "businessId": null, "kind": "EXPENSE", "enabled": true }. Returns the refreshed list.

Update a rule (same body; omitted fields keep their value). Returns the refreshed list.

Delete a rule. Returns the refreshed list.

Submit the upgrade request. Body: { "orgName": "Santos Family Stores", "teamSize": "2-5", "notes": "…" } — orgName required (≤ 80 chars, becomes the workspace name), teamSize one of 1 | 2-5 | 6-15 | 16+, notes optional (≤ 2000). Returns 201 { "upgradeRequestedAt": "…" } and the same timestamp thereafter on GET /me. One open request at a time: a second submit answers 409 with the existing upgradeRequestedAt (also while an approved request is being set up); after a request was not approved (upgradeDecision on GET /me reads denied) a fresh submit is accepted and resets the decision. The request is forwarded to the Rooche support inbox (the same channel as Get help), so follow-ups happen there.

Turn a power-up on or off for the WHOLE workspace (organization workspaces). Body: { "key": "attachments", "enabled": true } — key must be a product power-up (400 otherwise), enabled a boolean. Admins only, signed-in humans only: managers and members answer 403, and so does an API key — enabling a workspace surface is an owning-role decision. Returns the refreshed { "powerUps": [ … ] } array (the same shape GET /me carries).

Turn one of YOUR power-ups on or off (personal/consumer face only — every organization-workspace role answers 403; an organization's switch is the admin PUT /power-ups above). Body: { "key": "attachments", "enabled": true } — key must be a product power-up (400 otherwise), enabled a boolean. Returns the refreshed { "powerUps": [ … ] } array. Every power-up starts off; until you switch one on, its feature endpoints answer 403 { "code": "power_up_off" } for you.

Mark the caller's own walkthrough as seen (both "Get started" and "Skip" call it). Idempotent — the first call stamps the current time, later calls keep the original. Returns { "ok": true, "walkthroughSeenAt": "…" }; the same timestamp rides GET /me thereafter. There is no way to clear it — the walkthrough shows once.

Reset data. Signed-in humans only: an organization ADMIN/SUPERADMIN clears ONE business — body { "businessId": "…", "confirm": "…" }, where businessId names a business of the workspace (404 otherwise); on the personal (consumer) face a signed-in person starts over — body { "confirm": "…" }, their whole tenant including the business itself. A MANAGER, a plain member, and an API key answer 403. confirm must equal the target business's name (RESET when it has none); a mismatch answers 400 and changes nothing. Returns { "mode": "business" | "start_over", "recordsDeleted", "businessesReset", "businessesDeleted" }.