> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute tool

> Run a tool by its slug with the arguments you provide. Use this when building agents or automation that need to call tools (e.g. send email, call an API).



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/tools/execute/{toolSlug}
openapi: 3.0.0
info:
  title: Flowra API (API Key Endpoints)
  description: >-
    **Flowra** is an AI-powered platform for building agents, workflows, and
    integrations.


    ### Capabilities

    - **Tools & Toolkits** – Define and group tools for agents and workflows.

    - **Workflows** – Orchestrate steps and automate processes.

    - **Triggers** – Schedule or event-based execution.

    - **Auth & Connections** – OAuth, API keys, and connected accounts.

    - **MCP** – Model Context Protocol server integration.

    - **Knowledge / RAG** – Add files and URLs for retrieval-augmented
    generation.


    ### Authentication

    Use the **x-api-key** header with a project API key to access endpoints that
    support API Key auth. Create and manage API keys in the dashboard under your
    project settings.


    Only endpoints that support API Key authentication via the @ApiKeyEnabled()
    decorator.


    Send x-api-key (required). On multi-tenant endpoints, optionally send
    x-username to act as an external user.
  version: '1.0'
  contact:
    name: Flowra
    url: https://flowra.dev
servers:
  - url: https://flowra.dev
    description: Flowra API
security: []
tags:
  - name: Users
    description: User profile
  - name: External Users
    description: End-user identities inside a project (x-username)
  - name: Auth Configs
    description: OAuth and API key configs for toolkits
  - name: Connected Accounts
    description: OAuth connected accounts and link creation
  - name: Toolkits
    description: List and search toolkits
  - name: Tools
    description: List, execute, and manage tools
  - name: Skills
    description: Browse, create, import, and install skills
  - name: Workflow & Agent
    description: Create, run, and inspect workflows and agents
  - name: Triggers
    description: Schedule and event-based trigger instances
  - name: Chat
    description: Threads and streaming agent runs
  - name: File
    description: Upload, list, and download files
  - name: Knowledge
    description: RAG knowledge collections
  - name: Table
    description: Collections and documents
  - name: Sandbox
    description: Ephemeral and durable code sandboxes
  - name: Browser
    description: Live browser sessions and view
  - name: LLM
    description: List AI models and generate completions
  - name: MCP
    description: MCP server management
  - name: usage
    description: Credit balance and usage ledger for the project API key
paths:
  /api/v1/tools/execute/{toolSlug}:
    post:
      tags:
        - Tools
      summary: Execute tool
      description: >-
        Run a tool by its slug with the arguments you provide. Use this when
        building agents or automation that need to call tools (e.g. send email,
        call an API).
      operationId: ToolsController_executeTool
      parameters:
        - name: toolSlug
          required: true
          in: path
          description: Tool slug from DISCOVER / GET /tools (e.g. gmail_send_email)
          schema:
            example: gmail_send_email
            type: string
        - name: x-username
          in: header
          required: false
          description: >-
            External user (end user) to act as. Optional — if omitted, Flowra
            uses the project’s default external user. Send a stable username
            (e.g. customer_alice) only when you need another end-user context.
          schema:
            type: string
            default: (project default user)
          example: customer_alice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteToolDto'
      responses:
        '200':
          description: Tool executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteToolResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  data: {}
                  error: Invalid credentials
                  successful: true
                  sessionInfo: {}
                  logId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteToolResponseDto'
      security:
        - x-api-key: []
        - x-api-key: []
          x-username: []
components:
  schemas:
    ExecuteToolDto:
      type: object
      properties:
        connectedAccountId:
          type: string
          description: Connected account ID
          example: account_123
        mcpServerId:
          type: string
          description: MCP server owner id (toolsMode / discovery / pins)
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        metaSessionId:
          type: string
          description: Ephemeral meta session id from DISCOVER_TOOLS
          example: meta_sess_01HZX
        version:
          type: string
          description: Tool version
          example: 2.0.0
        customAuthParams:
          $ref: '#/components/schemas/CustomAuthParamsDto'
        customConnectionData:
          $ref: '#/components/schemas/CustomConnectionDataDto'
        arguments:
          type: object
          description: Tool arguments matching the tool’s input JSON Schema
          additionalProperties: true
          example:
            channel: '#general'
            text: Hello from Flowra
        text:
          type: string
          description: Natural language description of what to accomplish
          example: 'Send a message to the #general channel'
        allowTracing:
          type: boolean
          description: Allow tracing for debugging
          example: false
          default: false
        proxyUrl:
          type: string
          description: >-
            One-off outbound proxy for this execution only (http(s) or socks).
            Not persisted in outbound_proxies. Takes precedence over the server
            default proxy and over proxyUrl on connection val.
          example: http://127.0.0.1:7890
        invokeViaMcp:
          type: boolean
          description: 'Internal: MCP invocation flag'
          default: false
        preferOwnerConnectionBinds:
          type: boolean
          description: 'Internal: prefer owner connection binds'
          default: false
    ExecuteToolResponseDtoSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          type: object
          properties:
            data:
              type: object
              description: Tool execution result data
              additionalProperties: true
            error:
              type: string
              description: Error message if execution failed
              example: Invalid credentials
            successful:
              type: boolean
              description: Whether the execution was successful
              example: true
            sessionInfo:
              type: object
              description: Session information for debugging
              additionalProperties: true
            logId:
              type: string
              description: >-
                Primary key (UUID) of the row in tool_execution_logs after the
                execution is recorded
              example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          required:
            - data
            - error
            - successful
          example:
            data: {}
            error: Invalid credentials
            successful: true
            sessionInfo: {}
            logId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      required:
        - success
        - message
        - data
    ExecuteToolResponseDto:
      type: object
      properties:
        data:
          type: object
          description: Tool execution result data
          additionalProperties: true
        error:
          type: string
          description: Error message if execution failed
          example: Invalid credentials
        successful:
          type: boolean
          description: Whether the execution was successful
          example: true
        sessionInfo:
          type: object
          description: Session information for debugging
          additionalProperties: true
        logId:
          type: string
          description: >-
            Primary key (UUID) of the row in tool_execution_logs after the
            execution is recorded
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      required:
        - data
        - error
        - successful
    CustomAuthParamsDto:
      type: object
      properties:
        baseUrl:
          type: string
          description: Base URL for custom authentication
          example: https://api.example.com
        parameters:
          description: Custom authentication parameters
          type: array
          items:
            $ref: '#/components/schemas/CustomAuthParamsParameterDto'
        body:
          type: object
          description: Custom authentication body
          additionalProperties: true
    CustomConnectionDataDto:
      type: object
      properties:
        authScheme:
          enum:
            - OAUTH1
            - OAUTH2
            - S2S_OAUTH2
            - API_KEY
            - BASIC
            - BEARER_TOKEN
            - BILLCOM_AUTH
            - GOOGLE_SERVICE_ACCOUNT
            - NO_AUTH
            - BASIC_WITH_JWT
            - CALCOM_AUTH
            - SERVICE_ACCOUNT
            - SAML
            - DCR_OAUTH
            - COOKIE
            - WHATSAPP_QR
          type: string
          description: Authentication scheme
          example: OAUTH2
        toolkitSlug:
          type: string
          description: Toolkit slug
          example: slack
        val:
          $ref: '#/components/schemas/ConnectedAccountConnectionValDto'
      required:
        - authScheme
        - toolkitSlug
        - val
    CustomAuthParamsParameterDto:
      type: object
      properties:
        name:
          type: string
          description: Parameter name
          example: Authorization
        in:
          enum:
            - query
            - header
          type: string
          description: Parameter location
          example: header
        value:
          type: object
          description: Parameter value
          example: Bearer token123
      required:
        - name
        - in
        - value
    ConnectedAccountConnectionValDto:
      type: object
      properties:
        cookies:
          type: string
          description: Full Cookie header for authenticated requests
        localStorage:
          type: object
          description: Subset of localStorage used for captured session
          additionalProperties:
            type: string
        localStorageHeaderBindings:
          type: array
          items:
            $ref: '#/components/schemas/LocalStorageHeaderBindingDto'
        access_token:
          type: string
          example: ya29.a0AfH6SMC...
        account_id:
          type: string
        accountId:
          type: string
          description: Zernio / partner social account id (camelCase)
        profileId:
          type: string
          description: Zernio multi-tenant profile id
        platform:
          type: string
          description: Partner platform slug, e.g. instagram
        account_url:
          type: string
        api_key:
          type: string
        api_url:
          type: string
        application_id:
          type: string
        authed_user:
          $ref: '#/components/schemas/ComposioCustomConnectionAuthedUserDto'
        authUri:
          type: string
          description: Authorization / OAuth URI
        base_url:
          type: string
        basic_encoded:
          type: string
        bearer_token:
          type: string
        borneo_dashboard_url:
          type: string
        callbackUrl:
          type: string
          description: Callback URL (camelCase variant)
        callback_url:
          type: string
        client_id:
          type: string
        COMPANYDOMAIN:
          type: string
          description: Composio COMPANYDOMAIN
        composio_link_redirect_url:
          type: string
        consumer_key:
          type: string
        code_verifier:
          type: string
          description: PKCE / OAuth code verifier
        credentials_json:
          type: string
          description: Opaque credentials JSON string
        dc:
          type: string
        dev_key:
          type: string
          description: Flowra / toolkit dev key
        domain:
          type: string
        error:
          type: string
        error_description:
          type: string
        expired_at:
          type: string
        expires_in:
          type: object
          example: 3600
        extension:
          type: string
        final_redirect_uri:
          type: string
          description: Final redirect after OAuth
        form_api_base_url:
          type: string
        generic_api_key:
          type: string
        id_token:
          type: string
        instanceEndpoint:
          type: string
        instanceName:
          type: string
        installation_id:
          type: string
        long_redirect_url:
          type: boolean
        oauth_token:
          type: string
        oauth_token_secret:
          type: string
        oauth_verifier:
          type: string
        password:
          type: string
        private_key:
          type: string
        proxy_password:
          type: string
        proxy_username:
          type: string
        redirectUrl:
          type: string
        refresh_token:
          type: string
        registration_access_token:
          type: string
        registration_client_uri:
          type: string
        region:
          type: string
        scope:
          type: object
          example:
            - read
            - write
        server_location:
          type: string
        shop:
          type: string
        site_name:
          type: string
        status:
          enum:
            - INITIALIZING
            - INITIATED
            - ACTIVE
            - FAILED
            - EXPIRED
            - INACTIVE
          type: string
          example: INITIATED
        state_prefix:
          type: string
        subdomain:
          type: string
        token:
          type: string
        token_type:
          type: string
        username:
          type: string
        version:
          type: string
        webhook_signature:
          type: string
        your-domain:
          type: string
        your_server:
          type: string
    LocalStorageHeaderBindingDto:
      type: object
      properties:
        headerName:
          type: string
          example: Authorization
        localStorageKey:
          type: string
          example: token
        headerValue:
          type: string
          example: Bearer …
      required:
        - headerName
        - localStorageKey
        - headerValue
    ComposioCustomConnectionAuthedUserDto:
      type: object
      properties:
        access_token:
          type: string
          example: ya29.a0AfH6SMC...
        scope:
          type: string
          example: read,write
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Project API key. Create and manage keys in the dashboard under Project →
        API Keys. Send as header: x-api-key: <your-key>
    x-username:
      type: apiKey
      in: header
      name: x-username
      description: >-
        Optional. External user username. If omitted, Flowra uses the project’s
        default external user. Send as header: x-username: <username>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.