> ## 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. Only endpoints that support API Key authentication via the @ApiKeyEnabled() decorator. Send x-api-key (required). On multi-tenant endpoints, optionally send x-username (defaults to the project’s default 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 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 schema: 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/SuccessResponseDto' '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ExecuteToolResponseDto' security: - x-api-key: [] - x-api-key: [] x-username: [] components: schemas: ExecuteToolDto: $ref: '#/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) metaSessionId: type: string description: Ephemeral meta session id from DISCOVER_TOOLS version: type: string description: Tool version example: 2.0.0 customAuthParams: description: Custom authentication parameters allOf: - $ref: '#/components/schemas/CustomAuthParamsDto' customConnectionData: description: Custom connection data allOf: - $ref: '#/components/schemas/CustomConnectionDataDto' arguments: type: object description: Tool arguments additionalProperties: true 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. examples: http: value: http://127.0.0.1:7890 socks5: value: socks5://127.0.0.1:1080 invokeViaMcp: type: boolean description: 'Internal: MCP invocation flag' default: false SuccessResponseDto: $ref: '#/components/schemas/SuccessResponseDto' type: object properties: success: type: boolean description: Success status example: true message: type: string description: Success message example: Operation completed successfully data: type: object description: Response data required: - success - message - data ExecuteToolResponseDto: $ref: '#/components/schemas/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 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: 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: ````