Insight Genius Processing API

openapi: 3.2.0
info:
  title: SPSS InsightGenius Processing API
  description: '**SPSS InsightGenius API** — REST API for processing SPSS (.sav) files.


    Powered by QuantipyMRX for market research analysis: crosstabs with significance testing, auto-detection of question types, NPS, Top/Bottom Box, nets, and AI-powered Reporting Ticket parsing via Claude Haiku.


    ## Authentication

    All endpoints require `Authorization: Bearer sk_live_...` or `sk_test_...`


    ## Rate Limits

    | Plan | Requests/min | Max file size |

    |------|-------------|---------------|

    | Free (sk_test_) | 10 | 5 MB |

    | Pro | 60 | 50 MB |

    | Business | 200 | 200 MB |'
  version: 1.0.0
tags:
- name: Processing
  description: 'Full pipeline: upload + analyze + return results'
paths:
  /v1/process:
    post:
      tags:
      - Processing
      summary: Full processing pipeline
      description: Upload a .sav file with optional Reporting Ticket or manual operations spec. Returns metadata + all analysis results.
      operationId: process_v1_process_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_process_v1_process_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tabulate:
    post:
      tags:
      - Processing
      summary: Full tabulation → Excel
      description: 'Upload a .sav file, specify a banner variable (demographic) and stub variables (questions to analyze), and receive a professional Excel workbook with:


        - One sheet per stub variable

        - Crosstab with column percentages

        - Significance letters (A/B/C notation)

        - Column bases (N)

        - Optional nets (Top 2 Box, Bottom 2 Box, etc.)

        - Summary sheet with column legend and stub index


        **Example spec:**

        ```json

        {

        "banner": "Q_4",

        "stubs": ["Q_2", "Q_3", "Q_5"],

        "significance_level": 0.95,

        "weight": "WEIGHT1",

        "nets": {"Q_2": {"Top 2 Box": [5, 6], "Bottom 2 Box": [1, 2]}},

        "title": "Customer Satisfaction Study 2026"

        }

        ```


        Set `stubs` to `["_all_"]` to auto-select all variables with value labels.'
      operationId: tabulate_v1_tabulate_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_tabulate_v1_tabulate_post'
        required: true
      responses:
        '200':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/workbook/front-sheets:
    post:
      tags:
      - Processing
      summary: Add sheets at the front of a workbook this engine generated
      description: '24-oct-2026. Survey Coder agregaba «Revisión del archivo» y «Advertencias

        de calidad» reabriendo el libro con ExcelJS, que no abre un libro con

        comentarios de celda: el libro entero fallaba. El texto de la revisión

        depende de lo que el motor aplicó, así que se agrega DESPUÉS de generar,

        aquí, con la misma librería que escribió el libro.'
      operationId: workbook_front_sheets_v1_workbook_front_sheets_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_workbook_front_sheets_v1_workbook_front_sheets_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/preparation/inspect:
    post:
      tags:
      - Processing
      summary: Read bounded aggregate evidence for study preparation
      operationId: inspect_preparation_v1_preparation_inspect_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_inspect_preparation_v1_preparation_inspect_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/preparation/preview:
    post:
      tags:
      - Processing
      summary: Validate a preparation against a SAV without changing it
      operationId: preview_preparation_v1_preparation_preview_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_preview_preparation_v1_preparation_preview_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auto-analyze:
    post:
      tags:
      - Processing
      summary: Zero-config auto analysis
      description: Upload a .sav file and get a complete Excel workbook with auto-detected banners, stubs, nets, MRS groups, and significance testing. No configuration needed.
      operationId: auto_analyze_v1_auto_analyze_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_auto_analyze_v1_auto_analyze_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/auto-analyze:
    post:
      tags:
      - Processing
      summary: Zero-config auto analysis for an existing project
      description: Runs the same auto-detect banner/stub/nets/MRS pipeline as /v1/auto-analyze, but on an already-uploaded project's data (with active Data Prep rules and weight applied). Returns a complete Excel workbook.
      operationId: project_auto_analyze_v1_projects__project_id__auto_analyze_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Body_auto_analyze_v1_auto_analyze_post:
      properties:
        background_book:
          type: boolean
          title: Background Book
          description: Paid background export budget
          default: false
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: SPSS .sav file (or use file_id)
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: File session ID from /v1/library/upload
        ticket:
          type: string
          contentMediaType: application/octet-stream
          title: Ticket
          description: Reporting Ticket .docx — AI parses it to override auto-detection
        options:
          type: string
          title: Options
          description: 'Optional JSON: {"max_banners": 3, "output_mode": "multi_sheet", "significance_level": 0.95}'
          default: '{}'
        response_format:
          anyOf:
          - type: string
          - type: 'null'
          title: Response Format
          description: '"xlsx" (default): the workbook as a binary stream. "bundle": JSON with the workbook in base64, the stats, and the assumptions the engine made for THIS run.'
      type: object
      title: Body_auto_analyze_v1_auto_analyze_post
    Body_inspect_preparation_v1_preparation_inspect_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
        inspection:
          type: string
          title: Inspection
          default: '{}'
        all_pages:
          type: boolean
          title: All Pages
          default: false
        dependency_batches:
          anyOf:
          - type: string
          - type: 'null'
          title: Dependency Batches
      type: object
      title: Body_inspect_preparation_v1_preparation_inspect_post
    Body_preview_preparation_v1_preparation_preview_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
        preparation:
          type: string
          title: Preparation
      type: object
      required:
      - preparation
      title: Body_preview_preparation_v1_preparation_preview_post
    Body_process_v1_process_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: SPSS .sav file (or use file_id)
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: File session ID from /v1/library/upload
        operations:
          anyOf:
          - type: string
          - type: 'null'
          title: Operations
          description: JSON array of operation specs
        ticket:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: Ticket
          description: Reporting Ticket .docx (optional)
        weight:
          anyOf:
          - type: string
          - type: 'null'
          title: Weight
          description: Default weight variable
      type: object
      title: Body_process_v1_process_post
    Body_tabulate_v1_tabulate_post:
      properties:
        background_book:
          type: boolean
          title: Background Book
          description: Paid background export budget; not for interactive queries
          default: false
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: .sav file to tabulate (or use file_id)
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: File session ID from /v1/library/upload
        preparation_source:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: Preparation Source
          description: Original SAV that the preparation was reviewed against, when file is an enriched SAV
        spec:
          type: string
          title: Spec
          description: JSON tabulation specification
        ticket:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: Ticket
          description: Optional .docx Reporting Ticket — Haiku parses it into a tab plan
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
          description: URL to POST job result when processing completes. If provided, returns 202 with job_id instead of blocking.
        response_format:
          anyOf:
          - type: string
          - type: 'null'
          title: Response Format
          description: '"xlsx" (default): the workbook as a binary stream. "bundle": JSON with the workbook in base64, the stats, and the assumptions the engine made for THIS run (families, scale source, box nets, what happened to each column). Sync only.'
      type: object
      required:
      - spec
      title: Body_tabulate_v1_tabulate_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_workbook_front_sheets_v1_workbook_front_sheets_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: The .xlsx returned by /v1/tabulate
        sheets:
          type: string
          title: Sheets
          description: 'JSON: [{"name", "title", "intro"?, "header", "rows"}], at most 5'
      type: object
      required:
      - file
      - sheets
      title: Body_workbook_front_sheets_v1_workbook_front_sheets_post