From a227f47f151f87bcc86eaba144b636fea9191719 Mon Sep 17 00:00:00 2001
From: "n8n-assistant[bot]"
 <100856346+n8n-assistant[bot]@users.noreply.github.com>
Date: Mon, 26 Jan 2026 22:22:20 +0000
Subject: [PATCH] chore: Update Public API schema (#4147)

Co-authored-by: github-merge-queue[bot] <118344674+github-merge-queue[bot]@users.noreply.github.com>
Co-authored-by: Kartik Balasubramanian <22399046+HumanistSerif@users.noreply.github.com>
---
 docs/api/v1/openapi.yml | 679 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 679 insertions(+)

diff --git a/docs/api/v1/openapi.yml b/docs/api/v1/openapi.yml
index 836ea47f5..73de79238 100644
--- a/docs/api/v1/openapi.yml
+++ b/docs/api/v1/openapi.yml
@@ -30,6 +30,8 @@ tags:
     description: Operations about source control
   - name: Variables
     description: Operations about variables
+  - name: DataTable
+    description: Operations about data tables and their rows
   - name: Projects
     description: Operations about projects
 externalDocs:
@@ -1100,6 +1102,411 @@ paths:
           $ref: '#/components/responses/forbidden'
         '404':
           $ref: '#/components/responses/notFound'
+  /data-tables:
+    get:
+      x-eov-operation-id: listDataTables
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.handler
+      tags:
+        - DataTable
+      summary: List all data tables
+      description: Retrieve a list of all data tables with optional filtering, sorting, and pagination.
+      operationId: list-data-tables
+      parameters:
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/cursor'
+        - name: filter
+          in: query
+          description: JSON string of filter conditions
+          schema:
+            type: string
+            format: jsonString
+          example: '{"name":"my-table"}'
+        - name: sortBy
+          in: query
+          description: 'Sort format: field:asc or field:desc'
+          schema:
+            type: string
+          example: name:asc
+      responses:
+        '200':
+          description: Successfully retrieved data tables
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/dataTableList'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+      security:
+        - ApiKeyAuth: []
+    post:
+      x-eov-operation-id: createDataTable
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.handler
+      tags:
+        - DataTable
+      summary: Create a new data table
+      description: Create a new data table in your workspace.
+      operationId: create-data-table
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/createDataTableRequest'
+            example:
+              name: customers
+              columns:
+                - name: email
+                  type: string
+                - name: status
+                  type: string
+                - name: age
+                  type: number
+      responses:
+        '201':
+          description: Data table created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/dataTable'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '409':
+          $ref: '#/components/responses/conflict'
+      security:
+        - ApiKeyAuth: []
+  /data-tables/{dataTableId}:
+    get:
+      x-eov-operation-id: getDataTable
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.handler
+      tags:
+        - DataTable
+      summary: Get a data table
+      description: Retrieve a specific data table by ID.
+      operationId: get-data-table
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+      responses:
+        '200':
+          description: Successfully retrieved data table
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/dataTable'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+      security:
+        - ApiKeyAuth: []
+    patch:
+      x-eov-operation-id: updateDataTable
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.handler
+      tags:
+        - DataTable
+      summary: Update a data table
+      description: Update a data table's name.
+      operationId: update-data-table
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/updateDataTableRequest'
+            example:
+              name: updated-customers
+      responses:
+        '200':
+          description: Data table updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/dataTable'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+        '409':
+          $ref: '#/components/responses/conflict'
+      security:
+        - ApiKeyAuth: []
+    delete:
+      x-eov-operation-id: deleteDataTable
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.handler
+      tags:
+        - DataTable
+      summary: Delete a data table
+      description: Delete a data table. This will also delete all rows in the table.
+      operationId: delete-data-table
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+      responses:
+        '204':
+          description: Data table deleted successfully
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+      security:
+        - ApiKeyAuth: []
+  /data-tables/{dataTableId}/rows:
+    get:
+      x-eov-operation-id: getDataTableRows
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.rows.handler
+      tags:
+        - DataTable
+      summary: Retrieve rows from a data table
+      description: Query and retrieve rows from a data table with optional filtering, sorting, and pagination.
+      operationId: get-data-table-rows
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/cursor'
+        - name: filter
+          in: query
+          description: JSON string of filter conditions
+          schema:
+            type: string
+            format: jsonString
+          example: '{"type":"and","filters":[{"columnName":"status","condition":"eq","value":"active"}]}'
+        - name: sortBy
+          in: query
+          description: 'Sort format: columnName:asc or columnName:desc'
+          schema:
+            type: string
+          example: createdAt:desc
+        - name: search
+          in: query
+          description: Search text across all string columns
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successfully retrieved rows
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/dataTableRowList'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+      security:
+        - ApiKeyAuth: []
+    post:
+      x-eov-operation-id: insertDataTableRows
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.rows.handler
+      tags:
+        - DataTable
+      summary: Insert rows into a data table
+      description: Insert one or more rows into a data table.
+      operationId: insert-data-table-rows
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/insertRowsRequest'
+            example:
+              data:
+                - name: John Doe
+                  email: john@example.com
+                  age: 30
+                - name: Jane Smith
+                  email: jane@example.com
+                  age: 25
+              returnType: all
+      responses:
+        '200':
+          description: Rows inserted successfully
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                    properties:
+                      count:
+                        type: integer
+                    description: Number of rows inserted (when returnType is 'count')
+                  - type: array
+                    items:
+                      type: integer
+                    description: Array of inserted row IDs (when returnType is 'id')
+                  - type: array
+                    items:
+                      $ref: '#/components/schemas/dataTableRow'
+                    description: Array of inserted rows (when returnType is 'all')
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+      security:
+        - ApiKeyAuth: []
+  /data-tables/{dataTableId}/rows/update:
+    patch:
+      x-eov-operation-id: updateDataTableRows
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.rows.handler
+      tags:
+        - DataTable
+      summary: Update rows in a data table
+      description: Update rows matching filter conditions in a data table.
+      operationId: update-data-table-rows
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/updateRowsRequest'
+            example:
+              filter:
+                type: and
+                filters:
+                  - columnName: status
+                    condition: eq
+                    value: pending
+              data:
+                status: completed
+                updatedBy: admin
+              returnData: false
+              dryRun: false
+      responses:
+        '200':
+          description: Rows updated successfully
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: boolean
+                    description: True when returnData is false
+                  - type: array
+                    items:
+                      $ref: '#/components/schemas/dataTableRow'
+                    description: Updated rows when returnData is true
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+      security:
+        - ApiKeyAuth: []
+  /data-tables/{dataTableId}/rows/upsert:
+    post:
+      x-eov-operation-id: upsertDataTableRow
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.rows.handler
+      tags:
+        - DataTable
+      summary: Upsert a row in a data table
+      description: Update an existing row or insert a new one if no row matches the filter conditions.
+      operationId: upsert-data-table-row
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/upsertRowRequest'
+            example:
+              filter:
+                type: and
+                filters:
+                  - columnName: email
+                    condition: eq
+                    value: user@example.com
+              data:
+                email: user@example.com
+                name: Updated Name
+                status: active
+              returnData: true
+              dryRun: false
+      responses:
+        '200':
+          description: Row upserted successfully
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: boolean
+                    description: True when returnData is false
+                  - allOf:
+                      - $ref: '#/components/schemas/dataTableRow'
+                    description: Upserted row when returnData is true
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+      security:
+        - ApiKeyAuth: []
+  /data-tables/{dataTableId}/rows/delete:
+    delete:
+      x-eov-operation-id: deleteDataTableRows
+      x-eov-operation-handler: v1/handlers/data-tables/data-tables.rows.handler
+      tags:
+        - DataTable
+      summary: Delete rows from a data table
+      description: Delete rows matching filter conditions from a data table. Filter is required to prevent accidental deletion of all data.
+      operationId: delete-data-table-rows
+      parameters:
+        - $ref: '#/components/parameters/dataTableId'
+        - name: filter
+          in: query
+          required: true
+          description: JSON string of filter conditions. Required to prevent accidental deletion of all data.
+          schema:
+            type: string
+            format: jsonString
+          example: '{"type":"and","filters":[{"columnName":"status","condition":"eq","value":"archived"}]}'
+        - name: returnData
+          in: query
+          description: If true, return the deleted rows; if false, return true on success
+          schema:
+            type: boolean
+            default: false
+        - name: dryRun
+          in: query
+          description: If true, preview which rows would be deleted without actually deleting them
+          schema:
+            type: boolean
+            default: false
+      responses:
+        '200':
+          description: Rows deleted successfully
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: boolean
+                    description: True when returnData is false
+                  - type: array
+                    items:
+                      $ref: '#/components/schemas/dataTableRow'
+                    description: Deleted rows when returnData is true
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+      security:
+        - ApiKeyAuth: []
   /projects:
     post:
       x-eov-operation-id: createProject
@@ -2154,6 +2561,270 @@ components:
           type: string
           example: VmwOO9HeTEj20kxM
           nullable: true
+    dataTable:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Unique identifier for the data table
+        name:
+          type: string
+          description: Name of the data table
+        columns:
+          type: array
+          description: Column definitions
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                description: Column ID
+              name:
+                type: string
+                description: Column name
+              type:
+                type: string
+                enum:
+                  - string
+                  - number
+                  - boolean
+                  - date
+                description: Column data type
+              index:
+                type: integer
+                description: Column position
+        projectId:
+          type: string
+          description: ID of the project this table belongs to
+        createdAt:
+          type: string
+          format: date-time
+          description: Timestamp when the table was created
+        updatedAt:
+          type: string
+          format: date-time
+          description: Timestamp when the table was last updated
+      required:
+        - id
+        - name
+        - columns
+        - projectId
+        - createdAt
+        - updatedAt
+    dataTableList:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/dataTable'
+        nextCursor:
+          type: string
+          description: Paginate through data tables by setting the cursor parameter to a nextCursor attribute returned by a previous request. Default value fetches the first "page" of the collection.
+          nullable: true
+          example: MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
+    createDataTableRequest:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Name of the data table
+          minLength: 1
+          maxLength: 128
+        columns:
+          type: array
+          description: Column definitions for the table
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: Column name
+                minLength: 1
+              type:
+                type: string
+                enum:
+                  - string
+                  - number
+                  - boolean
+                  - date
+                  - json
+                description: Column data type
+            required:
+              - name
+              - type
+      required:
+        - name
+        - columns
+    updateDataTableRequest:
+      type: object
+      properties:
+        name:
+          type: string
+          description: New name for the data table
+          minLength: 1
+          maxLength: 128
+      required:
+        - name
+    dataTableRow:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: The row ID (auto-generated)
+        createdAt:
+          type: string
+          format: date-time
+          description: The date and time the row was created
+        updatedAt:
+          type: string
+          format: date-time
+          description: The date and time the row was last updated
+      additionalProperties: true
+      description: A data table row with system columns (id, createdAt, updatedAt) and user-defined columns
+    dataTableRowList:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/dataTableRow'
+        nextCursor:
+          type: string
+          description: Paginate through rows by setting the cursor parameter to a nextCursor attribute returned by a previous request. Default value fetches the first "page" of the collection.
+          nullable: true
+          example: MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
+    insertRowsRequest:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+          description: Array of rows to insert. Each row is an object with column names as keys.
+          minItems: 1
+        returnType:
+          type: string
+          enum:
+            - count
+            - id
+            - all
+          default: count
+          description: |
+            - count: Return only the number of rows inserted
+            - id: Return an array of inserted row IDs
+            - all: Return the full row data for all inserted rows
+      required:
+        - data
+    updateRowsRequest:
+      type: object
+      properties:
+        filter:
+          type: object
+          properties:
+            type:
+              type: string
+              enum:
+                - and
+                - or
+              default: and
+            filters:
+              type: array
+              minItems: 1
+              items:
+                type: object
+                properties:
+                  columnName:
+                    type: string
+                  condition:
+                    type: string
+                    enum:
+                      - eq
+                      - neq
+                      - like
+                      - ilike
+                      - gt
+                      - gte
+                      - lt
+                      - lte
+                  value: {}
+                required:
+                  - columnName
+                  - condition
+                  - value
+          required:
+            - filters
+          description: Filter conditions to match rows for update
+        data:
+          type: object
+          additionalProperties: true
+          description: Column values to update
+        returnData:
+          type: boolean
+          default: false
+          description: If true, return the updated rows; if false, return true on success
+        dryRun:
+          type: boolean
+          default: false
+          description: If true, preview changes without persisting them
+      required:
+        - filter
+        - data
+    upsertRowRequest:
+      type: object
+      properties:
+        filter:
+          type: object
+          properties:
+            type:
+              type: string
+              enum:
+                - and
+                - or
+              default: and
+            filters:
+              type: array
+              minItems: 1
+              items:
+                type: object
+                properties:
+                  columnName:
+                    type: string
+                  condition:
+                    type: string
+                    enum:
+                      - eq
+                      - neq
+                      - like
+                      - ilike
+                      - gt
+                      - gte
+                      - lt
+                      - lte
+                  value: {}
+                required:
+                  - columnName
+                  - condition
+                  - value
+          required:
+            - filters
+          description: Filter conditions to match existing row. If no row matches, a new row is inserted.
+        data:
+          type: object
+          additionalProperties: true
+          description: Column values for the row
+        returnData:
+          type: boolean
+          default: false
+          description: If true, return the upserted row; if false, return true on success
+        dryRun:
+          type: boolean
+          default: false
+          description: If true, preview changes without persisting them
+      required:
+        - filter
+        - data
     projectList:
       type: object
       properties:
@@ -2353,6 +3024,14 @@ components:
       required: true
       schema:
         type: string
+    dataTableId:
+      name: dataTableId
+      in: path
+      description: The ID of the data table
+      required: true
+      schema:
+        type: string
+        format: nanoid
     Cursor:
       $ref: '#/components/parameters/cursor'
     Limit: