openapi: 3.0.3
info:
  title: Boltic Tables API
  description: >-
    The Boltic Tables API provides programmatic access to Boltic Tables, a
    no-code database for teams to organize, manage, and automate structured
    data workflows. The API supports full CRUD operations on tables and rows,
    SQL query execution via a built-in SQL editor with AI-powered query
    generation, and integration with workflows for automated data processing
    triggered by table changes.
  version: 1.0.0
  contact:
    name: Boltic
    url: https://www.boltic.io
  license:
    name: Proprietary
    url: https://www.boltic.io/terms
servers:
  - url: https://api.boltic.io/v1
    description: Boltic Tables API
security:
  - bearerAuth: []
tags:
  - name: Queries
    description: Execute SQL queries against tables
  - name: Rows
    description: Create, read, update, and delete table rows
  - name: Tables
    description: Manage tables and their schemas
paths:
  /tables:
    get:
      operationId: listTables
      summary: Boltic List all tables
      description: Retrieve a list of all tables in the workspace.
      tags:
        - Tables
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: A list of tables
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Table'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      operationId: createTable
      summary: Boltic Create a new table
      description: Create a new table with a defined schema of columns.
      tags:
        - Tables
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableInput'
      responses:
        '201':
          description: Table created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '400':
          $ref: '#/components/responses/BadRequest'
  /tables/{tableId}:
    get:
      operationId: getTable
      summary: Boltic Get a table by ID
      description: Retrieve table metadata and schema.
      tags:
        - Tables
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Table details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTable
      summary: Boltic Update a table
      description: Update table metadata or schema definition.
      tags:
        - Tables
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TableInput'
      responses:
        '200':
          description: Table updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
    delete:
      operationId: deleteTable
      summary: Boltic Delete a table
      tags:
        - Tables
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Table deleted
  /tables/{tableId}/rows:
    get:
      operationId: listRows
      summary: Boltic List rows in a table
      description: Retrieve rows from a table with optional filtering and sorting.
      tags:
        - Rows
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: filter
          in: query
          description: JSON-encoded filter expression
          schema:
            type: string
        - name: sort
          in: query
          description: Column name to sort by
          schema:
            type: string
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: asc
      responses:
        '200':
          description: A list of rows
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Row'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      operationId: createRow
      summary: Boltic Add a new row
      description: Insert a new row into the table.
      tags:
        - Rows
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RowInput'
      responses:
        '201':
          description: Row created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Row'
  /tables/{tableId}/rows/{rowId}:
    get:
      operationId: getRow
      summary: Boltic Get a row by ID
      tags:
        - Rows
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
        - name: rowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Row details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Row'
    put:
      operationId: updateRow
      summary: Boltic Update a row
      description: Modify an existing row in the table.
      tags:
        - Rows
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
        - name: rowId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RowInput'
      responses:
        '200':
          description: Row updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Row'
    delete:
      operationId: deleteRow
      summary: Boltic Delete a row
      tags:
        - Rows
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
        - name: rowId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Row deleted
  /tables/{tableId}/query:
    post:
      operationId: queryTable
      summary: Boltic Execute a SQL query
      description: >-
        Run a DML query against the table using the built-in SQL editor.
        Supports AI-powered natural language to SQL generation.
      tags:
        - Queries
      parameters:
        - name: tableId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: SQL query to execute
                naturalLanguage:
                  type: string
                  description: >-
                    Optional natural language prompt for AI-powered SQL
                    generation
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                type: object
                properties:
                  columns:
                    type: array
                    items:
                      type: string
                  rows:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  rowCount:
                    type: integer
                  generatedQuery:
                    type: string
                    description: >-
                      The SQL query generated from natural language, if
                      applicable
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Table:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        columns:
          type: array
          items:
            $ref: '#/components/schemas/Column'
        rowCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    TableInput:
      type: object
      required:
        - name
        - columns
      properties:
        name:
          type: string
        description:
          type: string
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ColumnInput'
    Column:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - text
            - number
            - boolean
            - date
            - datetime
            - email
            - url
            - select
            - multi-select
            - attachment
            - relation
        required:
          type: boolean
        defaultValue:
          type: string
        options:
          type: array
          items:
            type: string
          description: Options for select and multi-select columns
    ColumnInput:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          type: string
        required:
          type: boolean
          default: false
        defaultValue:
          type: string
        options:
          type: array
          items:
            type: string
    Row:
      type: object
      properties:
        id:
          type: string
        fields:
          type: object
          additionalProperties: true
          description: Key-value pairs of column names to values
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    RowInput:
      type: object
      properties:
        fields:
          type: object
          additionalProperties: true
          description: Key-value pairs of column names to values
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'