SaaSFlow

Move one account into a different account group, or send `accountGroupId: null` to take it out of every group. Grouping is presentational and does not affect balances. Use `/accounts/reorder` when you also need to set the position inside the target group. Fails with 404 if the account or the group does not exist.

accounts_change_group

Create an account. Use `importType: "manual"` for one you will fill by hand or by CSV; accounts fed by a bank connection are created by the integration itself. `includeInCashBalance` decides whether it counts towards the cash position, which is usually false for loans. Pass `initialBalance` to seed the opening balance so the running balance is right from day one, dated before any transaction you then import. `order` is required and sets its position in the list.

accounts_create

Get the day-by-day cumulative balance across accounts, returned as `[date, balance]` tuples. Unlike the per-account balances endpoint, these are converted into the company's base currency and summed, so this is the series to plot as a cash curve. Restrict it to specific accounts with a comma-separated `accountIds`.

accounts_daily_balance

Delete an account and cascade-delete every transaction on it, along with their categorizations. That rewrites cash balances and the P&L for every period the account covered, so archive it instead when the intent is only to get it off the screen.

accounts_delete

Retrieve a single account with the integration managing it, if any. Returns 404 if the account does not exist or belongs to another company.

accounts_get

Get the account's initial-balance seed, the synthetic transaction that carries whatever the account held before its first imported transaction. Returns `{ transaction: null }` when no seed exists, which is the usual reason a running balance looks right in shape but wrong by a constant amount.

accounts_initial_balance

List a company's accounts (bank, cash, credit card, loan, transit, other) with the integration managing each one, where there is one. `includeInCashBalance` decides whether an account counts towards the cash position, so a loan or a holding account can be excluded from it. Archived accounts are included; filter on `archived` for the live ones. Transaction counts and last-transaction dates only appear for callers with `transactions:read`.

accounts_list

Permanently delete this one account's transactions before `beforeDate` and replace them with a single balance transaction, so the running balance stays correct while the detail goes away. Useful for trimming a long import back to the period the books actually start from. For the company-wide version that also sets the data start date, use `POST /accounts/remove_history`.

accounts_remove_history

Permanently delete transactions before `beforeDate` on the listed accounts and set the company data start date, so reporting begins from a clean, fully covered period. Each collapsed account gets an initial-balance seed so its running balance still ends up right; supply `initialBalances` for accounts with no existing seed, such as CSV wallets whose uploads started late, otherwise the seed is derived from the recorded sum. Pass an empty `accountIds` to only move the data start date. Accounts left with no transactions are archived and returned in `archivedAccountIds`. Transit accounts are refused with 422. This cannot be undone, so preview first.

accounts_remove_history_bulk

Preview what cutting off history before a date would do, without changing anything. Returns per-account transaction counts and date ranges, plus `suggestedDate`: the earliest date from which every account has data, which is the point where the books stop having gaps. Loan accounts are ignored when computing it, since their data only spans payout to final repayment and a late loan is not a coverage gap. Only accounts with transactions are listed, and transit accounts are left out. Always run this before `remove_history`.

accounts_remove_history_preview

Reorder accounts inside one group, and move them into it in the same call. Every id in `accountIds` is assigned to `accountGroupId` (null for the ungrouped list) and given an `order` matching its position, so send the full contents of the target group rather than just the account that moved. Fails with 404 if the group does not exist.

accounts_reorder

Set or correct the account's opening balance, creating the seed transaction if there is none. `value` is the balance on `date` in the account's default currency, not a delta. The date has to fall strictly before every other transaction on the account: otherwise you get 422 with `initial_balance_not_first` and the `earliestDate` to go before. Accounts managed by an integration that does not allow hand-set balances are refused with `integration_managed`.

accounts_set_initial_balance

Detach an account from the integration feeding it and make it manually managed. Existing transactions stay; new ones stop arriving automatically and the account becomes editable by hand. Use this when a bank connection is being retired but its history should survive. Reconnecting later means setting the integration up again.

accounts_switch_to_manual

Bring an archived account back into the active lists. Nothing about its transactions changes; only its visibility does.

accounts_unarchive

Update an account. Only the fields you send change. Two rules are enforced here: transit accounts may not change their type or currency (422), and a company can hold only one active transit account per currency, so creating a second is refused with 409 until the existing one is archived. Changing `defaultCurrency` on an account that already has transactions does not restate them.

accounts_update

List the agents that can be run for this company, each with a title and a description of what it does. The `id` here is the `definitionId` you pass when starting a run. Read this first rather than hard-coding an id, since the catalogue changes as agents are added.

agent_definitions_list

Start an agent run. `definitionId` comes from the agent-definitions endpoint and `input` carries that agent's parameters. Returns a `runId` immediately; the agent works in the background, so poll the run or its messages. To continue a finished session rather than start fresh, pass `resumeFromRunId` and put the follow-up instruction in `input.prompt`; the earlier transcript is restored. Because agents send company data to an AI provider, a company that has not consented gets 403 with `code: "aiConsentRequired"` and the `providerKey` to request. The caller also needs every permission the agent uses, not just `transactions:read`. One run at a time per company (409), with a per-company rate limit (429, carrying `retryAt`).

agent_runs_create

Retrieve one agent run: its status, the input it was started with, and its result once finished. Poll this after starting a run. Returns 404 if the run does not exist or belongs to another company.

agent_runs_get

List this company's agent runs, past and in progress, with their status and which definition they came from. Use it to find a run id, or to check whether an agent is already working before starting another one.

agent_runs_list

Send a follow-up message to a running interactive agent, up to 8000 characters. The message is queued rather than answered inline, so poll the messages endpoint for the reply. Runs that are not interactive reject this with 400, and a session that has already ended returns 409; start a new run, or resume the finished one, instead.

agent_runs_messages_create

Read the conversation of an agent run, oldest first. Poll with `afterId` set to the last id you saw to stream new messages without refetching the thread. Reading a run requires the permissions the agent itself used, so a caller with narrower access than the person who started it gets 403 rather than a filtered view.

agent_runs_messages_list

Download the full session transcript as JSON Lines: every message and every tool call the agent made, which is the record to read when debugging what an agent actually did. Transcripts run to megabytes, so pass `tailBytes` to take only the end of the run (the cut is aligned to a line start). Without it a transcript that is too large is refused with 413. Content type is `application/x-ndjson`, not JSON.

agent_runs_transcript

Grant this company consent to share data with one AI provider. Only a company owner can do this. Send the `disclosureVersion` that was actually shown to the person accepting: if the disclosure has changed since, the request is refused with 409 and the new disclosure has to be shown again. That keeps every recorded consent tied to the exact text it was given against.

ai_consents_create

Revoke this company's consent for one AI provider. Agent runs already in flight are allowed to finish; new runs that need the provider are blocked from here on. Returns 404 when there was no active consent to revoke.

ai_consents_delete

List every AI provider SaaSFlow can send company data to, with the current disclosure for each (which agents use it, which models, what data leaves the account, where it is processed) and whether this company has an active consent. Providers without an active consent are still listed, with a null consent. AI features that need a provider stay blocked until consent is granted.

ai_consents_list

Use this when the user asks for summary SaaS metrics (MRR, ARR, NRR, GRR, churn, LTV, CAC, burn rate, runway) over a period. Requires permissions: financials:read.

data_analytics

Retrieve one background task by id to check whether it is still running, what it produced, or why it failed. Returns 404 if the task does not exist or belongs to another company.

background_tasks_get

List background tasks for a company. Long-running work such as bank syncs, imports, and bulk edits runs asynchronously and reports progress here. Poll this after kicking off an operation that returns a task id, and read `status` to tell running from finished and failed. Tasks with `visible: false` are high-frequency webhook refreshes that the app hides from its pending indicator; skip them if you are mirroring that behaviour. Type-specific counters (processed, total, new transactions) live in `data`.

background_tasks_list

Use this when the user asks for cash/bank balances charted over time. Requires permissions: balances:read.

data_balanceTimeSeries

Use this when the user asks how balances are split across cash types (operating, reserve, savings, etc.). Requires permissions: balances:read.

data_balanceByCashType

Use this when the user asks for cash inflows and outflows over time. Requires permissions: transactions:read, balances:read.

data_cashFlowTimeSeries

Use this when the user asks which categories drive cash inflows or outflows in a period. Requires permissions: transactions:read.

data_cashFlowByCategory

Delete several categories at once. All or nothing: if any id in the list is a system category, or still has transactions or planned transactions attached, nothing is deleted and the call fails with 400 or 409.

categories_batch_delete

Create a category. `plTypes` decides where transactions in it land in the P&L, and `order` sets its position in the list. Leave `system` at its default of false; system categories are SaaSFlow-managed and behave differently on delete.

categories_create

Delete a category. Refused with 409 while any transaction is still categorized under it or any planned transaction still uses it, and with 400 for system categories, which SaaSFlow manages. To retire a category that is in use, merge it into another one instead.

categories_delete

Retrieve a single category by id. Returns 404 if the category does not exist or belongs to another company.

categories_get

List a company's transaction categories. Each category declares the P&L lines it can post to through `plTypes` (revenue, cogs, cac, pd, ga, no, neutral), which is what lets one category split across the P&L. `used` counts everything currently assigned to the category, both transactions and planned transactions, so a zero there means the category can be deleted outright; `usedTransactions` and `usedPlannedTransactions` break that total down. Categories flagged `system` are created and maintained by SaaSFlow and cannot be deleted at all.

categories_list

Merge several categories into one, in a single transaction. Creates the category described by `newCategory`, then repoints everything that referenced the old ids: transaction categorizations, the default categorization on customers and vendors, and the default category on accounts. The old categories are deleted afterwards. This is how to retire duplicates without stranding history, since a plain delete is refused while transactions still use the category. One thing to know before running it: plan items on the old categories are deleted rather than repointed, so a merge drops that part of the financial plan. Returns the new category.

categories_merge

Set the display order of categories. Each id's `order` becomes its position in the array you send, so send the full list rather than the few you moved.

categories_reorder

Update a category's name, emoji, `plTypes`, or order. Only the fields you send change. Narrowing `plTypes` does not rewrite transactions already categorized under the removed P&L type, so check reporting after a change like that.

categories_update