# Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

{% admonition type="warning" %}
To request access to the Fin Agent API, please [fill out this form](https://forms.gle/osy4uyiqyomRCsL2A).
{% /admonition %}

 

Use the Fin Agent API as a tool: your agent stays in control and calls Fin capabilities as needed — discover what Fin can do with `/fin/capabilities`, ask a one-shot question with `/fin/ask`, run a specific procedure with `/fin/procedures/{procedure_id}/run`, continue a conversation with `/fin/reply`, and escalate to a human with `/fin/escalate`. Fin notifies your application of its status and responses through a set of events, delivered via webhooks or Server-Sent Events (SSE).

 

You can also start a standalone conversation with `/fin/start`, where Fin owns the conversation and passes control back when it's done.

 

**Pricing**

Fin Agent API conversations are billed on **outcomes**: you're charged at most once per conversation, and only when Fin reaches a billable outcome such as a resolution. Pricing for the orchestration endpoints is being finalised while they're in Preview. See [Understanding Fin outcomes](https://www.intercom.com/help/en/articles/13513868-understanding-fin-outcomes).

 

**Events**

Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details.

- `fin_status_updated` - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete)
- `fin_replied` - Fired when Fin sends a reply to the user
- `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled)

All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation.


## Discover Fin's capabilities

 - [POST /fin/capabilities](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/fin-agent/listfincapabilities.md): Return a machine-readable, per-user list of what Fin can do for a given end user, so an
orchestrating agent can decide which endpoint to call.

The response is audience-matched to the supplied user: each live, API-triggerable
procedure is checked against that user before being included, alongside the static
reply and ask actions.

## Ask Fin

 - [POST /fin/ask](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/fin-agent/askfin.md): Ask Fin a single, self-contained question and receive one informational answer.

Unlike a conversation, /fin/ask is non-conversational: Fin will not ask follow-up
questions, will not run procedures, and will not escalate to a human.

Fin's answer is delivered asynchronously via the fin_replied event. The conversation
ends with a complete status — there is no awaiting_user_reply cycle.

## Reply to Fin

 - [POST /fin/reply](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/fin-agent/replytofin.md): Send a follow-up message in an existing conversation. When Fin needs more information to
complete an action, it sets the conversation to awaiting_user_reply — send the user's
response so Fin can continue.

## Run a Fin procedure

 - [POST /fin/procedures/{procedure_id}/run](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/fin-agent/runfinprocedure.md): Deterministically run a specific procedure on a new conversation. Calling this endpoint
guarantees that the named procedure runs — there is no non-deterministic routing.

Fin's progress is delivered asynchronously via events or Server-Sent Events. If the
procedure pauses for user input, the conversation status becomes awaiting_user_reply —
send the user's response with /fin/reply.

## Escalate to a human

 - [POST /fin/escalate](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/fin-agent/escalatefinconversation.md): Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the
handoff lands in your team inbox.

Provide either conversation_id or user:

- conversation_id — escalate an existing agent conversation. By default, Fin summarises
  the conversation and opens a new Helpdesk conversation that carries the summary as an
  internal note; the original agent conversation is not reassigned. Configure an escalation
  Operator Workflow to change this default.
- user — escalate on behalf of a user with no prior agent conversation. A new Helpdesk
  conversation is created for the teammate. Include an optional message for its first
  message.

In both cases the optional context is attached as an internal note (supplied by your
orchestrating agent, not generated by Fin) alongside any summary.

You are notified over the existing webhook or SSE channel with an escalated status
followed by complete. The complete status signals that Fin is done; it does not close
the conversation, which remains open in the human inbox.

## Start a conversation with Fin

 - [POST /fin/start](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/fin-agent/startfinconversation.md): Initialize Fin by passing it the user's message along with conversation history and user details.

These additional pieces of context will be used by Fin to provide a better and more contextual answer to the user.

Once Fin is initialized, it progresses through a series of statuses such as thinking, replying, awaiting_user_reply, or resolved before ending with a status of complete.

During this workflow, the client should allow Fin to continue uninterrupted until a final complete status is returned, at which point control of the conversation passes back to the client.

Events can be received via webhooks or Server-Sent Events (SSE) using the sse_subscription_url in the response.

Pricing

Conversations you start with /fin/start are billed on outcomes: you're charged at most once per conversation, and only when Fin reaches a billable outcome such as a resolution. See Understanding Fin outcomes.