# Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

{% admonition type="warning" %}
Please reach out to your accounts team to discuss access and tailored, hands-on support.
{% /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`, and continue a conversation with `/fin/reply`. 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.

## 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.