Simple AI Custom Data API

openapi: 3.2.0
info:
  title: Public API v1 Custom Data API
  description: 'Public API v1 requiring API keys.


    **Timestamps:** All datetime fields in API responses are returned in UTC using ISO 8601 format (e.g., `2024-01-15T14:30:00Z`). When filtering by date parameters, provide timestamps in ISO 8601 format.'
  version: 0.1.0
servers:
- url: https://api.usesimple.ai/api/v1
  description: Production API Server
tags:
- name: Custom Data
paths:
  /data/tables:
    get:
      tags:
      - Custom Data
      summary: List Custom Data Tables
      description: List the custom data tables for the authenticated organization, including each table's columns and record count.
      operationId: list_custom_data_tables_data_tables_get
      security:
      - APIKeyHeader: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomDataTable'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Custom Data
      summary: Create Custom Data Table
      description: Create a custom data table and its column schema for the authenticated organization.
      operationId: create_custom_data_table_data_tables_post
      security:
      - APIKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDataTableCreate'
      responses:
        '201':
          description: Custom Data Table Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataTable'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /data/tables/reference-tables:
    get:
      tags:
      - Custom Data
      summary: List Available Reference Tables
      description: List system and custom tables that can be used as targets for REFERENCE columns.
      operationId: list_custom_data_reference_tables_data_tables_reference_tables_get
      security:
      - APIKeyHeader: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailableReferenceTable'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /data/tables/{id}:
    patch:
      tags:
      - Custom Data
      summary: Update Custom Data Table
      description: Update a custom data table's label, search indexing setting, and column schema.
      operationId: update_custom_data_table_data_tables__id__patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: ID
        description: Custom data table ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDataTableUpdate'
      responses:
        '200':
          description: Custom Data Table Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataTable'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Custom Data
      summary: Delete Custom Data Table
      description: Delete an empty custom data table. Tables that still contain records or are referenced by another table cannot be deleted.
      operationId: delete_custom_data_table_data_tables__id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: ID
        description: Custom data table ID.
      responses:
        '200':
          description: Custom Data Table Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomDataTableResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /data/query:
    post:
      tags:
      - Custom Data
      summary: Query Custom Data
      description: Deterministic facet-filtered query against a single custom data table that has search indexing enabled. Provide exact-match `filters` and/or a free-text `text`; omit both to get the most recent records.
      operationId: query_custom_data_data_query_post
      security:
      - APIKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDataQueryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataQueryResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /data/facets/{table_name}:
    get:
      tags:
      - Custom Data
      summary: Get Custom Data Facets
      description: Return distinct values and counts for facetable columns in an indexed custom data table.
      operationId: get_custom_data_facets_data_facets__table_name__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9_]+$
          title: Table Name
        description: Custom data table name.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataFacetsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /data/{table_name}:
    get:
      tags:
      - Custom Data
      summary: List Custom Data Records
      description: List records in a custom data table. Query parameters matching declared table columns or managed columns are treated as exact-match filters.
      operationId: list_custom_data_records_data__table_name__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          title: Table Name
        description: Custom data table name.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
        description: Page number. Invalid or non-positive values default to 1.
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
          title: Per Page
        description: Number of records per page. Values above 200 are capped at 200.
      - name: order_by
        in: query
        required: false
        schema:
          type: string
          default: created_at
          title: Order By
        description: Column used for sorting. Use a declared table column or one of id, organization_id, created_at, updated_at.
      - name: order_direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
          - asc
          - desc
          default: DESC
          title: Order Direction
        description: Sort direction. Any value other than ASC defaults to DESC.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataRecordListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Custom Data
      summary: Create Custom Data Record
      description: Create a record in a custom data table.
      operationId: create_custom_data_record_data__table_name__put
      security:
      - APIKeyHeader: []
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          title: Table Name
        description: Custom data table name.
      - name: sourceUpdatedAtColumn
        in: query
        required: false
        schema:
          type: string
          pattern: ^[a-z][a-z0-9_]*$
          maxLength: 63
        description: Name of a TIMESTAMP column supplied with a non-null value. Atomically apply only if the stored timestamp is null or older. Equal/older values return 409. Ordered PUT also requires a configured business key and its value. Omit for normal write behavior.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDataRecordPayload'
      responses:
        '201':
          description: Custom Data Record Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataRecordResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: An equal or newer source timestamp already exists, or a unique value conflicts.
    delete:
      tags:
      - Custom Data
      summary: Delete All Custom Data Records
      description: Delete all records from a custom data table without deleting the table schema.
      operationId: delete_all_custom_data_records_data__table_name__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          title: Table Name
        description: Custom data table name.
      responses:
        '200':
          description: Custom Data Records Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAllCustomDataRecordsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /data/{table_name}/{id}:
    get:
      tags:
      - Custom Data
      summary: Get Custom Data Record
      description: Get a single record from a custom data table by record ID.
      operationId: get_custom_data_record_data__table_name___id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          title: Table Name
        description: Custom data table name.
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: ID
        description: Custom data record ID.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataRecordResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table or Record Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - Custom Data
      summary: Update Custom Data Record
      description: Update a record in a custom data table.
      operationId: update_custom_data_record_data__table_name___id__patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          title: Table Name
        description: Custom data table name.
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: ID
        description: Custom data record ID.
      - name: sourceUpdatedAtColumn
        in: query
        required: false
        schema:
          type: string
          pattern: ^[a-z][a-z0-9_]*$
          maxLength: 63
        description: Name of a TIMESTAMP column supplied with a non-null value. Atomically apply only if the stored timestamp is null or older. Equal/older values return 409. Ordered PUT also requires a configured business key and its value. Omit for normal write behavior.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDataRecordPayload'
      responses:
        '200':
          description: Custom Data Record Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDataRecordResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table or Record Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: An equal or newer source timestamp already exists, or a unique value conflicts.
    delete:
      tags:
      - Custom Data
      summary: Delete Custom Data Record
      description: Delete one record from a custom data table.
      operationId: delete_custom_data_record_data__table_name___id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          title: Table Name
        description: Custom data table name.
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: ID
        description: Custom data record ID.
      responses:
        '200':
          description: Custom Data Record Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomDataRecordResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Custom Data Table or Record Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CustomDataColumnType:
      type: string
      enum:
      - STRING
      - NUMERIC
      - BOOLEAN
      - JSONB
      - TIMESTAMP
      - REFERENCE
      - STRING_ARRAY
      - NUMERIC_ARRAY
      - BOOLEAN_ARRAY
      - TIMESTAMP_ARRAY
      - OBJECT
      title: Custom Data Column Type
    DeleteAllCustomDataRecordsResponse:
      type: object
      required:
      - success
      - message
      - deleted_count
      properties:
        success:
          type: boolean
          default: true
        message:
          type: string
          title: Message
        deleted_count:
          type: integer
          title: Deleted Count
      title: Delete All Custom Data Records Response
    CustomDataRecordResponse:
      type: object
      required:
      - record
      properties:
        record:
          $ref: '#/components/schemas/CustomDataRecord'
      title: Custom Data Record Response
    CustomDataFacetValue:
      type: object
      required:
      - value
      - count
      properties:
        value:
          anyOf:
          - type: string
          - type: number
          - type: boolean
          title: Value
        count:
          type: integer
          title: Count
      title: Custom Data Facet Value
    CustomDataTableCreate:
      type: object
      required:
      - name
      - label
      - columns
      properties:
        name:
          type: string
          pattern: ^[a-z]([a-z0-9]+(_[a-z0-9]+)*)?$
          title: Name
          description: Stable table identifier used in record endpoint paths.
        label:
          type: string
          title: Label
          description: Human-readable table name shown in Simple AI.
        searchIndexingEnabled:
          type: boolean
          title: Search Indexing Enabled
          description: Whether this table can be searched with the custom data search and facets endpoints.
          default: false
        columns:
          type: array
          items:
            $ref: '#/components/schemas/CustomDataColumnInput'
          minItems: 1
          title: Columns
      title: Custom Data Table Create
    CustomDataColumnFacet:
      type: object
      required:
      - columnName
      - columnDisplayName
      - columnType
      - values
      properties:
        columnName:
          type: string
          title: Column Name
        columnDisplayName:
          type: string
          title: Column Display Name
        columnType:
          $ref: '#/components/schemas/CustomDataColumnType'
        values:
          type: array
          items:
            $ref: '#/components/schemas/CustomDataFacetValue'
          title: Values
      title: Custom Data Column Facet
    CustomDataQueryResponse:
      type: object
      required:
      - records
      - total
      properties:
        records:
          type: array
          items:
            type: object
            additionalProperties: true
          title: Records
        total:
          type: integer
          title: Total
          description: Total number of records matching the query (may exceed the returned page).
      title: Custom Data Query Response
    CustomDataQueryRequest:
      type: object
      required:
      - tableName
      properties:
        tableName:
          type: string
          pattern: ^[a-z0-9_]+$
          title: Table Name
          description: The indexed custom data table to query.
        filters:
          type: array
          title: Filters
          description: Exact-match filters. Each filter matches a column against one or more values (any-of). An empty filter is ignored.
          items:
            type: object
            required:
            - column
            - values
            properties:
              column:
                type: string
                pattern: ^[a-z0-9_]+$
                title: Column
              values:
                type: array
                title: Values
                items:
                  anyOf:
                  - type: string
                  - type: number
                  - type: boolean
        text:
          type: string
          maxLength: 5000
          title: Text
          description: Optional free-text search across all columns.
        size:
          type: integer
          minimum: 0
          maximum: 50
          title: Size
          description: Max records to return (default 25, max 50).
        from:
          type: integer
          minimum: 0
          title: From
          description: Offset for pagination.
      title: Custom Data Query Request
    CustomDataColumn:
      type: object
      required:
      - id
      - name
      - type
      - displayName
      - referenceTable
      - jsonSchema
      - position
      properties:
        id:
          type: integer
          title: ID
        name:
          type: string
          title: Name
        type:
          $ref: '#/components/schemas/CustomDataColumnType'
        displayName:
          type: string
          title: Display Name
        referenceTable:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Table
        jsonSchema:
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          title: JSON Schema
        position:
          type: integer
          title: Position
      title: Custom Data Column
    CustomDataTableUpdate:
      type: object
      required:
      - label
      - columns
      properties:
        label:
          type: string
          title: Label
          description: Human-readable table name shown in Simple AI.
        searchIndexingEnabled:
          type: boolean
          title: Search Indexing Enabled
          description: Whether this table can be searched with the custom data search and facets endpoints.
        columns:
          type: array
          items:
            $ref: '#/components/schemas/CustomDataColumnInput'
          minItems: 1
          title: Columns
      title: Custom Data Table Update
    CustomDataRecordPayload:
      type: object
      additionalProperties: true
      minProperties: 1
      title: Custom Data Record Payload
      description: Object containing values for declared table columns. Managed columns and unknown columns are ignored.
    CustomDataColumnInput:
      type: object
      required:
      - name
      - type
      - displayName
      properties:
        name:
          type: string
          maxLength: 63
          pattern: ^[a-z]([a-z0-9]+(_[a-z0-9]+)*)?$
          title: Name
          description: Column identifier. Use lowercase letters, numbers, and underscores.
        type:
          $ref: '#/components/schemas/CustomDataColumnType'
        displayName:
          type: string
          title: Display Name
          description: Human-readable column name shown in Simple AI.
        referenceTable:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Table
          description: Required for REFERENCE columns. Use a custom table name or a supported system reference table such as calls.
        jsonSchema:
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          title: JSON Schema
          description: Required for OBJECT columns. Provide an OpenAPI/JSON Schema object that describes the structured value.
      title: Custom Data Column Input
    DeleteCustomDataRecordResponse:
      type: object
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          default: true
        message:
          type: string
          title: Message
      title: Delete Custom Data Record Response
    DeleteCustomDataTableResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          default: true
      title: Delete Custom Data Table Response
    ErrorResponse:
      type: object
      required:
      - status
      - success
      - error
      - errors
      properties:
        status:
          type: string
          default: error
        success:
          type: boolean
          default: false
        error:
          type: string
          title: Error
        errors:
          type: array
          items:
            type: string
          title: Errors
      title: Error Response
    CustomDataTable:
      type: object
      required:
      - id
      - name
      - label
      - searchIndexingEnabled
      - columns
      - recordCount
      - createdAt
      - updatedAt
      properties:
        id:
          type: integer
          title: ID
        name:
          type: string
          title: Name
        label:
          type: string
          title: Label
        searchIndexingEnabled:
          type: boolean
          title: Search Indexing Enabled
        columns:
          type: array
          items:
            $ref: '#/components/schemas/CustomDataColumn'
          title: Columns
        recordCount:
          type: integer
          title: Record Count
        createdAt:
          type: string
          format: date-time
          title: Created At
        updatedAt:
          type: string
          format: date-time
          title: Updated At
      title: Custom Data Table
    AvailableReferenceTable:
      type: object
      required:
      - name
      - displayName
      properties:
        name:
          type: string
          title: Name
        displayName:
          type: string
          title: Display Name
      title: Available Reference Table
    CustomDataFacetsResponse:
      type: object
      required:
      - tableName
      - tableLabel
      - totalRecords
      - facets
      properties:
        tableName:
          type: string
          title: Table Name
        tableLabel:
          type: string
          title: Table Label
        totalRecords:
          type: integer
          title: Total Records
        facets:
          type: array
          items:
            $ref: '#/components/schemas/CustomDataColumnFacet'
          title: Facets
      title: Custom Data Facets Response
    CustomDataRecordListResponse:
      type: object
      required:
      - records
      - total_count
      - page
      - per_page
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/CustomDataRecord'
          title: Records
        total_count:
          type: integer
          title: Total Count
        page:
          type: integer
          title: Page
        per_page:
          type: integer
          title: Per Page
      title: Custom Data Record List Response
    CustomDataRecord:
      type: object
      required:
      - id
      - organization_id
      - created_at
      - updated_at
      properties:
        id:
          type: integer
          title: ID
        organization_id:
          type: integer
          title: Organization ID
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      additionalProperties: true
      title: Custom Data Record
  securitySchemes:
    APIKeyHeader:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer YOUR_API_KEY`'