Flowra File API

openapi: 3.2.0
info:
  title: Flowra API (API Key Endpoints) File API
  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
tags:
- name: File
  description: Upload, list, and download files
paths:
  /api/v1/file:
    get:
      operationId: FileController_getFiles
      x-apiKeyEnabled: true
      summary: List files
      description: List files uploaded to your project with pagination and filters. Use to show a file library or pick a file for use in workflows (e.g. knowledge, attachments).
      parameters:
      - name: q
        required: false
        in: query
        description: Search keyword for filtering results
        schema:
          example: john doe
          type: string
      - name: page
        required: false
        in: query
        description: Page number (1-based)
        schema:
          minimum: 1
          default: 1
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: Number of items per page
        schema:
          minimum: 1
          maximum: 100
          default: 20
          example: 20
          type: number
      - name: offset
        required: false
        in: query
        description: Number of items to skip (for offset-based pagination)
        schema:
          minimum: 0
          example: 0
          type: number
      - name: sortBy
        required: false
        in: query
        description: Field name to sort by
        schema:
          example: createdAt
          type: string
      - name: sortOrder
        required: false
        in: query
        description: Sort order
        schema:
          default: DESC
          example: DESC
          enum:
          - ASC
          - DESC
          type: string
      - name: fields
        required: false
        in: query
        description: Comma-separated list of fields to include in response
        schema:
          example: id,name,email
          type: string
      - name: format
        required: false
        in: query
        description: Filter files by format/extension
        schema:
          example: png
          type: string
      responses:
        '200':
          description: Files retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponseDtoPaginatedResponse'
              example:
                success: true
                message: Data retrieved successfully
                data:
                - id: ''
                  format: png
                  mimeType: image/png
                  size: 150
                  encoding: 7bit
                  alt: ''
                  originalName: ''
                  projectId: ''
                  ownerEUID: ''
                  fileTypeName: chat
                  fileTypeId: 0
                  createdAt: '2024-01-01T00:00:00.000Z'
                  updatedAt: '2024-01-01T00:00:00.000Z'
                total: 100
                totalTools: 5000
                page: 1
                limit: 20
                totalPages: 5
                hasNextPage: true
                hasPreviousPage: false
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/{filename}:
    get:
      operationId: FileController_serveFileByFilename
      x-apiKeyEnabled: true
      summary: Serve file by filename
      description: Serve a file by its stored filename (e.g. for public or signed URLs). Use when you have the filename from upload response.
      parameters:
      - name: filename
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: File content
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/{id}:
    delete:
      operationId: FileController_deleteFile
      x-apiKeyEnabled: true
      summary: Delete file
      description: Permanently remove a file. It will no longer be available for download or use in workflows.
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: File deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleSuccessResponseDto'
              example:
                success: true
                message: Operation completed successfully
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/delete-many:
    post:
      operationId: FileController_deleteManyFiles
      x-apiKeyEnabled: true
      summary: Delete multiple files
      description: Permanently remove one or more files you own in the current project scope. Use for bulk cleanup from the file library.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteFilesDto'
      responses:
        '200':
          description: Files deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFilesResponseDto'
              example:
                success: true
                deleted: 0
                message: ''
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFilesResponseDto'
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/download/{id}:
    get:
      operationId: FileController_downloadFile
      x-apiKeyEnabled: true
      summary: Download file
      description: Download a file by its ID. Possession of the id is enough (capability URL). Returns the file bytes with the stored content-type.
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: File content
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/fileType/{fileType}:
    get:
      operationId: FileController_fileType
      x-apiKeyEnabled: true
      summary: Get file type info
      description: Returns allowed file extensions and metadata for a given type (e.g. image, document). Use to validate uploads or show users which formats are accepted.
      parameters:
      - name: fileType
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data: {}
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/fileTypes:
    get:
      operationId: FileController_fileTypeList
      x-apiKeyEnabled: true
      summary: List supported file types
      description: List all supported file types and their allowed extensions. Use to build upload forms or validate file types before uploading.
      responses:
        '200':
          description: Operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data: {}
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/prune-oldest:
    post:
      operationId: FileController_pruneOldestFiles
      x-apiKeyEnabled: true
      summary: Delete oldest files to free storage
      description: Removes the oldest files for the current end user in the current project (not automatic). Use when storage quota is full.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PruneOldestFilesDto'
      responses:
        '200':
          description: Oldest files deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PruneOldestFilesResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  deleted: 0
                  freedKb: 0
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PruneOldestFilesResponseDto'
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/storage-breakdown:
    get:
      operationId: FileController_getStorageBreakdown
      x-apiKeyEnabled: true
      summary: File storage breakdown
      description: Returns used storage (KiB) for your whole account, the current project, and the current end user, plus the plan limit in GiB.
      responses:
        '200':
          description: Storage breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStorageBreakdownDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  accountUsedKb: 0
                  projectUsedKb: 0
                  endUserUsedKb: 0
                  limitGb: 0
      tags:
      - File
      security:
      - x-api-key: []
  /api/v1/file/upload/single/{fileType}:
    post:
      operationId: FileController_uploadSingleFile
      x-apiKeyEnabled: true
      summary: Upload a single file
      description: Upload a file (image or document) via multipart form. Pass the file type in the URL path. Returns the file ID to use in other APIs (e.g. knowledge, workflows).
      parameters:
      - name: fileType
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: File uploaded; returns file ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdDtoSuccessResponse'
      tags:
      - File
      security:
      - x-api-key: []
components:
  schemas:
    FileResponseDtoPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Response message
          example: Data retrieved successfully
        data:
          description: Array of items
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: File ID (UUID)
              format:
                type: string
                description: File format/extension
                example: png
              mimeType:
                type: string
                description: MIME type
                example: image/png
              size:
                type: number
                description: File size in KB
                example: 150
              encoding:
                type: string
                description: File encoding
                example: 7bit
              alt:
                type:
                - string
                - 'null'
                description: Alternative text/description
              originalName:
                type:
                - string
                - 'null'
                description: Original file name
              projectId:
                type:
                - string
                - 'null'
                description: Project ID
              ownerEUID:
                type:
                - string
                - 'null'
                description: Owner external user id (eUID)
              fileTypeName:
                type: string
                description: File type name
                example: chat
              fileTypeId:
                type: number
                description: File type ID
              createdAt:
                format: date-time
                type: string
                description: Created at timestamp
              updatedAt:
                format: date-time
                type: string
                description: Updated at timestamp
            required:
            - id
            - format
            - mimeType
            - size
            - encoding
            - alt
            - originalName
            - projectId
            - ownerEUID
            - fileTypeName
            - fileTypeId
            - createdAt
            - updatedAt
          example:
          - id: ''
            format: png
            mimeType: image/png
            size: 150
            encoding: 7bit
            alt: ''
            originalName: ''
            projectId: ''
            ownerEUID: ''
            fileTypeName: chat
            fileTypeId: 0
            createdAt: '2024-01-01T00:00:00.000Z'
            updatedAt: '2024-01-01T00:00:00.000Z'
        total:
          type: number
          description: Total number of items across all pages
          example: 100
        totalTools:
          type: number
          description: Optional secondary total (e.g. nested tools across all matching toolkits)
          example: 5000
        page:
          type: number
          description: Current page number (1-based)
          example: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
        totalPages:
          type: number
          description: Total number of pages
          example: 5
        hasNextPage:
          type: boolean
          description: Whether there is a next page
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there is a previous page
          example: false
      required:
      - success
      - message
      - data
      - total
    DeleteFilesDto:
      type: object
      properties:
        ids:
          description: File IDs to delete
          example:
          - 3e8a222c-be35-4bb7-a0a3-4013d086878e
          type: array
          items:
            type: string
      required:
      - ids
    PruneOldestFilesDto:
      type: object
      properties:
        count:
          type: number
          default: 10
          minimum: 1
          maximum: 100
          description: Number of oldest files to delete for the current end user in this project
          example: 10
      required:
      - count
    FileStorageBreakdownDtoSuccessResponse:
      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:
            accountUsedKb:
              type: number
              description: Total storage used across all projects owned by you (KiB)
            projectUsedKb:
              type: number
              description: Storage used in the current project (KiB)
            endUserUsedKb:
              type: number
              description: Storage used by the current end user in this project (KiB)
            limitGb:
              type:
              - number
              - 'null'
              description: Plan storage limit in GiB. null = unlimited; omitted/0 when no plan limit applies.
          required:
          - accountUsedKb
          - projectUsedKb
          - endUserUsedKb
          example:
            accountUsedKb: 0
            projectUsedKb: 0
            endUserUsedKb: 0
            limitGb: 0
      required:
      - success
      - message
      - data
    SimpleSuccessResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
      required:
      - success
      - message
    IdDtoSuccessResponse:
      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
              example: 3e8a222c-be35-4bb7-a0a3-4013d086878e
          required:
          - id
          example:
            id: 3e8a222c-be35-4bb7-a0a3-4013d086878e
      required:
      - success
      - message
      - data
    JsonSuccessResponse:
      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
          additionalProperties: true
          example: {}
      required:
      - success
      - message
      - data
    PruneOldestFilesResponseDto:
      type: object
      properties:
        deleted:
          type: number
        freedKb:
          type: number
          description: Approximate KiB freed
      required:
      - deleted
      - freedKb
    PruneOldestFilesResponseDtoSuccessResponse:
      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:
            deleted:
              type: number
            freedKb:
              type: number
              description: Approximate KiB freed
          required:
          - deleted
          - freedKb
          example:
            deleted: 0
            freedKb: 0
      required:
      - success
      - message
      - data
    DeleteFilesResponseDto:
      type: object
      properties:
        success:
          type: boolean
        deleted:
          type: number
        message:
          type: string
      required:
      - success
      - deleted
      - message
  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>'