> ## 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.

# Create a new tool

> Create a custom tool (e.g. API call, script, or custom logic) that your workflows and agents can call. Define name, description, and input schema.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/tools
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:
    post:
      tags:
        - Tools
      summary: Create a new tool
      description: >-
        Create a custom tool (e.g. API call, script, or custom logic) that your
        workflows and agents can call. Define name, description, and input
        schema.
      operationId: ToolsController_createTool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateToolDtoDef'
      responses:
        '200':
          description: Tool created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  slug: gmail_send_email
                  name: Send Email
                  description: Sends an email via Gmail
                  instructions: Use when the user asks to send an email.
                  toolkitSlug: gmail
                  inputParameters:
                    type: object
                    properties:
                      to:
                        type: string
                  outputParameters:
                    type: object
                    properties:
                      messageId:
                        type: string
                  noAuth: false
                  availableVersions:
                    - 1.0.0
                  version: 1.0.0
                  scopes:
                    - gmail.send
                  tags:
                    - email
                  isImportant: false
                  isDeprecated: false
                  isDisabled: false
                  popularityScore: 12
                  provider: COMPOSIO
                  type: action
                  ragContentHash: ''
                  ragSyncedAt: '2024-01-01T00:00:00.000Z'
                  createdAt: '2024-01-01T00:00:00.000Z'
                  updatedAt: '2024-01-01T00:00:00.000Z'
                  fieldModifiers: {}
                  script: javascript
                  executionCreditCost: 0
      security:
        - x-api-key: []
components:
  schemas:
    CreateToolDtoDef:
      type: object
      properties:
        slug:
          type: string
          maxLength: 100
          description: Tool slug
          example: send_slack_digest
        name:
          type: string
          maxLength: 200
          description: Tool name
          example: Send Slack digest
        description:
          type: string
          description: Tool description
          example: Posts a daily summary to a Slack channel
        instructions:
          type: string
          description: Tool instructions
          example: Call when the user asks to share a digest in Slack.
        toolkitSlug:
          type: string
          maxLength: 100
          description: Toolkit slug
          example: my-custom-toolkit
        inputParameters:
          type: object
          description: JSON Schema for tool arguments
          example:
            type: object
            properties:
              channel:
                type: string
            required:
              - channel
        outputParameters:
          type: object
          description: JSON Schema for the tool result
          example:
            type: object
            properties:
              ok:
                type: boolean
        noAuth:
          type: boolean
          description: Whether the tool requires no authentication
          default: false
        scopes:
          description: Required OAuth/API scopes
          example:
            - chat:write
          type: array
          items:
            type: string
        tags:
          description: Tool tags
          example:
            - slack
            - digest
          type: array
          items:
            type: string
        isImportant:
          type: boolean
          description: Whether the tool is important
          default: false
        popularityScore:
          type: number
          minimum: 0
          description: Popularity score
          default: 0
        type:
          enum:
            - action
            - poll
            - webhook
          type: string
          description: Tool type
          default: action
        availableVersions:
          description: Available versions
          example:
            - 1.0.0
            - 1.1.0
          type: array
          items:
            type: string
        version:
          type: string
          maxLength: 50
          description: Tool version
          default: 1.0.0
        isDeprecated:
          type: boolean
          description: Whether the tool is deprecated
          default: false
        isDisabled:
          type: boolean
          description: Whether the tool is disabled
          default: false
        triggerThreadKey:
          type: string
          description: Trigger thread key (for webhook type)
          example: invoice.paid
        deprecatedInfo:
          type: object
          properties:
            displayName:
              type: string
            version:
              type: string
            availableVersions:
              type: array
              items:
                type: string
            isDeprecated:
              type: boolean
            toolkit:
              type: object
              properties:
                logo:
                  type: string
        script:
          $ref: '#/components/schemas/CreateToolScriptDto'
        executionCreditCost:
          type: number
          nullable: true
          minimum: 0
          description: >-
            Credits charged per successful execution. Omit or null for platform
            default (2). Admin only.
          example: 2
      required:
        - slug
        - name
        - description
        - toolkitSlug
        - inputParameters
        - outputParameters
        - deprecatedInfo
    ToolResponseDtoSuccessResponse:
      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:
            id:
              type: string
              description: Tool UUID
              example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            slug:
              type: string
              description: Stable tool slug used in execute and agent tool lists
              example: gmail_send_email
            name:
              type: string
              description: Display name
              example: Send Email
            description:
              type: string
              description: What the tool does
              example: Sends an email via Gmail
            instructions:
              type: string
              description: Instructions for when an agent should call this tool
              example: Use when the user asks to send an email.
            toolkitSlug:
              type: string
              description: Parent toolkit slug
              example: gmail
            inputParameters:
              type: object
              description: JSON Schema for arguments
              example:
                type: object
                properties:
                  to:
                    type: string
            outputParameters:
              type: object
              description: JSON Schema for the result
              example:
                type: object
                properties:
                  messageId:
                    type: string
            noAuth:
              type: boolean
              description: True when the tool can run without a connected account
              example: false
            availableVersions:
              description: Published versions
              example:
                - 1.0.0
              type: array
              items:
                type: string
            version:
              type: string
              description: Current version
              example: 1.0.0
            scopes:
              description: Required scopes
              example:
                - gmail.send
              type: array
              items:
                type: string
            tags:
              description: Tags
              example:
                - email
              type: array
              items:
                type: string
            isImportant:
              type: boolean
              description: Highlighted in pickers
              example: false
            isDeprecated:
              type: boolean
              description: Marked deprecated in the catalog
              example: false
            isDisabled:
              type: boolean
              description: Disabled tools cannot be executed
              example: false
            popularityScore:
              type: number
              description: Relative popularity score
              example: 12
            provider:
              type: string
              enum:
                - COMPOSIO
                - LOCAL
            type:
              enum:
                - action
                - poll
                - webhook
              type: string
            ragContentHash:
              type: string
            ragSyncedAt:
              format: date-time
              type: string
            createdAt:
              format: date-time
              type: string
            updatedAt:
              format: date-time
              type: string
            fieldModifiers:
              type: object
            script:
              type: string
              nullable: true
              description: Custom script for this tool when set (language and source code).
              enum:
                - javascript
                - python
            executionCreditCost:
              type: number
              nullable: true
              description: >-
                Credits charged per successful execution. Null = platform
                default. Visible to admins only.
          required:
            - id
            - slug
            - name
            - description
            - instructions
            - toolkitSlug
            - inputParameters
            - outputParameters
            - noAuth
            - availableVersions
            - version
            - scopes
            - tags
            - isImportant
            - isDeprecated
            - isDisabled
            - popularityScore
            - provider
            - type
            - ragContentHash
            - ragSyncedAt
            - createdAt
            - updatedAt
            - fieldModifiers
          example:
            id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            slug: gmail_send_email
            name: Send Email
            description: Sends an email via Gmail
            instructions: Use when the user asks to send an email.
            toolkitSlug: gmail
            inputParameters:
              type: object
              properties:
                to:
                  type: string
            outputParameters:
              type: object
              properties:
                messageId:
                  type: string
            noAuth: false
            availableVersions:
              - 1.0.0
            version: 1.0.0
            scopes:
              - gmail.send
            tags:
              - email
            isImportant: false
            isDeprecated: false
            isDisabled: false
            popularityScore: 12
            provider: COMPOSIO
            type: action
            ragContentHash: ''
            ragSyncedAt: '2024-01-01T00:00:00.000Z'
            createdAt: '2024-01-01T00:00:00.000Z'
            updatedAt: '2024-01-01T00:00:00.000Z'
            fieldModifiers: {}
            script: javascript
            executionCreditCost: 0
      required:
        - success
        - message
        - data
    CreateToolScriptDto:
      type: object
      properties:
        language:
          enum:
            - javascript
            - python
          type: string
          description: Script language
          example: javascript
        source:
          type: string
          description: Source code executed when the tool runs
          example: >-
            export default async function ({ input }) { return { ok: true, input
            }; }
      required:
        - language
        - source
  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>

````

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