# Fin documentation

> REST API documentation for integrating an agent backend.

MCP endpoint: /mcp (Streamable HTTP; tools: search_docs and get_doc).
Full documentation: /llms-full.txt
OpenAPI: /openapi.json

- [Introduction](/index.md): An agent backend for your application. Your interface, your users, one API.
- [Quickstart](/quickstart.md): Go from a verified user to your first agent response.
- [How Fin works](/concepts.md): Understand users, conversations, stable runs, financial operations and consent.
- [Base URL](/base-url.md): Use the API origin supplied for your deployment:
- [Authentication](/authentication.md): Every `/v1` request carries two credentials:
- [Pagination](/pagination.md): Lists take `cursor` and `limit` and return `data` and `nextCursor`, with `total` where documented. Pass `nextCursor` back unchanged; `null` means the end as of that read. Use the endpoint's schema for its limit and default.
- [Idempotency](/idempotency.md): `runs.start` accepts an optional client-chosen `runId`. Retry the same start with the same id and conversation to receive the same run id without duplicate work. Use a new id for a new instruction. A retry does not amend the already admitted input or profile.
- [Rate limits](/rate-limits.md): Requests are limited per partner key and per user. Defaults are 6,000 requests per minute per partner key and 300 per minute per user; deployment configuration can change those values. Inspect the response's rate-limit headers and honor `Retry-After` on `429`.
- [Compatibility](/compatibility.md): Document revision **2.0.0** is an intentional breaking reset of the earlier staging `/v1` contract: run and approval paths, resource identities and response types changed together. Existing integrations must update their requests and generated types. This reset is an explicit exception to the previous six-month notice promise; no prior notice or external client migration is claimed. The complete change record is `docs/api-reset-2.md` in the repository. The policy below applies to subsequent changes.
- [Errors](/errors.md): Every failure is an RFC 9457 problem (`application/problem+json`). `type` names the kind, `reason` is the machine-readable why, `retryable` says whether repeating the same request can succeed, and `requestId` is what to quote. A resource that belongs to someone else answers exactly like a missing one.
- [Events](/events.md): The journal and the stream carry one shape. On the stream, `id` is the journal `seq`, `event` is the type below, and `data` is a `{ delivery, seq, payload }` frame; resume with `Last-Event-ID` or `?cursor=`.
- [Streaming & events](/streaming.md): Follow an agent live and reconnect without losing its history.
- [Financial operations](/financial-operations.md): Read exact consent, frozen terms and settlement receipts for a financial request.
- [Docs for AI agents](/agents.md): Connect your coding assistant to the same documentation you read.
- [Create account](/api-reference/users/ensure.md): Provisions the verified identity's account. Idempotent: calling it again for an already-provisioned identity returns the same account unchanged. It is the only call an unprovisioned identity may make; every other endpoint requires this to have run first.
- [Get current account](/api-reference/users/me.md): Returns the caller's own account: its id, verified subject and when the credential expires. Lets a client learn its user id before it names one explicitly in another call.
- [Get account](/api-reference/users/get.md): Returns the caller's own account, addressed by the explicit `userId` in the path — the same shape every other user-scoped resource uses. Equivalent to `users.me`; the path's `userId` must equal the token's own account.
- [Start a conversation](/api-reference/conversations/create.md): Starts a new conversation for the caller, optionally titled. `conversations.list` and `conversations.activity` pick it up as soon as it exists; nothing needs to happen in it first.
- [List conversations](/api-reference/conversations/list.md): Lists the caller's ordinary conversations, newest created first. Automation execution conversations are addressable directly (`conversations.get`) but do not appear in this list; for conversations ordered by recent activity instead, see `conversations.activity`.
- [Get conversation](/api-reference/conversations/get.md): Returns one conversation by id: an ordinary conversation or an automation execution conversation, as long as the caller owns it. A conversation belonging to another user answers exactly like an unknown id.
- [Start an agent run](/api-reference/agent-runs/runs-start.md): Starts the model working on the conversation's next turn and answers 202 with the run's id at once; the work happens after the response. A client-chosen `runId` makes the call safe to retry: calling it again with the same id — whether the first call already created the run or is still being admitted — answers the same id rather than starting a second run. The run's progress and output follow on the journal and `runs.get`; a tool call that needs consent opens an approval and pauses the run until `approvals.approve` or `approvals.deny` decides it.
- [List agent runs](/api-reference/agent-runs/runs-list.md): Lists the caller-owned durable agent runs, newest first, optionally restricted to one conversation. Each result has the same complete representation as runs.get; continuation segments retain the same public run id.
- [Get an agent run](/api-reference/agent-runs/runs-get.md): Returns one run by id: its status, its output once it ends, and any approvals still waiting on a decision.
- [Stop an agent run](/api-reference/agent-runs/runs-abort.md): Asks the engine to stop the run named in the path; it must be the conversation's current live run. The call waits for the engine to confirm cleanup before answering. When this stop is what ends the run (`aborted: true`), the run's terminal `run.ended` event (status `aborted`) follows on the journal and the stream, and `runs.get` reports it once it lands.
- [List financial operations](/api-reference/financial-operations/financial-operations-list.md): Lists actual financial requests owned by the caller, including direct withdrawals and requests from agent runs or automation occurrences. Each resource includes immutable requested terms, exact approval and grant links, current lifecycle, safe frozen plan terms and all persisted leg receipts. Pagination does not truncate a resource or depend on journal replay.
- [Get a financial operation](/api-reference/financial-operations/financial-operations-get.md): Reads one retained financial request even when signing is unavailable. Execution started means its claim committed and the outcome may remain unresolved; it does not prove a process is live. An uncertain operation must never be resubmitted automatically. Reads do not execute or retry financial work.
- [Get activity overview](/api-reference/activity/overview.md): Combines active agent conversations, recent ordinary conversations and the newest page of historical milestones. This presentation read links to canonical agent runs and financial operations; activity.history pages older milestones.
- [List activity history](/api-reference/activity/history.md): Pages backward through durable user-owned milestones, including approvals, run lifecycle and settlement evidence. Omit the cursor for the newest page and pass the returned cursor to continue.
- [List financial activity](/api-reference/activity/financial-operations.md): Returns presentation rows for actual persisted financial requests, newest request first, including direct withdrawals with no conversation. FinancialOperations.get provides the complete canonical request and receipts for each operation identity.
- [List events](/api-reference/events/list.md): The conversation's durable journal, oldest first: every `FinEvent` a run, an approval, an automation trigger or a settlement appended, from the beginning or after the given cursor. `conversations.stream` delivers the same events live; this is how a client backfills what it missed or reads history without holding a connection open.
- [Stream events](/api-reference/events/conversations-stream.md): Opens a live `text/event-stream` (SSE) for one conversation: replays durable journal events strictly after the cursor, then delivers new events — durable and live — as they happen. Reconnect with `Last-Event-ID` or `?cursor=` to resume exactly where a dropped connection left off; `events.list` reads the same durable history without holding a connection open.
- [List approvals](/api-reference/approvals/list.md): Lists the caller's approvals, newest first. Defaults to `pending`; pass `status` to include decided or expired ones instead, or `all` for every status.
- [Get an approval](/api-reference/approvals/get.md): Returns the caller-owned approval and exact review input for agent or direct financial work.
- [Approve a tool call](/api-reference/approvals/approve.md): Approves the parked tool call named in the path and resumes the run that opened it, which takes its execution slot again exactly as new work does. If the resume cannot be admitted, the decision is not recorded and the approval stays pending; the call otherwise answers once the decision is durable. `approval.decided` follows at once on the journal, and `approval.consumed` follows once the approval is spent to authorize the call — immediately before it runs, not once it finishes; the call can still fail afterward.
- [Deny a tool call](/api-reference/approvals/deny.md): Denies the parked tool call named in the path and resumes the run that opened it so it can continue without the call's result, which takes its execution slot again exactly as new work does. If the resume cannot be admitted, the decision is not recorded and the approval stays pending; the call otherwise answers once the decision is durable, and `approval.decided` follows at once on the journal.
- [List files](/api-reference/artifacts/list.md): Lists the conversation's files, oldest first: uploads and files a sandbox command left in its outbox. Read one back with `artifacts.download`.
- [Attach a file](/api-reference/artifacts/upload.md): Attaches a file to the conversation. The request body is the file's raw bytes; `Content-Type` declares its media type, and `?name=` names it. The upload answers with the new artifact.
- [Download a file](/api-reference/artifacts/download.md): Downloads one file as an opaque attachment (`application/octet-stream`), whatever media type its uploader declared; a file is never rendered on the API's own origin.
- [Get agent wallet](/api-reference/wallets/get.md): Returns the user's agent wallet, or `null` if `wallets.ensure` has not created one yet. Never returns key material.
- [Create agent wallet](/api-reference/wallets/ensure.md): Creates the user's agent wallet if one does not exist yet, or returns the existing one — safe to call more than once. Also reconnects the provider session, so this is the call that clears `authorization_required`.
- [Get wallet balances](/api-reference/wallets/balances.md): Returns the wallet's current portfolio: every held asset with its provider price and USD value, and the total. Prices and balances are read live from the provider on each call.
- [List withdrawal sources](/api-reference/wallets/withdrawal-sources.md): Lists what the wallet can withdraw right now: each asset with a positive, transferable balance held in the agent wallet's own account, and the owner's main account a withdrawal would pay out to. Feeds `wallets.prepareWithdrawal`.
- [Prepare a withdrawal](/api-reference/wallets/prepare-withdrawal.md): Builds the exact withdrawal contract for the given asset and amount, and opens the approval that stands for it. Nothing is signed and no key is touched: this only returns the terms to review and the `fingerprint` that `wallets.confirmWithdrawal` must echo back unchanged.
- [Get a withdrawal](/api-reference/wallets/get-withdrawal.md): Reads the retained direct withdrawal resource without requiring a signing provider. After an interrupted confirmation, query this id to recover the recorded outcome; execution_started or uncertain must not cause automatic resubmission.
- [Confirm a withdrawal](/api-reference/wallets/confirm-withdrawal.md): Confirms the exact reviewed withdrawal and atomically spends its approval while claiming the financial operation. A duplicate confirmation returns the retained outcome or unresolved resource without executing again. Authority and terms are rechecked before dispatch; a consumed approval does not imply funds moved. The durable withdrawal lookup and financial operation resource retain pending, refused, uncertain and settled outcomes. Never automatically retry an unresolved financial action.
- [Get spend headroom](/api-reference/budgets/headroom.md): Reports whether the caller can spend right now: the day and month caps, what is reserved by runs in flight, what is already spent, and any operator freeze. Admission checks this same headroom before it lets a run start.
- [List event sources](/api-reference/automations/automation-sources-list.md): Lists the event sources an automation's rule may watch, each with its configuration schema, its data fields, and this owner's current ability to use it. Reading the catalog does not fetch a live value or create a connection.
- [List automations](/api-reference/automations/list.md): Lists the user's automations, oldest first, each with its current monitoring health and its active or most recent occurrence. `filter` narrows by lifecycle state.
- [Preview rule](/api-reference/automations/preview.md): Checks a rule without saving it, and reports what it would do: its next scheduled wake times, a plain-language summary of its behavior, and how each of its source bindings would be collected.
- [Get automation](/api-reference/automations/get.md): Returns one automation: its rule, its current sources, its monitoring health, and its active or most recent occurrence.
- [Archive automation](/api-reference/automations/remove.md): Archives the automation: it stops firing for good and cannot be resumed. Already-archived is answered the same way, so calling this more than once is safe.
- [List occurrences](/api-reference/automations/history.md): Lists the automation's occurrences, newest first: what fired, when, and the run it produced, if any.
- [Resume firing](/api-reference/automations/enable.md): Resumes a paused automation: its clock and readers restart, and its sources are re-planned before firing resumes. Refused if an operator holds the automation, if its rule no longer compiles or plans cleanly, or if the automation carries a contract — once withdrawn, a contract's standing authority cannot be re-approved by resuming; create a new automation instead.
- [Pause firing](/api-reference/automations/disable.md): Pauses the automation: its clock and readers stop, its pending occurrences are canceled, and any contract's standing authority is withdrawn. `automations.enable` resumes it later — except a contract automation, which cannot be resumed once paused.
- [Fire now](/api-reference/automations/invoke.md): Fires the automation immediately, bypassing its rule's condition. `revision` must match the automation's current one, and `idempotencyKey` makes the call safe to repeat: calling again with the same key before it finishes answers the same outcome rather than firing twice. The occurrence this creates, and the run it produces, follow through `automations.history`.
- [Send signal](/api-reference/automations/signal.md): Hands the rule's condition an event to evaluate, as if a source had delivered it; `automations.invoke` bypasses that decision instead. `revision` must match the automation's current one, and `idempotencyKey` makes the call safe to repeat: calling again with the same key answers the same outcome rather than recording it twice.
- [Rotate webhook secret](/api-reference/automations/rotate-webhook-secret.md): Mints a new inbound webhook secret for the automation; the previous one stops working at once. Only works on an enabled automation whose rule has an event wake: anything else is refused as `automation_changed`, the same reason a stale `revision` gets, even when the revision sent is perfectly current. `revision` must match the automation's current one.
- [Test condition](/api-reference/automations/test-condition.md): Evaluates the automation's condition once, against the given event when one is supplied or against its retained source data otherwise. Nothing is recorded and the automation does not fire.
- [Search automations](/api-reference/automations/search.md): Searches the user's automations, oldest first, matching every given word as a whole token against the name, prompt and reviewed rule description (the same text `automations.status` reports as `behavior`). `state` narrows by lifecycle. The page is small and bounded to a byte cap, meant for a model to read back mid-conversation rather than to browse — see `automations.list` for that.
- [Get automation status](/api-reference/automations/status.md): The bounded, model-readable state of one automation: its lifecycle, its overall monitoring status, its most recent evaluation and occurrence. Unlike `automations.get`, evidence here is fixed-size and reviewed for a conversation, never the raw stored value.