# Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.
 
To request access to the Fin Agent API, please [fill out this form](https://forms.gle/osy4uyiqyomRCsL2A).
 
Server-Sent Events (SSE) is available by application only. Contact your account team or Customer Support to request access.
 
Integration centres on the Fin Agent API endpoints — start a conversation with `/fin/start` and continue it with `/fin/reply`, or drive Fin from your own agent with `/fin/capabilities`, `/fin/ask`, `/fin/procedures/{procedure_id}/run`, and `/fin/escalate` — plus a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.
 
**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](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 (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)
- `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`)

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

 - [POST /fin/start](https://developers.intercom.com/docs/references/2.14/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
 - [POST /fin/reply](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/replytofin.md): Once Fin has returned a response to a user's message, its status will be `awaiting_user_reply`. If a user replies, use this endpoint to send this response to Fin. To request access to the Fin Agent AP
 - [POST /fin/csat](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/submitfincsat.md): Record a customer's satisfaction rating for a conversation, with an optional free-text remark. Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin workflow, not this API
 - [POST /fin/capabilities](https://developers.intercom.com/docs/references/2.14/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: ea
 - [POST /fin/ask](https://developers.intercom.com/docs/references/2.14/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,
 - [POST /fin/procedures/{procedure_id}/run](https://developers.intercom.com/docs/references/2.14/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 as
 - [POST /fin/escalate](https://developers.intercom.com/docs/references/2.14/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 exist
 - [Fin Agent Attachment](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_attachment.md): Schema: #/components/schemas/fin_agent_attachment
 - [Fin Agent Attribute Errors](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_attribute_errors.md): Schema: #/components/schemas/fin_agent_attribute_errors
 - [Fin Agent Conversation Metadata](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_conversation_metadata.md): Schema: #/components/schemas/fin_agent_conversation_metadata
 - [Fin Agent CSAT Requested Event](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_csat_requested_event.md): Schema: #/components/schemas/fin_agent_csat_requested_event
 - [Fin Agent Message](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_message.md): Schema: #/components/schemas/fin_agent_message
 - [Fin Agent Replied Event](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_replied_event.md): Schema: #/components/schemas/fin_agent_replied_event
 - [Fin Agent Reply Chunk Event](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_reply_chunk_event.md): Schema: #/components/schemas/fin_agent_reply_chunk_event
 - [Fin Agent Status Updated Event](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_status_updated_event.md): Schema: #/components/schemas/fin_agent_status_updated_event
 - [Fin Agent User](https://developers.intercom.com/docs/references/2.14/rest-api/api.intercom.io/fin-agent/fin_agent_user.md): Schema: #/components/schemas/fin_agent_user