# 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 %}

 

Orchestrate Fin from your own agent: 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 hand off 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).

 

Starting a standalone conversation with `/fin/start` remains available for existing conversational integrations and is documented below.

 

**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): {% admonition type="info" name="Legacy — conversational mode" %}
/fin/start powers the conversational model, where your own UI drives a back-and-forth with Fin. This endpoint is no longer actively developed and is maintained only for existing integrations — new functionality lands on the orchestration endpoints.
{% /admonition %}

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.