Merge

Merge Agent Handler

Merge Agent Handler enables AI agents to connect with thousands of pre-built tools for taking real-time actions. It manages authentication, rate limits, error handling, Tool Packs that group connectors per agent, Registered Users for end-user identity, and security controls (standard entity rules + custom regex rules) that scan tool inputs and responses for sensitive data. Exposes both a REST management API and an MCP server surface the agent talks to directly.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.merge.dev/merge-agent-handler/agent-handler

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/merge/refs/heads/main/openapi/merge-agent-handler-api-openapi.yaml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/merge/refs/heads/main/json-schema/agent-handler-tool-pack-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/merge/refs/heads/main/json-structure/agent-handler-tool-pack-structure.json

Other Resources

🔗
Website
https://www.merge.dev/merge-agent-handler
🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/merge/refs/heads/main/json-ld/merge-agent-handler-context.jsonld
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/merge/refs/heads/main/examples/agent-handler-tool-pack-example.json
🔗
Support
https://help.ah.merge.dev/

OpenAPI Specification

merge-agent-handler-api-openapi.yaml Raw ↑ 
openapi: 3.1.0
info:
  title: Agent Handler
  version: 1.0.0
paths:
  /api/v1/connectors/:
    get:
      operationId: list
      summary: List connectors
      description: Retrieves a list of Connectors
      tags:
        - subpackage_connectors
      parameters:
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedConnectorDetailPublicResponseList'
  /api/v1/connectors/{slug}/:
    get:
      operationId: retrieve
      summary: Get connector
      description: Retrieves a Connector by slug
      tags:
        - subpackage_connectors
      parameters:
        - name: slug
          in: path
          description: The slug of the Connector
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorDetailPublicResponse'
  /api/v1/application-credentials/:
    get:
      operationId: list
      summary: List application credentials
      description: Lists OAuth application credentials for the organization.
      tags:
        - subpackage_applicationCredentials
      parameters:
        - name: external_id
          in: query
          description: Filter by external_id
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: slug
          in: query
          description: Filter by connector slug
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedApplicationCredentialPublicResponseList'
    post:
      operationId: create
      summary: Create application credential
      description: >-
        Creates an OAuth application credential for a connector. The `external_id` field is optional — omit it unless
        you need multiple OAuth apps for the same connector (e.g. one per customer tenant).
      tags:
        - subpackage_applicationCredentials
      parameters:
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCredentialPublicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCredentialPublicCreate'
  /api/v1/application-credentials/{id}/:
    get:
      operationId: retrieve
      summary: Get application credential
      description: Retrieves an OAuth application credential by ID.
      tags:
        - subpackage_applicationCredentials
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCredentialPublicResponse'
    delete:
      operationId: destroy
      summary: Delete application credential
      description: Deletes an OAuth application credential. This also deletes all associated user credentials.
      tags:
        - subpackage_applicationCredentials
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
    patch:
      operationId: partial-update
      summary: Update application credential
      description: >-
        Partially updates an OAuth application credential. Only fields included in the request body are updated; omitted
        fields are left unchanged. Pass null to explicitly clear a field (e.g. client_secret or external_id).
      tags:
        - subpackage_applicationCredentials
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCredentialPublicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedApplicationCredentialUpdate'
  /api/v1/credentials/registered-users/{registered_user_id}/connectors/{connector_slug}/:
    delete:
      operationId: registered-users-connectors-destroy
      summary: Delete credentials
      description: Deletes credentials for a Registered User's Connector
      tags:
        - subpackage_credentials
      parameters:
        - name: connector_slug
          in: path
          description: The slug of the Connector
          required: true
          schema:
            type: string
        - name: registered_user_id
          in: path
          description: Agent Handler ID of the Registered User
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
  /api/v1/access-keys/:
    get:
      operationId: list
      summary: List access keys
      description: Lists active access keys for the organization.
      tags:
        - subpackage_accessKeys
      parameters:
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAccessKeyList'
    post:
      operationId: create
      summary: Create access key
      description: >-
        Creates a new access key. Can be scoped to specific tool packs and registered users. The new key's scope must be
        a subset of the parent key (the access key authenticating this request).
      tags:
        - subpackage_accessKeys
      parameters:
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessKeyCreate'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessKeyCreate'
  /api/v1/access-keys/{key_id}/:
    get:
      operationId: retrieve
      summary: Get access key
      description: Retrieves an access key by id.
      tags:
        - subpackage_accessKeys
      parameters:
        - name: key_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessKey'
  /api/v1/access-keys/{key_id}/regenerate/:
    post:
      operationId: regenerate
      summary: Regenerate access key secret
      description: Rotates the secret of an existing access key. Scope and expiration are preserved; only the secret value changes.
      tags:
        - subpackage_accessKeys
      parameters:
        - name: key_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessKeyCreate'
  /api/v1/access-keys/{key_id}/revoke/:
    post:
      operationId: revoke
      summary: Revoke access key
      description: Revokes an access key. Revocation is permanent.
      tags:
        - subpackage_accessKeys
      parameters:
        - name: key_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
  /api/v1/audit-log/:
    get:
      operationId: list
      summary: List audit log events
      description: >-
        Retrieves a paginated list of audit log events for the organization. Events are ordered by creation time, with
        the most recent first.
      tags:
        - subpackage_auditLog
      parameters:
        - name: created_after
          in: query
          description: Filter events created on or after this date (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          description: Filter events created on or before this date (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
        - name: event_type
          in: query
          description: Filter by event type
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1AuditLogGetParametersEventType'
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: user_id
          in: query
          description: Filter by user ID
          required: false
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAuditLogEventPublicList'
  /api/v1/registered-users/:
    get:
      operationId: list
      summary: List Registered Users
      description: Retrieves a list of Registered Users
      tags:
        - subpackage_registeredUsers
      parameters:
        - name: origin_user_id
          in: query
          description: Filter by the origin user ID of the Registered User
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRegisteredUserPublicResponseList'
    post:
      operationId: create
      summary: Create Registered User
      description: Creates a Registered User with the given values
      tags:
        - subpackage_registeredUsers
      parameters:
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredUserPublicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisteredUserPublicRequest'
  /api/v1/registered-users/{registered_user_id}/:
    get:
      operationId: retrieve
      summary: Get Registered User
      description: Retrieves a Registered User by ID
      tags:
        - subpackage_registeredUsers
      parameters:
        - name: registered_user_id
          in: path
          description: Agent Handler ID of the Registered User
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredUserPublicResponse'
    delete:
      operationId: destroy
      summary: Delete Registered User
      description: Deletes a Registered User by ID
      tags:
        - subpackage_registeredUsers
      parameters:
        - name: registered_user_id
          in: path
          description: Agent Handler ID of the Registered User
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
    patch:
      operationId: partial-update
      summary: Update Registered User
      description: Updates fields on a Registered User by ID
      tags:
        - subpackage_registeredUsers
      parameters:
        - name: registered_user_id
          in: path
          description: Agent Handler ID of the Registered User
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredUserPublicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedRegisteredUserPublicRequest'
  /api/v1/registered-users/{registered_user_id}/link-token/:
    post:
      operationId: create-for-registered-user
      summary: Create Link token
      description: >-
        Generates a Link Token for a Registered User to authenticate with Connectors. Also returns a magic link URL that
        can be shared with the user to authenticate in a browser.
      tags:
        - subpackage_linkToken
      parameters:
        - name: registered_user_id
          in: path
          description: Agent Handler ID of the Registered User
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/linkToken_createForRegisteredUser_Response_201'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                connector:
                  type: string
                  description: Slug of the connector to generate a link token for
                external_id:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Optional external ID to scope the link token to a specific application credential. Use this when you
                    have multiple OAuth apps for the same connector.
                callback_url:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Optional URL to redirect the user to after they complete the authentication flow. Must be added to
                    your organization's allowed callback origins first.
                state:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Optional CSRF protection token returned to your callback_url after authentication. Requires
                    callback_url to be set. Do not include a 'state' query parameter in callback_url if using this
                    field.
              required:
                - connector
  /api/v1/tool-packs/:
    get:
      operationId: list
      summary: List Tool Packs
      description: Retrieves a list of Tool Packs
      tags:
        - subpackage_toolPacks
      parameters:
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedToolPackPublicList'
    post:
      operationId: create
      summary: Create Tool Pack
      description: Creates a Tool Pack with connectors
      tags:
        - subpackage_toolPacks
      parameters:
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolPackPublic'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolPackPublicWrite'
  /api/v1/tool-packs/{id}/:
    get:
      operationId: retrieve
      summary: Get Tool Pack
      description: Retrieves a Tool Pack by ID
      tags:
        - subpackage_toolPacks
      parameters:
        - name: id
          in: path
          description: Agent Handler ID of the Tool Pack
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolPackPublic'
    delete:
      operationId: destroy
      summary: Delete Tool Pack
      description: Deletes a Tool Pack by ID
      tags:
        - subpackage_toolPacks
      parameters:
        - name: id
          in: path
          description: Agent Handler ID of the Tool Pack
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
    patch:
      operationId: partial-update
      summary: Update Tool Pack
      description: Updates a Tool Pack by ID
      tags:
        - subpackage_toolPacks
      parameters:
        - name: id
          in: path
          description: Agent Handler ID of the Tool Pack
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolPackPublic'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedToolPackPublicWrite'
  /api/v1/tool-packs/{tool_pack_id}/connectors/:
    get:
      operationId: list-connectors
      summary: List connectors in a Tool Pack
      description: List the connectors attached to a tool pack, with the tools enabled on each connector.
      tags:
        - subpackage_toolPacks
      parameters:
        - name: tool_pack_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectorPublic'
    put:
      operationId: replace-connectors
      summary: Update connectors in a Tool Pack
      description: >-
        Replace a tool pack's connector list declaratively. Any connector not in the request body is removed from the
        tool pack.


        `tool_names` behavior per item:

        - Omitted: all tools are enabled on the connector.

        - `[]` (empty list): the connector is removed from the tool pack.

        - Otherwise: exactly these tools are enabled.


        Returns the updated list of connectors on the tool pack.
      tags:
        - subpackage_toolPacks
      parameters:
        - name: tool_pack_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectorPublic'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ToolPackConnectorBulkInput'
    patch:
      operationId: bulk-upsert-delete-connectors
      summary: Update connectors in a Tool Pack (partial)
      description: |-
        Partially update a tool pack's connectors. Connectors not listed in the request body are left untouched.

        `tool_names` behavior per item:
        - Omitted (new connector): all tools are enabled.
        - Omitted (existing connector): the connector's tools are left unchanged.
        - `[]` (empty list): the connector is removed from the tool pack.
        - Otherwise: exactly these tools are enabled.

        Returns the updated list of connectors on the tool pack.
      tags:
        - subpackage_toolPacks
      parameters:
        - name: tool_pack_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectorPublic'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ToolPackConnectorBulkInput'
  /api/v1/tool-packs/{tool_pack_id}/connectors/{slug}/:
    delete:
      operationId: delete-connector
      summary: Remove a connector from a Tool Pack
      description: Remove a single connector from a tool pack by slug. Returns 204 No Content.
      tags:
        - subpackage_toolPacks
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
        - name: tool_pack_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
  /api/v1/connectors/tool-description-overrides/:
    get:
      operationId: list
      summary: List tool description overrides (connector)
      description: List tool description overrides, optionally filtered by connector slug. Returns paginated results.
      tags:
        - subpackage_toolDescriptionOverrides
      parameters:
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: slug
          in: query
          description: Filter by connector slug.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedToolDescriptionOverrideList'
    patch:
      operationId: bulk-upsert-delete
      summary: Bulk upsert/delete tool description overrides (connector)
      description: >-
        Bulk upsert or delete tool description overrides. Send a list of items with connector_slug, tool_name, and
        description. Set description to null to delete an override.
      tags:
        - subpackage_toolDescriptionOverrides
      parameters:
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ToolDescriptionOverride'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BulkToolDescriptionOverrideInput'
  /api/v1/tool-packs/{tool_pack_id}/tool-description-overrides/:
    get:
      operationId: list-tool-pack
      summary: List tool description overrides (Tool Pack)
      description: List tool-pack-level description overrides, optionally filtered by connector slug. Returns paginated results.
      tags:
        - subpackage_toolDescriptionOverrides
      parameters:
        - name: tool_pack_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: A page number within the paginated result set.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: slug
          in: query
          description: Filter by connector slug.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Token-based authentication with required prefix "Bearer"
          required: true
          schema

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/merge/refs/heads/main/openapi/merge-agent-handler-api-openapi.yaml