Agent API

The Agent API is a read-only HTTP surface AI agents (Claude, Cursor, custom bots) and external integrations use to read your Cash Runway data. Every endpoint is JSON, bearer-token authenticated, and scoped — see API keys for how to provision one.

This guide is the high-level operator tour. If you're handing a key to an engineer, point them at the API reference for the full schema catalogue.

Endpoint surface at a glance

Endpoint	Required scope	What it returns
GET /api/agent/status	any	Subscription, query-credit usage, and key context. Session bootstrap. Exempt from query-credit counting.
GET /api/agent/bank-accounts	READ_BANK	Active bank accounts and balances (reconciled + statement).
GET /api/agent/cash-position	READ_FORECAST	Today's cash position with per-account breakdown.
GET /api/agent/forecast	READ_FORECAST	The 13-week rolling forecast.
GET /api/agent/invoices	READ_INVOICES	AR invoices. Filter by status, contact, date range. Optional ?lines=true.
GET /api/agent/bills	READ_INVOICES	AP bills. Same shape as /invoices.
GET /api/agent/contacts	READ_CONTACTS	Customers and suppliers. Filter by type, sort by revenue / spend / recency.
GET /api/agent/contacts/{id}	READ_CONTACTS	Single-contact drill — LTV, payment cadence, ABC tier, recent paid invoices.
GET /api/agent/daily-summary	READ_SUMMARY	Composite "how's my business going?" surface with a prose narrative.

Pick the narrowest scope set the integration needs. Sensitive-data gating applies automatically — see API keys.

Start here: daily-summary

For a generic AI assistant, daily-summary is the right first call. It returns enough context for an LLM to answer "how's my business going today?" in a single request:

• cashToday — current cash position and bank-account count.
• last7d — net cash flow plus top 5 inflows and top 5 outflows.
• ar — aging buckets (current / 30 / 60 / 90+).
• anomalies — pending anomaly count.
• forecast13w — ending cash, lowest point, break-even date.
• narrative — deterministic 2-4 sentence prose summary. The LLM doesn't need to derive "business is doing well" from raw numbers — the endpoint says so.
• notesForAgent[] — plain-language signals (seasonality, AR risk, customer concentration) the LLM can quote without re-deriving.

Provision a key with just READ_SUMMARY to start; add the narrower scopes later when the assistant needs to slice deeper.

Example call

Every endpoint takes a bearer token in the Authorization header:

curl -sS https://app.cashrunway.ai/api/agent/daily-summary \
  -H "Authorization: Bearer $CASHRUNWAY_API_KEY" \
  -D - | jq

The -D - flag prints response headers — X-CashRunway-Quota-Remaining is the one worth reading on every call. When quota drops below 10%, the response body folds in a billingAlert field.

See Agentic API — Example calls for curl, TypeScript, and Python recipes against the full endpoint set.

Tool tagging (for MCP / CLI clients)

Every endpoint accepts an optional X-CashRunway-Tool request header. MCP servers and CLI clients set it to record the calling tool name in the audit log (e.g. X-CashRunway-Tool: cashrunway.list_invoices). The value must match ^cashrunway\.[a-z_]+$ — bad values are silently ignored.

Operators using curl, direct fetch, or any current production integration don't need to set this header. It costs nothing to add (quota counts once per request either way) but adds nothing if the only consumer is your own script.

Rate limits

• Per-key burst cap: 60 requests per minute per endpoint.
• Query credits: metered per (user, account) in a rolling 5-hour window — Free 10 / Pocket 50 / Wallet 250 / Vault 1,000 / Reserve 5,000 per window. Credits free up continuously as each call ages past 5 hours; the usage block reports remaining, nextCreditInMinutes, fullResetInMinutes, and windowResetAt. Run dry and you can upgrade or let Cushion top up. See Plans, query credits & accounts.
• /api/agent/status is exempt from query-credit counting — agents can poll it freely for session bootstrap.

See the API reference overview for the full header contract and response-shape catalogue.

Related

• API keys — provisioning, rotation, audit.
• API Reference — full schema and per-endpoint detail.
• Agentic API — Example calls — curl, TypeScript, Python snippets.