Skip to content

Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

To request access to the Fin Agent API, go to Settings > Integrations > Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent > Deploy.

 

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, escalate to a human with /fin/escalate, and record a satisfaction rating with /fin/csat. Fin notifies your application of its status and responses through a set of events, delivered via webhooks.

 

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.

 

Events

Configure a webhook endpoint in the Fin Agent API settings to receive events. See the setup guide 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
  • 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.

Fin Agent Message

A message exchanged within a Fin Agent conversation.

authorstringrequired

The author that created the message. In conversation_metadata.history, only user and agent are accepted.

Enum:"user""agent""fin"
Example:"user"
bodystringrequired

The body of the message. Accepts both plain text and HTML format. For the message you send to Fin, this is the user's message. For an agent item in conversation_metadata.history, it is the agent's message. Fin's response is returned in the format set by response_format (HTML by default).

Example:"How can I see my account details?"
timestampstring, (date-time)

The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision. Send timestamp or timestamp_ms; at least one is required. If you send both, timestamp_ms is used. On the top-level message, sending neither fails with a 422 error (message: timestamp_ms is required). In conversation_metadata.history, an item with neither causes the whole history to be ignored.

Example:"2025-01-24T10:01:20.000Z"
timestamp_msstring, (date-time)

The timestamp when the message was created, with millisecond precision. Accepted in place of timestamp when you send a message, and also present in event responses (fin_replied). At least one of timestamp or timestamp_ms is required.

Example:"2025-01-24T10:01:20.456Z"
{ "author": "user", "body": "How can I see my account details?", "timestamp": "2025-01-24T10:01:20.000Z", "timestamp_ms": "2025-01-24T10:01:20.456Z" }