Flowra Table API

openapi: 3.2.0
info:
  title: Flowra API (API Key Endpoints) Table 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: Table
  description: Collections and documents
paths:
  /api/v1/table/collections:
    get:
      operationId: TableController_getCollections
      x-apiKeyEnabled: true
      summary: List collections
      description: List your data collections (tables). Use to choose a collection for reading or writing documents via the documents endpoints.
      parameters:
      - 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
      responses:
        '200':
          description: Collections retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionInfoDtoArraySuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                - id: 507f1f77bcf86cd799439011
                  name: products
                  description: Products collection
                  schema:
                    name: string
                    price: number
                  documentCount: 100
                  exposeViaMcp: true
                  ownerEUID: usr_ext_abc123
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/table/collections/{collectionId}/documents:
    post:
      operationId: TableController_createDocument
      x-apiKeyEnabled: true
      summary: Create document
      description: Create a new document in a collection. Send the document fields as JSON; the response includes the new document ID.
      parameters:
      - name: collectionId
        required: true
        in: path
        description: Collection ID
        schema:
          example: 507f1f77bcf86cd799439011
          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
      responses:
        '200':
          description: Document created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data: {}
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/table/collections/{collectionId}/documents/{documentId}:
    delete:
      operationId: TableController_deleteDocument
      x-apiKeyEnabled: true
      summary: Delete document
      description: Permanently remove a document from a collection. It cannot be recovered.
      parameters:
      - name: collectionId
        required: true
        in: path
        description: Collection ID
        schema:
          example: 507f1f77bcf86cd799439011
          type: string
      - name: documentId
        required: true
        in: path
        description: Document ID
        schema:
          example: 507f1f77bcf86cd799439012
          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
      responses:
        '200':
          description: Document deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedBooleanDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  deleted: true
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
    patch:
      operationId: TableController_updateDocument
      x-apiKeyEnabled: true
      summary: Update document
      description: Update one or more fields of a document by collection and document ID. Send only the fields you want to change.
      parameters:
      - name: collectionId
        required: true
        in: path
        description: Collection ID
        schema:
          example: 507f1f77bcf86cd799439011
          type: string
      - name: documentId
        required: true
        in: path
        description: Document ID
        schema:
          example: 507f1f77bcf86cd799439012
          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
      responses:
        '200':
          description: Document updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data: {}
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/table/collections/{id}:
    get:
      operationId: TableController_getCollectionMetadata
      x-apiKeyEnabled: true
      summary: Get collection metadata
      description: 'Get metadata for one collection: name, schema, and document count. Use before querying documents to understand the structure.'
      parameters:
      - name: id
        required: true
        in: path
        description: Collection ID
        schema:
          example: 507f1f77bcf86cd799439011
          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
      responses:
        '200':
          description: Collection metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionInfoDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  id: 507f1f77bcf86cd799439011
                  name: products
                  description: Products collection
                  schema:
                    name: string
                    price: number
                  documentCount: 100
                  exposeViaMcp: true
                  ownerEUID: usr_ext_abc123
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
    delete:
      operationId: TableController_deleteCollection
      x-apiKeyEnabled: true
      summary: Delete collection
      description: Permanently delete a collection and all documents in it. Use with care; this cannot be undone.
      parameters:
      - name: id
        required: true
        in: path
        description: Collection ID
        schema:
          example: 507f1f77bcf86cd799439011
          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
      responses:
        '200':
          description: Collection deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedBooleanDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  deleted: true
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/table/collections/{id}/documents:
    get:
      operationId: TableController_getCollectionDocuments
      x-apiKeyEnabled: true
      summary: List collection documents
      description: List documents in a collection with pagination, sorting, and optional search. Use to display records or feed data into workflows.
      parameters:
      - name: id
        required: true
        in: path
        description: Collection ID
        schema:
          example: 507f1f77bcf86cd799439011
          type: string
      - 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: sort
        required: false
        in: query
        description: 'Sort configuration in format: field:asc or field:desc or field1:asc,field2:desc. Overrides sortBy and sortOrder.'
        schema:
          example: createdAt:desc
          type: string
      - name: search
        required: false
        in: query
        description: Search query to filter documents. Overrides q parameter.
        schema:
          example: search term
          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
      responses:
        '200':
          description: Documents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDocumentsResponseDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  documents:
                  - {}
                  total: 100
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
  /api/v1/table/collections/{id}/expose-mcp:
    patch:
      operationId: TableController_setCollectionExposeViaMcp
      x-apiKeyEnabled: true
      summary: Toggle read-only share with project members via MCP
      description: When exposeViaMcp is true, other members of this project may list and read this Mongo-backed collection via MCP. Writes stay owner-only. The collection still only appears in the owner’s dashboard list.
      parameters:
      - name: id
        required: true
        in: path
        description: Collection ID
        schema:
          example: 507f1f77bcf86cd799439011
          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/TableCollectionExposeDto'
      responses:
        '200':
          description: Read-only project share flag updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExposeViaMcpDtoSuccessResponse'
              example:
                success: true
                message: Operation completed successfully
                data:
                  exposeViaMcp: true
      tags:
      - Table
      security:
      - x-api-key: []
      - x-api-key: []
        x-username: []
components:
  schemas:
    TableCollectionExposeDto:
      type: object
      properties:
        exposeViaMcp:
          type: boolean
          description: Read-only share with other members of this project via MCP. Writes and dashboard lists stay owner-only.
          example: true
      required:
      - exposeViaMcp
    CollectionInfoDtoArraySuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Success message
          example: Operation completed successfully
        data:
          description: Response data
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Collection ID (use in documents endpoints)
                example: 507f1f77bcf86cd799439011
              name:
                type: string
                description: Collection display name
                example: products
              description:
                type: string
                description: Collection description
                example: Products collection
              schema:
                type: object
                description: Collection schema
                example:
                  name: string
                  price: number
              documentCount:
                type: number
                description: Total number of documents in the collection
                example: 100
              exposeViaMcp:
                type: boolean
                description: When true, MCP tools may read this collection (list/find/count/aggregate only)
                default: false
              ownerEUID:
                type: string
                description: External user id of the collection owner (enforced for non-admin database tools)
                example: usr_ext_abc123
            required:
            - id
            - name
            - description
          example:
          - id: 507f1f77bcf86cd799439011
            name: products
            description: Products collection
            schema:
              name: string
              price: number
            documentCount: 100
            exposeViaMcp: true
            ownerEUID: usr_ext_abc123
      required:
      - success
      - message
      - data
    CollectionInfoDtoSuccessResponse:
      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: Collection ID (use in documents endpoints)
              example: 507f1f77bcf86cd799439011
            name:
              type: string
              description: Collection display name
              example: products
            description:
              type: string
              description: Collection description
              example: Products collection
            schema:
              type: object
              description: Collection schema
              example:
                name: string
                price: number
            documentCount:
              type: number
              description: Total number of documents in the collection
              example: 100
            exposeViaMcp:
              type: boolean
              description: When true, MCP tools may read this collection (list/find/count/aggregate only)
              default: false
            ownerEUID:
              type: string
              description: External user id of the collection owner (enforced for non-admin database tools)
              example: usr_ext_abc123
          required:
          - id
          - name
          - description
          example:
            id: 507f1f77bcf86cd799439011
            name: products
            description: Products collection
            schema:
              name: string
              price: number
            documentCount: 100
            exposeViaMcp: true
            ownerEUID: usr_ext_abc123
      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
    DeletedBooleanDtoSuccessResponse:
      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: boolean
              example: true
          required:
          - deleted
          example:
            deleted: true
      required:
      - success
      - message
      - data
    ExposeViaMcpDtoSuccessResponse:
      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:
            exposeViaMcp:
              type: boolean
              example: true
          required:
          - exposeViaMcp
          example:
            exposeViaMcp: true
      required:
      - success
      - message
      - data
    CollectionDocumentsResponseDtoSuccessResponse:
      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:
            documents:
              description: List of documents
              type: array
              items:
                type: object
            total:
              type: number
              description: Total number of documents
              example: 100
          required:
          - documents
          - total
          example:
            documents:
            - {}
            total: 100
      required:
      - success
      - message
      - data
  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>'