Insight Genius Agent API

openapi: 3.2.0
info:
  title: SPSS InsightGenius Agent 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: Agent
paths:
  /v1/agent/chat:
    post:
      tags:
      - Agent
      summary: Streaming chat via Claude Agent SDK + MCP (replaces /v1/chat-stream)
      description: 'Open an Agent SDK session and stream the response.


        The agent connects to our own MCP server over loopback SSE, executes tools

        to compute answers, and streams results back to the browser as SSE events.

        Every tool call is logged to agent_tool_calls (Supabase).


        file_id resolution priority:

        1. Explicit file_id in the form (used by /try light demo + stateless API).

        2. project_id → primary file (used by the full app at /app where the

        user is logged in and we know which project they''re working on).'
      operationId: agent_chat_v1_agent_chat_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_agent_chat_v1_agent_chat_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/agent/smart-spec:
    post:
      tags:
      - Agent
      summary: Generate a TabulateSpec from .sav + questionnaire + ticket via the agent
      description: Upload an SPSS file (or pass file_id) plus optional questionnaire (.docx/.pdf) and/or reporting ticket (.docx). The agent reads everything, validates variables against the real metadata, and produces a TabulateSpec JSON ready to feed to /v1/tabulate. Every variable in the output is verified to exist in the dataset.
      operationId: agent_smart_spec_v1_agent_smart_spec_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_agent_smart_spec_v1_agent_smart_spec_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent/parse-ticket:
    post:
      tags:
      - Agent
      summary: Parse a Reporting Ticket (.docx) into a TabulateSpec-compatible plan via the…
      operationId: agent_parse_ticket_v1_agent_parse_ticket_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_agent_parse_ticket_v1_agent_parse_ticket_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/agent/report:
    post:
      tags:
      - Agent
      summary: Multi-analysis executive report via the agent
      description: Generate a deterministic executive report from an SPSS file. The agent plans 6-8 analyses, executes them via the MCP server, and writes a narrative citing the real numbers. Every figure is traceable via agent_tool_calls.
      operationId: agent_report_v1_agent_report_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_agent_report_v1_agent_report_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/agent/detect-structure:
    post:
      tags:
      - Agent
      summary: Propose study structure (MRS groups, grids, derived banners, scale T2B/B2B)…
      description: Upload a questionnaire (.docx or .pdf) plus a .sav (or pass file_id). The agent reads the questionnaire, cross-references it with the SPSS metadata, and proposes a structure for the analyst to review and apply. Every variable in the proposal is verified to exist in the dataset. Idempotent — running twice on the same inputs produces similar (not necessarily identical) suggestions.
      operationId: agent_detect_structure_v1_agent_detect_structure_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_agent_detect_structure_v1_agent_detect_structure_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent/detect-structure/{job_id}:
    get:
      tags:
      - Agent
      summary: Poll the status/result of an async detect-structure job
      description: Returns {status} while pending/running and {status, ...proposal} when done. status ∈ pending|running|done|failed. The proposal (mrs_groups, grid_groups, derived_banners, scales, unmapped, summary) is in `result` when status=done.
      operationId: agent_detect_structure_status_v1_agent_detect_structure__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_agent_detect_structure_v1_agent_detect_structure_post:
      properties:
        questionnaire:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: Questionnaire
          description: Questionnaire .docx or .pdf (optional if the project already has one stored)
        file:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: File
          description: SPSS .sav (omit if passing file_id)
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: Existing Redis session ID for the .sav
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: If provided, resolves file_id from the project's primary file (used by /app)
      type: object
      title: Body_agent_detect_structure_v1_agent_detect_structure_post
    Body_agent_report_v1_agent_report_post:
      properties:
        file_id:
          type: string
          title: File Id
          description: Redis file session ID (upload first via /v1/files/upload)
        depth:
          type: string
          title: Depth
          description: compact | standard | detailed
          default: standard
        language:
          type: string
          title: Language
          description: Report language (es, en, ...)
          default: es
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: Optional project ID for study brief context
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
      type: object
      required:
      - file_id
      title: Body_agent_report_v1_agent_report_post
    Body_agent_parse_ticket_v1_agent_parse_ticket_post:
      properties:
        ticket:
          type: string
          contentMediaType: application/octet-stream
          title: Ticket
          description: Reporting Ticket .docx
        file:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: File
          description: Optional .sav for variable matching
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
      type: object
      required:
      - ticket
      title: Body_agent_parse_ticket_v1_agent_parse_ticket_post
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_agent_smart_spec_v1_agent_smart_spec_post:
      properties:
        file:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: File
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
        questionnaire:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: Questionnaire
        ticket:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: Ticket
      type: object
      title: Body_agent_smart_spec_v1_agent_smart_spec_post
    Body_agent_chat_v1_agent_chat_post:
      properties:
        user_message:
          type: string
          title: User Message
          description: User's question
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: Redis file session ID (optional if project_id provided)
        conversation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversation Id
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: If provided, resolves file_id from the project's primary file
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        study_brief:
          anyOf:
          - type: string
          - type: 'null'
          title: Study Brief
          description: Optional JSON with study context (for demo)
      type: object
      required:
      - user_message
      title: Body_agent_chat_v1_agent_chat_post