openapi.yaml

openapi: 3.0.0
info:
  title: Softr Database API
  description: |
    Public API to communicate with Softr Databases. The API follows REST semantics and uses JSON to encode objects.
    
    **Rate Limiting:**
    All calls are subject to rate limiting. On exceeding the limit, you will receive a 429 HTTP Response Status Code.
    - **Paid plans:** 20 calls per second per single Public API Token or Workspace.
    - **Free plans:** 10 calls per second per single Public API Token or Workspace.
  version: "1.0.0"
servers:
  - url: https://tables-api.softr.io/api/v1
    description: Production Server

tags:
  - name: Databases
    description: Operations related to Softr databases.
  - name: Tables
    description: Operations related to tables within a database.
  - name: Table Fields
    description: Operations to manage fields within a table.
  - name: Records
    description: Operations to manage records (rows) within a table.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Softr-Api-Key
  
  schemas:
    # GENERAL
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message.

    # DATABASES
    Database:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        workspaceId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # TABLES
    TableField:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          description: "The type of the field."
          enum: [SINGLE_LINE_TEXT, CHECKBOX, CURRENCY, DATETIME, DURATION, EMAIL, SELECT, NUMBER, ATTACHMENT, RATING, LINKED_RECORD, LONG_TEXT, URL, PERCENT, BUTTON, PROGRESS, PHONE, DATE_RANGE, ADDRESS, TIME, LOOKUP, ROLLUP, FORMULA, COUNT, CREATED_AT, UPDATED_AT, CREATED_BY, UPDATED_BY, AUTONUMBER, RECORD_ID, USER]
        options:
          type: object
          description: "Configuration options for the field, specific to its type. See the official documentation for the structure of each type."
          additionalProperties: true
        allowMultipleEntries:
          type: boolean
        readonly:
          type: boolean
        required:
          type: boolean
        locked:
          type: boolean
        defaultValue:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    
    Table:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        primaryFieldId:
          type: string
        defaultViewId:
          type: string
        fields:
          type: array
          items:
            $ref: '#/components/schemas/TableField'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    TableView:
      type: object
      properties:
        id:
          type: string
        tableId:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          
    # RECORDS
    Record:
      type: object
      properties:
        id:
          type: string
        tableId:
          type: string
        fields:
          type: object
          description: "A map of Field IDs to their values for this record."
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          
    RecordListMetadata:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
          
    # FILTERING
    FilterCondition:
      type: object
      description: "A condition for filtering records. Text-related conditions are case-insensitive."
      properties:
        operator:
          type: string
          enum: [AND, OR, IS_EMPTY, IS_NOT_EMPTY, IS_BETWEEN, IS_NOT_BETWEEN, IS, IS_NOT, GREATER_THAN, GREATER_THAN_OR_EQUALS, LESS_THAN, LESS_THAN_OR_EQUALS, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, DOES_NOT_START_WITH, ENDS_WITH, DOES_NOT_END_WITH, IS_ONE_OF, IS_NOT_ONE_OF, HAS_ALL_OF, HAS_NONE_OF]
        leftSide:
          type: string
          description: "The Field ID to apply the operator on."
        rightSide:
          description: "The value to compare against. Can be a string, number, or an array for operators like IS_ONE_OF."
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
        lowerBound:
          type: string
          description: "Lower bound for IS_BETWEEN operator."
        upperBound:
          type: string
          description: "Upper bound for IS_BETWEEN operator."
        conditions:
          type: array
          description: "Used for AND/OR operators to nest conditions."
          items:
            $ref: '#/components/schemas/FilterCondition'

security:
  - ApiKeyAuth: []

paths:
  /databases:
    get:
      tags:
        - Databases
      summary: Get Databases
      description: Retrieve a list of all databases accessible to the authenticated user.
      operationId: getDatabases
      responses:
        '200':
          description: A list of databases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Database'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Databases
      summary: Create a Database
      description: Create a new database in the specified workspace.
      operationId: createDatabase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workspaceId
                - name
              properties:
                workspaceId:
                  type: string
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: The newly created database.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Database'
        '429':
          description: Rate limit exceeded.

  /databases/{databaseId}:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Databases
      summary: Get Single Database
      description: Retrieve details of a specific database by its ID.
      operationId: getDatabaseById
      responses:
        '200':
          description: Database details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Database'
        '429':
          description: Rate limit exceeded.
    put:
      tags:
        - Databases
      summary: Update Database
      description: Update the details of an existing database.
      operationId: updateDatabase
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: The updated database.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Database'
        '429':
          description: Rate limit exceeded.
    delete:
      tags:
        - Databases
      summary: Delete Database
      description: Delete a specific database by its ID. It can only be deleted if it is empty, unless the 'force' parameter is used.
      operationId: deleteDatabase
      parameters:
        - name: force
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: Database deleted successfully.
        '400':
          description: Bad Request - Database is not empty and force=true was not provided.
        '429':
          description: Rate limit exceeded.

  /databases/{databaseId}/tables:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Tables
      summary: Get Tables
      description: Retrieve a list of all tables in the specified database.
      operationId: getTables
      responses:
        '200':
          description: A list of tables.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Table'
        '429':
          description: Rate limit exceeded.
    post:
      tags:
        - Tables
      summary: Create Table
      description: Create a new table in the specified database.
      operationId: createTable
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                primaryFieldName:
                  type: string
                fields:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      type:
                        type: string
                      options:
                        type: object
                        additionalProperties: true
      responses:
        '200':
          description: The newly created table.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Table'
        '429':
          description: Rate limit exceeded.

  /databases/{databaseId}/tables/{tableId}:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tableId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Tables
      summary: Get Single Table
      description: Retrieve details of a specific table by its ID.
      operationId: getTableById
      responses:
        '200':
          description: Table details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Table'
        '429':
          description: Rate limit exceeded.
    put:
      tags:
        - Tables
      summary: Update Table
      description: Update a table's name and/or description. To modify fields, use the field-specific endpoints.
      operationId: updateTable
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: The updated table.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Table'
        '429':
          description: Rate limit exceeded.
    delete:
      tags:
        - Tables
      summary: Delete Table
      description: Delete a specific table by its ID. It can only be deleted if it is empty, unless the 'force' parameter is used.
      operationId: deleteTable
      parameters:
        - name: force
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: Table deleted successfully.
        '400':
          description: Bad Request - Table is not empty and force=true was not provided.
        '429':
          description: Rate limit exceeded.

  /databases/{databaseId}/tables/{tableId}/views:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tableId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Tables
      summary: Get Table Views
      description: Retrieve a list of views for a specific table.
      operationId: getTableViews
      responses:
        '200':
          description: A list of table views.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TableView'
        '429':
          description: Rate limit exceeded.

  /databases/{databaseId}/tables/{tableId}/fields:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tableId
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Table Fields
      summary: Add Table Field
      description: Add a new field to a table.
      operationId: addTableField
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - type
              properties:
                name:
                  type: string
                type:
                  type: string
                options:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The newly created field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TableField'
        '429':
          description: Rate limit exceeded.

  /databases/{databaseId}/tables/{tableId}/fields/{fieldId}:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tableId
        in: path
        required: true
        schema:
          type: string
      - name: fieldId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Table Fields
      summary: Get Table Field
      description: Retrieve details of a specific field.
      operationId: getTableField
      responses:
        '200':
          description: Field details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TableField'
        '429':
          description: Rate limit exceeded.
    put:
      tags:
        - Table Fields
      summary: Update Table Field
      description: Update the properties of a specific field.
      operationId: updateTableField
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                options:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The updated field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TableField'
        '429':
          description: Rate limit exceeded.
    delete:
      tags:
        - Table Fields
      summary: Delete Table Field
      description: Delete a specific field from a table.
      operationId: deleteTableField
      responses:
        '204':
          description: Field deleted successfully.
        '429':
          description: Rate limit exceeded.

  /databases/{databaseId}/tables/{tableId}/records:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tableId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Records
      summary: Get Records
      description: Retrieve a list of all records in the specified table.
      operationId: getRecords
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: A paginated list of records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Record'
                  metadata:
                    $ref: '#/components/schemas/RecordListMetadata'
        '429':
          description: Rate limit exceeded.
    post:
      tags:
        - Records
      summary: Create Record
      description: Create a new record in the specified table.
      operationId: createRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  description: "A map of Field IDs to their values."
                  additionalProperties: true
      responses:
        '200':
          description: The newly created record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Record'
        '429':
          description: Rate limit exceeded.
          
  /databases/{databaseId}/tables/{tableId}/records/search:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tableId
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Records
      summary: Search Records
      description: Search for records in the specified table based on filter, sort, and pagination criteria.
      operationId: searchRecords
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  $ref: '#/components/schemas/FilterCondition'
                sort:
                  type: object
                  description: "Sorting criteria (structure not fully specified in docs)."
                paging:
                  type: object
                  properties:
                    offset:
                      type: integer
                      default: 0
                    limit:
                      type: integer
                      default: 10
      responses:
        '200':
          description: A paginated list of matching records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Record'
                  metadata:
                    $ref: '#/components/schemas/RecordListMetadata'
        '429':
          description: Rate limit exceeded.
          
  /databases/{databaseId}/tables/{tableId}/records/{recordId}:
    parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tableId
        in: path
        required: true
        schema:
          type: string
      - name: recordId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Records
      summary: Get Single Record
      description: Retrieve details of a specific record by its ID.
      operationId: getRecordById
      responses:
        '200':
          description: Record details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Record'
        '429':
          description: Rate limit exceeded.
    patch:
      tags:
        - Records
      summary: Update Record
      description: Partially update a specific record by its ID. Only the fields provided in the request body will be changed.
      operationId: updateRecord
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  description: "A map of Field IDs to their new values."
                  additionalProperties: true
      responses:
        '200':
          description: The updated record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Record'
        '429':
          description: Rate limit exceeded.
    delete:
      tags:
        - Records
      summary: Delete Record
      description: Delete a specific record by its ID.
      operationId: deleteRecord
      responses:
        '204':
          description: Record deleted successfully.
        '429':
          description: Rate limit exceeded.