# Discover Fin's capabilities

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`, `ask`, and `escalate` actions.
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**.

Endpoint: POST /fin/capabilities
Version: 2.18
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)

## Request fields (application/json):

  - `user` (object, required)
    The user to list capabilities for. If no user exists for the id, one is created from the supplied details; if the user already exists, the supplied email and attributes update it.

  - `user.id` (string, required)
    The ID of the user. This value will be used to uniquely identify the user
during a conversation with Fin. Maps to the user_id field on the Intercom User object.
    Example: 123456

  - `user.name` (string)
    The name of the user.
    Example: John Doe

  - `user.email` (string)
    The email of the user.
    Example: john.doe@example.com

## Response 200 fields (application/json):

  - `version` (string)
    The API version the capabilities document was generated for.
    Example: 2.17

  - `capabilities` (array)
    The list of capabilities available to this user, as tool definitions.

  - `capabilities.name` (string)
    The capability name. Procedures are named `run_procedure_<title_slug>_<id>`, with the slug cut to 80 characters, or `run_procedure_<id>` when the title gives no usable slug (for example a blank or non-Latin title); the static actions are named `reply`, `ask`, and `escalate`.
    Example: run_procedure_reset_password_12345

  - `capabilities.description` (string)
    A description of the capability. For a procedure, the text is wrapped in `<untrusted-content>` tags, and is null when the procedure has no description.
    Example: Send a user reply into an existing Fin conversation and get Fin's next turn. Use this to continue any ongoing conversation — including one opened by a procedure run — whenever its status is `awaiting_…

  - `capabilities.endpoint` (string)
    The endpoint path to call to use this capability.
    Example: /fin/procedures/12345/run

  - `capabilities.method` (string)
    The HTTP method to use.
    Example: POST

  - `errors` (object)
    Contains error details if any user or conversation attribute updates failed.

  - `errors.user` (object)
    User-related attribute errors.

  - `errors.conversation` (object)
    Conversation-related attribute errors.

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 403 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid