mammoth-io Generate AI data API

openapi: 3.2.0
info:
  title: Mammoth Io Generate AI data API
  version: 0.1.0
  contact:
    name: Mammoth Analytics
    url: https://mammoth.io
    email: support@mammoth.io
  description: 'Operations tagged Generate AI data across 2 of this provider''s published API definitions: app.mammoth.io-openapi.json, mammoth-io-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v2
security:
- bearerAuth: []
- apiKey: []
  apiSecret: []
  workspaceId: []
tags:
- name: Generate AI data
paths:
  /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}/data/generate:
    get:
      tags:
      - Generate AI data
      summary: Get validation information
      description: This endpoint fetches validation information with regards to the external service used to generate the data e.g. limits for the LLM provider key
      operationId: GetValidationInfo
      parameters:
      - name: workspace_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Workspace ID
          description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
          examples:
          - 4
        description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
        required: true
        deprecated: false
        examples:
          workspace_id-example-1:
            summary: Sample workspace ID
            value: 4
      - name: project_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Project ID
          description: Project ID of the workspace
          examples:
          - 4
        description: Project ID of the workspace
        required: true
        deprecated: false
        examples:
          project_id-example-1:
            summary: Sample project ID
            value: 4
      - name: dataset_id
        in: path
        schema:
          type: integer
          minimum: 0.0
          title: Dataset ID
          description: Id of the dataset
          examples:
          - 121
        description: Id of the dataset
        required: true
        deprecated: false
        examples:
          dataset_id-example-1:
            summary: Sample dataset ID
            value: 121
      - name: dataview_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Dataview ID
          description: Dataview ID of the dataset
          examples:
          - 4
        description: Dataview ID of the dataset
        required: true
        deprecated: false
        examples:
          dataview_id-example-1:
            summary: Sample dataview ID
            value: 4
      - name: sequence
        in: query
        schema:
          oneOf:
          - type: integer
          - type: 'null'
          - type: 'null'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      - name: validate_only
        in: query
        schema:
          oneOf:
          - type: boolean
            description: Validate AI generation for the view
            examples:
            - true
          - type: 'null'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      - name: api_key_id
        in: query
        schema:
          oneOf:
          - type: integer
            title: API Key ID
            description: The ID of the API key to use for generating AI data
            examples:
            - 1
          - type: 'null'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenAIValidationSpec'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                oneOf:
                - properties:
                    status_code:
                      type: integer
                    detail:
                      type: string
                    extra:
                      additionalProperties: {}
                      type:
                      - 'null'
                      - object
                      - array
                  type: object
                  required:
                  - detail
                  - status_code
                  description: Client Error
                  examples:
                  - status_code: 400
                    detail: Bad Request
                    extra: {}
                - properties:
                    status_code:
                      type: integer
                    detail:
                      type: string
                    extra:
                      additionalProperties: {}
                      type:
                      - 'null'
                      - object
                      - array
                  type: object
                  required:
                  - detail
                  - status_code
                  description: Validation Exception
                  examples:
                  - status_code: 400
                    detail: Bad Request
                    extra: {}
        '403':
          description: Request forbidden -- authorization will not help
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Authorization Exception
                examples:
                - status_code: 403
                  detail: Forbidden
                  extra: {}
        '401':
          description: Authorization error
      deprecated: false
    post:
      tags:
      - Generate AI data
      summary: Generate AI preview data for a dataview for the given sequence
      description: Given the prompt, generate AI data againt a sequence number in the pipeline
      operationId: Preview
      parameters:
      - name: workspace_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Workspace ID
          description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
          examples:
          - 4
        description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
        required: true
        deprecated: false
        examples:
          workspace_id-example-1:
            summary: Sample workspace ID
            value: 4
      - name: project_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Project ID
          description: Project ID of the workspace
          examples:
          - 4
        description: Project ID of the workspace
        required: true
        deprecated: false
        examples:
          project_id-example-1:
            summary: Sample project ID
            value: 4
      - name: dataset_id
        in: path
        schema:
          type: integer
          minimum: 0.0
          title: Dataset ID
          description: Id of the dataset
          examples:
          - 121
        description: Id of the dataset
        required: true
        deprecated: false
        examples:
          dataset_id-example-1:
            summary: Sample dataset ID
            value: 121
      - name: dataview_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Dataview ID
          description: Dataview ID of the dataset
          examples:
          - 4
        description: Dataview ID of the dataset
        required: true
        deprecated: false
        examples:
          dataview_id-example-1:
            summary: Sample dataview ID
            value: 4
      - name: sequence
        in: query
        schema:
          oneOf:
          - type: integer
          - type: 'null'
          - type: 'null'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      - name: api_key_id
        in: query
        schema:
          oneOf:
          - type: integer
            title: API Key ID
            description: The ID of the API key to use for generating AI data
            examples:
            - 1
          - type: 'null'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenAISpec'
        required: true
      responses:
        '201':
          description: Document created, URL follows
          headers: {}
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                oneOf:
                - properties:
                    status_code:
                      type: integer
                    detail:
                      type: string
                    extra:
                      additionalProperties: {}
                      type:
                      - 'null'
                      - object
                      - array
                  type: object
                  required:
                  - detail
                  - status_code
                  description: Client Error
                  examples:
                  - status_code: 400
                    detail: Bad Request
                    extra: {}
                - properties:
                    status_code:
                      type: integer
                    detail:
                      type: string
                    extra:
                      additionalProperties: {}
                      type:
                      - 'null'
                      - object
                      - array
                  type: object
                  required:
                  - detail
                  - status_code
                  description: Validation Exception
                  examples:
                  - status_code: 400
                    detail: Bad Request
                    extra: {}
        '403':
          description: Request forbidden -- authorization will not help
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Authorization Exception
                examples:
                - status_code: 403
                  detail: Forbidden
                  extra: {}
        '200':
          description: AI data generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenAIData'
        '401':
          description: Authorization error
      deprecated: false
    servers:
    - url: /api/v2
  /workspaces/{workspace_id}/projects/{project_id}/suggestions:
    post:
      tags:
      - Generate AI data
      summary: Generate AI-based Suggestions for Dataview
      description: Given the prompt, generate AI data against a sequence number in the pipeline
      operationId: AiSuggestions
      parameters:
      - name: workspace_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Workspace ID
          description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
          examples:
          - 4
        description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
        required: true
        deprecated: false
        examples:
          workspace_id-example-1:
            summary: Sample workspace ID
            value: 4
      - name: project_id
        in: path
        schema:
          type: integer
          minimum: 1.0
          title: Project ID
          description: Project ID of the workspace
          examples:
          - 4
        description: Project ID of the workspace
        required: true
        deprecated: false
        examples:
          project_id-example-1:
            summary: Sample project ID
            value: 4
      - name: dataset_id
        in: query
        schema:
          oneOf:
          - type: integer
          - type: 'null'
          title: Dataset ID
          description: Id of the dataset
          examples:
          - 121
        description: Id of the dataset
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          dataset_id-example-1:
            summary: Sample dataset ID
            value: 121
      - name: dataview_id
        in: query
        schema:
          type: integer
          minimum: 1.0
          title: Dataview ID
          description: Dataview ID of the dataset
          default: 4
          examples:
          - 4
        description: Dataview ID of the dataset
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          dataview_id-example-1:
            summary: Sample dataview ID
            value: 4
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnifiedPromptSpec'
        required: true
      responses:
        '202':
          description: Request accepted, processing continues off-line
          headers: {}
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                - {}
                - $ref: '#/components/schemas/JobResponse'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                oneOf:
                - properties:
                    status_code:
                      type: integer
                    detail:
                      type: string
                    extra:
                      additionalProperties: {}
                      type:
                      - 'null'
                      - object
                      - array
                  type: object
                  required:
                  - detail
                  - status_code
                  description: Client Error
                  examples:
                  - status_code: 400
                    detail: Bad Request
                    extra: {}
                - properties:
                    status_code:
                      type: integer
                    detail:
                      type: string
                    extra:
                      additionalProperties: {}
                      type:
                      - 'null'
                      - object
                      - array
                  type: object
                  required:
                  - detail
                  - status_code
                  description: Validation Exception
                  examples:
                  - status_code: 400
                    detail: Bad Request
                    extra: {}
        '403':
          description: Request forbidden -- authorization will not help
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Authorization Exception
                examples:
                - status_code: 403
                  detail: Forbidden
                  extra: {}
        '200':
          description: The request was processed successfully, but a valid regex pattern could not be generated
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Regex and example generated successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Authorization error
      deprecated: false
    servers:
    - url: /api/v2
components:
  schemas:
    Limits:
      properties:
        can_process_max_rows:
          type: boolean
        max_rows_allowed:
          oneOf:
          - type: integer
          - type: 'null'
      type: object
      required:
      - can_process_max_rows
      title: Limits
    ExternalKeyType:
      type: string
      enum:
      - open_ai
      - anthropic
      - gemini
      - grok
      maxLength: 100
      minLength: 1
      title: ExternalKeyType
      description: Type of the external key e.g. open_ai
      examples:
      - value: open_ai
    GenAISpec:
      properties:
        columns:
          oneOf:
          - items:
              type: string
            type: array
          - type: 'null'
        no_of_rows:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Number of rows to be generated
        prompt:
          type: string
      type: object
      required:
      - no_of_rows
      - prompt
      title: GenAISpec
      description: Parameters required to generate AI data
      examples:
      - columns:
        - column_1
        no_of_rows: 10
        prompt: Describe the nature of the data of each cell in the given columns
    GenAIData:
      properties:
        data:
          type: array
        context_columns:
          items:
            type: string
          type: array
        provider:
          oneOf:
          - $ref: '#/components/schemas/ExternalKeyType'
          - type: 'null'
      type: object
      required:
      - context_columns
      - data
      title: GenAIData
    GenAIValidationSpec:
      properties:
        limits:
          oneOf:
          - $ref: '#/components/schemas/Limits'
          - type: 'null'
        is_key_valid:
          type: boolean
        error_code:
          oneOf:
          - type: string
          - type: 'null'
        error_message:
          oneOf:
          - type: string
          - type: 'null'
      type: object
      required:
      - is_key_valid
      title: GenAIValidationSpec
    JsonSuggestParams:
      properties:
        internal_name:
          type: string
          title: InternalName
          description: Internal column name to infer the JSON structure for
        sequence_number:
          oneOf:
          - type: integer
          - type: 'null'
          title: SequenceNumber
          description: Pipeline step at which to sample the column's values
      type: object
      required:
      - internal_name
      title: JsonSuggestParams
    JobSchema:
      properties:
        id:
          type: integer
          minimum: 0.0
          title: Job id
          examples:
          - value:
              id: 10
        status:
          type: string
          enum:
          - success
          - failure
          - processing
          - error
          title: Job status
          description: Job status can be success, failure or processing
          examples:
          - value:
              status: success
        response:
          oneOf:
          - type: object
          - type: array
          description: Result of async task is stored in response
          examples:
          - value:
              response:
                object: some object
        last_updated_at:
          type: string
          format: date-time
          title: Job last updated at
          description: Job last updated at is the time when Job status was last updated
          examples:
          - value:
              last_updated_at: '2021-08-10T10:00:00'
        created_at:
          type: string
          format: date-time
          title: Job created at
          description: Create at is time when async task was created
          examples:
          - value:
              created_at: '2021-08-10T10:00:00'
        path:
          type: string
          title: Job path
          description: API request path of the Job operation
          examples:
          - value:
              path: /api/v2/dataviews/1
        operation:
          type: string
          title: Job operation
          description: Operation is async task name which Job is tracking
          examples:
          - value:
              operation: post_modification_pipeline_execution
      type: object
      required:
      - created_at
      - id
      - last_updated_at
      - operation
      - path
      - response
      - status
      title: JobSchema
    GenerateTaskParams:
      properties:
        prompt:
          oneOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: Plain English condition, e.g., 'Filter rows where Price > 100'
        task_template:
          oneOf:
          - items:
              $ref: '#/components/schemas/TaskMinimalSchema'
            type: array
          - type: 'null'
          title: Task Template
          description: A list of dictionaries defining task templates, including task name, columns, reasons, etc.
        task_key:
          oneOf:
          - type: string
          - type: 'null'
          title: Task Key
          description: This task key is optional. If the user is interacting from within the function panel, frontend will include this key alongside the prompt. This allows the backend to send only the relevant rule/function information to the LLM for context, instead of all available rules.
      type: object
      required: []
      title: GenerateTaskParams
    ColumnDetails:
      properties:
        name:
          type: string
          description: Name of the column to apply the task to
        reason:
          type: string
          description: Reason for applying the task to this column
      type: object
      required:
      - name
      - reason
      title: ColumnDetails
    AddConditionParams:
      properties:
        sequence_number:
          type: integer
          title: Sequence Number
          description: The rule's order in the processing pipeline
        prompt:
          type: string
          title: Prompt
          description: A human-readable condition statement, specifying a rule for data processing, e.g., 'Filter rows where Price > 100'
        origin:
          type:
          - 'null'
          - string
          enum:
          - functions_panel
          - null
          title: Origin
          description: Specifies the source of the API call that triggered this condition addition. Defaults to 'functions_panel'.
      type: object
      required:
      - prompt
      - sequence_number
      title: AddConditionParams
    CustomPromptParams:
      properties:
        column_name:
          type: string
          title: Column Name
          description: The name of the column to apply extraction on
        sequence_number:
          type: integer
          minimum: 1.0
          title: Sequence Number
          description: The sequence order of the extraction rule
        prompt:
          oneOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: The user-defined prompt for AI-based extraction
        edit_regex:
          oneOf:
          - $ref: '#/components/schemas/EditRegexSpec'
          - type: 'null'
          title: EditRegex
          description: Optional edited regex pattern details for extraction
      type: object
      required:
      - column_name
      - sequence_number
      title: CustomPromptParams
    UnifiedPromptSpec:
      properties:
        suggestion_type:
          type: string
          enum:
          - extract_text
          - add_condition
          - generate_task
          - apply_ai_template
          - derivative_fuzzy_bucket
          - date_format
          - json_suggest
          title: Suggestion Type
          description: Type of operation (extraction or conditional filtering)
        params:
          oneOf:
          - $ref: '#/components/schemas/CustomPromptParams'
          - $ref: '#/components/schemas/AddConditionParams'
          - $ref: '#/components/schemas/GenerateTaskParams'
          - $ref: '#/components/schemas/DerivativeFuzzyBucketParams'
          - $ref: '#/components/schemas/DateFormatParams'
          - $ref: '#/components/schemas/JsonSuggestParams'
          title: Params
          description: Encapsulated parameters for the operation
      type: object
      required:
      - params
      - suggestion_type
      title: UnifiedPromptSpec
      description: Parameters required for intent-based extraction or filtering
      examples:
      - suggestion_type: extract_text
        params:
          column_name: comments
          sequence_number: 1
          prompt: Extract all mentions of product issues
          edit_regex: null
      - suggestion_type: add_condition
        params:
          sequence_number: 2
          prompt: Show records where Department contains 'cake'
          origin: null
    DerivativeFuzzyBucketParams:
      properties:
        column:
          type: string
          title: Column
          description: Name of the column to generate fuzzy-bucket suggestions for
        params:
          type: object
          title: Param
          description: Volatile query specification used to fetch sample values for the column
        grouping_strategy:
          oneOf:
          - type: string
          - type: 'null'
          title: Grouping Strategy
          description: Strategy used to group similar values, e.g. 'auto'
        method:
          oneOf:
          - type: string
          - type: 'null'
          title: Method
          description: Clustering method used for fuzzy bucketing, e.g. 'pdist'
        groups:
          oneOf:
          - items:
              type: object
            type: array
          - type: 'null'
          title: Groups
          description: The modal's in-progress bulk-replace groups (NAME/STATIC_VALUES/DYNAMIC_VALUES), if any. When present, the sample query used to generate clustering candidates is annotated with ownership against these groups, so each suggested value already carries its true count and current owning group -- no separate follow-up annotation request needed.
      type: object
      required:
      - column
      - params
      title: DerivativeFuzzyBucketParams
    JobResponse:
      properties:
        job:
          $ref: '#/components/schemas/JobSchema'
      type: object
      required:
      - job
      title: JobResponse
    DateFormatParams:
      properties:
        samples:
          items:
            type: string
          type: array
          title: Samples
          description: Sample values to detect a date format for, or validate against a given format
        format:
          oneOf:
          - type: string
          - type: 'null'
          title: Format
          description: Postgres-style date format to validate the samples against. When omitted, matching date formats are detected instead.
      type: object
      required:
      - samples
      title: DateFormatParams
    TaskMinimalSchema:
      properties:
        task_name:
          type: string
          enum:
          - SQL Query
          - Generative AI
          - Extract Text
          - Bulk Replace
          - Conditional Filter
          - Remove Duplicate Rows
          - Show Top/Bottom Rows
          - Edit Cells
          - Label & Insert Values
          - Fill Missing Values
          - Find & Replace
          - Increment/Decrement Date Values
          - Extract Date Part
          - Calculate Date Difference
          - Math Function
          - Window Function
          - Obtain Large or Small Values
          - Text Formatting
          - Extract JSON
          - Group & Aggregate
          - Columns To Rows
          - Crosstab
          - Add Column
          - Copy Columns
          - Combine Multiple Columns
          - Convert Column Type
          - Remove Column
          - Split Into Multiple Columns
          - Branch Out
          - Join
          - Lookup
          description: UI-facing task name
        task_description:
          type: string
          description: Description of the transformation task. Include names of columns involved and how those columns are used.
        columns:
          items:
            $ref: '#/components/schemas/ColumnDetails'
          type: array
          description: List of columns involved in the task
        task_key:
          type: string
          description: Automatically compute task_key from task_name
          readOnly: true
      type: object
      required:
      - columns
      - task_description
      - task_key
      - task_name
      title: TaskMinimalSchema
    EditRegexSpec:
      properties:
        expression:
          type: string
          title: Expression
          description: Regex pattern for extraction
        delimiter:
          type: string
          title: Delimiter
          description: Delimiter used in regex pattern
        global_flag:
          type: boolean
          title: Global
          description: Whether the regex should match globally
        capturing_groups:
          items:
            type: integer
          type: array
          title: Capturing Groups
          description: List of capturing group indices
      type: object
      required:
      - capturing_groups
      - delimiter
      - expression
      - global_flag
      title: EditRegexSpec
  securitySchemes:
    bearerAuth:
      type: http
      description: 'Primary credential. Authorization: Bearer mm_<token>. The token is issued server-side and shown once at creation.'
      scheme: bearer
    apiKey:
      type: apiKey
      description: Deprecated — use bearerAuth.
      name: X-API-KEY
      in: header
    apiSecret:
      type: apiKey
      description: Deprecated — use bearerAuth.
      name: X-API-SECRET
      in: header
    workspaceId:
      type: apiKey
      description: Required with X-API-KEY and X-API-SECRET. Deprecated with them — use bearerAuth.
      name: X-WORKSPACE-ID
      in: header
x-refined-from:
- app.mammoth.io-openapi.json
- mammoth-io-openapi.json