Scale AI Research API

openapi: 3.2.0
info:
  title: Document Understanding Research API
  description: API for uploading and processing documents
  version: 0.6.0
security:
- ApiKey: []
  AccountId: []
tags:
- name: Research
  description: Dex Research agent kickoff and results.
paths:
  /v1/projects/{project_id}/research:
    post:
      tags:
      - Research
      summary: Create Research Job
      description: 'Kick off a Dex Research job.


        Persists a ``research`` job and starts :class:`~dex_api.temporal.research.workflows.research_workflow.ResearchWorkflow`

        on the research task queue.


        **Scope:** one ``inputs.vector_stores`` id, **or** one or more ``inputs.parse_results`` ids

        (no mixing with vector stores). **Empty inputs:** if the project has exactly one vector store,

        that store is used automatically (empty-input shortcut).'
      operationId: create_research_job_v1_projects__project_id__research_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchJobRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobEntity'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/research/results:
    get:
      tags:
      - Research
      summary: List Research Results
      description: 'List research jobs for this project (same persistence as ``GET …/jobs``,

        forced to ``operation=research``).


        Returns :class:`~dex_core.models.jobs.JobEntity` rows (operation is always ``research``).'
      operationId: list_research_results_v1_projects__project_id__research_results_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by job IDs
          title: Ids
        description: Filter by job IDs
      - name: created_at_start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by creation time (start)
          title: Created At Start
        description: Filter by creation time (start)
      - name: created_at_end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by creation time (end)
          title: Created At End
        description: Filter by creation time (end)
      - name: completed_at_start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by completion time (start)
          title: Completed At Start
        description: Filter by completion time (start)
      - name: completed_at_end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by completion time (end)
          title: Completed At End
        description: Filter by completion time (end)
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/JobStatus'
          - type: 'null'
          description: Filter by job status
          title: Status
        description: Filter by job status
      - name: operation
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/JobOperationType'
          - type: 'null'
          description: Filter by job operation type
          title: Operation
        description: Filter by job operation type
      - name: page_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 100
            minimum: 1
          - type: 'null'
          description: Number of items per page
          title: Page Size
        description: Number of items per page
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Field to sort by
          title: Sort By
        description: Field to sort by
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          description: Sort order (asc or desc)
          title: Sort Order
        description: Sort order (asc or desc)
      - name: continuation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination token
          title: Continuation Token
        description: Pagination token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/PaginatedItems_JobEntity_'
                - type: array
                  items:
                    $ref: '#/components/schemas/JobEntity'
                title: Response List Research Results V1 Projects  Project Id  Research Results Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BatchChildJobInfo:
      properties:
        source_document_id:
          type: string
          title: Source Document Id
          description: Source document ID
        job_id:
          type: string
          title: Job Id
          description: Child job ID
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Status of the child job
        parse_result_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parse Result Id
          description: Parse result ID if succeeded
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if failed
      type: object
      required:
      - source_document_id
      - job_id
      - status
      title: BatchChildJobInfo
      description: Status of a single child job within a batch.
    ResearchTask:
      properties:
        description:
          type: string
          title: Description
          description: Goal of the research / extraction task
        plan:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan
          description: Unstructured plan or guidance for the agent
        output_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Output Schema
          description: JSON Schema for structured output
        report_schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Report Schema
          description: Unstructured template (e.g. markdown) for report-style output
      type: object
      required:
      - description
      title: ResearchTask
      description: 'User task: goal, optional plan, and structured or report-shaped output.'
    ResearchSpreadsheetAdvanced:
      properties:
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model for the spreadsheet (Excel) sub-agent; defaults to the subtask/acting model.
        rules:
          anyOf:
          - type: string
          - type: 'null'
          title: Rules
          description: Extra rules appended to the spreadsheet sub-agent's system prompt (e.g. summarise large sheets).
        max_hops:
          anyOf:
          - type: integer
            maximum: 50.0
            minimum: 1.0
          - type: 'null'
          title: Max Hops
          description: Max ReAct iterations inside the spreadsheet sub-agent (default 20); distinct from subtasks.max_cycles.
      type: object
      title: ResearchSpreadsheetAdvanced
      description: Excel / spreadsheet sub-agent overrides (``advanced.spreadsheet``).
    ResearchInputs:
      properties:
        files:
          items:
            type: string
          type: array
          title: Files
          description: Uploaded file IDs (e.g. file_…) — not yet supported.
        parse_results:
          items:
            type: string
          type: array
          title: Parse Results
          description: Parse result IDs (e.g. pres_…)
        vector_stores:
          items:
            type: string
          type: array
          title: Vector Stores
          description: Vector store IDs to search
        indexes:
          items:
            type: string
          type: array
          title: Indexes
          description: Index IDs (at most one). Enables index-based search/navigation tools.
      type: object
      title: ResearchInputs
      description: Scoped inputs for a research job. If all are empty, the API resolves to the project's sole vector store.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResearchDecompositionAdvanced:
      properties:
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
          - $ref: '#/components/schemas/ResearchReasoningBlock'
          - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
        rules:
          anyOf:
          - type: string
          - type: 'null'
          title: Rules
          description: Extra rules appended to the decompose prompt (e.g. domain-specific subtask guidance).
      type: object
      title: ResearchDecompositionAdvanced
      description: Decomposition step overrides (``advanced.decomposition``).
    ResearchReasoningBlock:
      properties:
        effort:
          anyOf:
          - type: string
            enum:
            - high
            - medium
            - low
            - none
          - type: 'null'
          title: Effort
          description: Model reasoning effort where applicable
      type: object
      title: ResearchReasoningBlock
      description: Nested reasoning / effort block for ``advanced.*.reasoning``.
    ResearchAdvancedStep:
      properties:
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
          - $ref: '#/components/schemas/ResearchReasoningBlock'
          - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
      type: object
      title: ResearchAdvancedStep
      description: Shared knobs for decomposition, subtasks, aggregation, validation.
    ResearchAdvanced:
      properties:
        decomposition:
          anyOf:
          - $ref: '#/components/schemas/ResearchDecompositionAdvanced'
          - type: 'null'
          description: Decomposition step overrides (model, prompt, rules, temperature, reasoning)
        subtasks:
          anyOf:
          - $ref: '#/components/schemas/ResearchSubtaskAdvancedSettings'
          - type: 'null'
          description: Subtask / ReAct step overrides including max_cycles
        aggregation:
          anyOf:
          - $ref: '#/components/schemas/ResearchAdvancedStep'
          - type: 'null'
          description: Aggregation step overrides (model, prompt, temperature, reasoning)
        output_validation:
          anyOf:
          - $ref: '#/components/schemas/ResearchOutputValidationAdvanced'
          - type: 'null'
          description: Output validation / schema-fix loop overrides including max_cycles
        spreadsheet:
          anyOf:
          - $ref: '#/components/schemas/ResearchSpreadsheetAdvanced'
          - type: 'null'
          description: Spreadsheet (Excel) sub-agent overrides (model, rules, max_hops)
      type: object
      title: ResearchAdvanced
      description: Optional per-stage overrides (``advanced`` object).
    PaginatedItems_JobEntity_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/JobEntity'
          type: array
          title: Items
        total_count:
          type: integer
          title: Total Count
        next_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Token
        prev_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Prev Token
      type: object
      required:
      - items
      - total_count
      title: PaginatedItems[JobEntity]
    ResearchSubtaskAdvancedSettings:
      properties:
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
          - $ref: '#/components/schemas/ResearchReasoningBlock'
          - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
        max_cycles:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Cycles
          description: Max ReAct iterations per subtask (default 5)
        search_rules:
          anyOf:
          - type: string
          - type: 'null'
          title: Search Rules
          description: Extra rules appended to the reasoning step search action (e.g. search strategy hints).
        extraction_rules:
          anyOf:
          - type: string
          - type: 'null'
          title: Extraction Rules
          description: Extra rules appended to the reasoning step extract action (e.g. unit/sign conventions).
      type: object
      title: ResearchSubtaskAdvancedSettings
      description: ReAct / subtask loop settings (``advanced.subtasks``).
    ResearchOutputValidationAdvanced:
      properties:
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: Override prompt for this step
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model id for this step
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          description: Sampling temperature for this step
        reasoning:
          anyOf:
          - $ref: '#/components/schemas/ResearchReasoningBlock'
          - type: 'null'
          description: Reasoning-effort block (e.g. o-series)
        max_cycles:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Cycles
          description: Max validation–fix cycles (default 3)
      type: object
      title: ResearchOutputValidationAdvanced
      description: Schema validation / fix loop (``advanced.output_validation``).
    ResearchToolConfigEntry:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: When False, the tool is not offered to the agent
          default: true
        config:
          additionalProperties: true
          type: object
          title: Config
          description: Tool-specific configuration (e.g. top_k, filters, rerank_config)
      type: object
      title: ResearchToolConfigEntry
      description: Per-tool enablement and opaque config (e.g. search_config for similarity_search).
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
      description: 'Enum for project sort fields.

        Note that only non-nullable fields can be sorted by (for

        details, see: https://github.com/djrobstep/sqlakeyset?tab=readme-ov-file#limitations ).'
    JobHistoryEvent:
      properties:
        step:
          type: string
          title: Step
          description: Human-readable step name
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: When this event occurred
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
          description: Duration in milliseconds (for completed steps)
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: Event status (e.g., 'completed', 'failed')
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Additional event details
      type: object
      required:
      - step
      - timestamp
      title: JobHistoryEvent
      description: A single event in the job execution timeline.
    ResearchJobRequest:
      properties:
        inputs:
          $ref: '#/components/schemas/ResearchInputs'
          description: 'Explicit scope. Empty lists: the API resolves to the project''s **sole** vector store when exactly one exists; otherwise set vector_stores or parse_results explicitly.'
        task:
          $ref: '#/components/schemas/ResearchTask'
        tools:
          additionalProperties:
            $ref: '#/components/schemas/ResearchToolConfigEntry'
          type: object
          title: Tools
          description: Map tool name → enablement + config
        model:
          type: string
          title: Model
          description: Default model for all agent steps unless overridden in advanced
        advanced:
          anyOf:
          - $ref: '#/components/schemas/ResearchAdvanced'
          - type: 'null'
          description: Per-stage model/prompt/temperature/reasoning overrides
        execute_dependent_subtask_tool_hints:
          type: boolean
          title: Execute Dependent Subtask Tool Hints
          description: When True, DECOMPOSE tool hints for dependent subtasks are executed as warm-start searches (same semantics as extract ``execute_dependent_subtask_tool_hints``). Default False (intent-only hints for dependents).
          default: false
        enable_subtable_citations:
          type: boolean
          title: Enable Subtable Citations
          description: When True, the agent may cite specific table cells/rows/ranges (block_ref#loc), resolved to sub-bboxes when the table was parsed with substructure recognition. Default False — whole-table citations only (previous behavior).
          default: false
        include_file_tree_in_prompt:
          type: string
          enum:
          - auto
          - all
          - folders
          - none
          title: Include File Tree In Prompt
          description: 'Whether the document file tree is embedded in the extraction prompt. ''auto'' (default) keeps existing behavior: omitted when a file-system index is configured (index tools browse the tree instead), else the full tree (''all''). ''all'' = every file path; ''folders'' = folder structure only; ''none'' = omit the tree entirely. Set ''none'' to avoid spending tokens on hundreds of unhelpful file names.'
          default: auto
      additionalProperties: false
      type: object
      required:
      - task
      - model
      title: ResearchJobRequest
      description: 'Kickoff body for ``POST /v1/projects/{project_id}/research``.


        Use ``tools`` for per-tool enablement and configuration (same map shape as

        :class:`~dex_core.models.extraction.ExtractionParameters.agentic_tools` on extract jobs).'
      example:
        advanced:
          decomposition:
            model: openai/gpt-5.4
            prompt: PROMPT_DECOMPOSITION
            reasoning:
              effort: high
            temperature: 0.0
          spreadsheet:
            max_hops: 12
            model: openai/gpt-5.3-codex
            rules: For sheets over 10k rows, summarise instead of printing.
          subtasks:
            model: openai/gpt-5.3-codex
            prompt: PROMPT_SUBTASKS
            temperature: 0.0
        inputs:
          parse_results:
          - pres_9f86d081884c7d659a2feaa0c55ad015
          vector_stores:
          - vector_store_9f86d081884c7d659a2feaa0c55ad015
        model: openai/gpt-5.4
        task:
          description: What is the Commencement Date of the document?
          output_schema:
            properties:
              commencement_date:
                description: The Commencement Date
                type: string
            type: object
          plan: '1. Find the Start Date

            2. Search for Commencement Date'
        tools:
          lexical_search:
            config: {}
            enabled: false
          similarity_search:
            config:
              filters:
                file_id:
                  $eq: file_9f86d081884c7d659a2feaa0c55ad015
              top_k: 5
            enabled: true
    JobOperationType:
      type: string
      enum:
      - parse
      - batch_parse
      - extract
      - research
      - vector_store
      - chunk
      - summarization
      - create_index
      - update_index
      title: JobOperationType
      description: Enum for job operation values.
    JobEntity:
      properties:
        id:
          type: string
          title: Id
          description: ID of the entity
        project_id:
          type: string
          title: Project Id
          description: ID of the project
        object:
          type: string
          const: job
          title: Object
          default: job
        operation:
          $ref: '#/components/schemas/JobOperationType'
          description: Operation type (e.g., 'parse')
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Current job status
        source_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Id
          description: Source document/file ID
        correlation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Correlation Id
          description: Request correlation ID for tracing
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the job was created
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: When the job started processing
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When the job completed
        result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result
          description: Job result payload when completed
        progress:
          anyOf:
          - $ref: '#/components/schemas/BatchParseProgress'
          - type: 'null'
          description: Live progress payload (used by batch jobs)
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if job failed
        history:
          anyOf:
          - items:
              $ref: '#/components/schemas/JobHistoryEvent'
            type: array
          - type: 'null'
          title: History
          description: Timeline of job execution events
      type: object
      required:
      - id
      - project_id
      - operation
      - status
      - created_at
      title: JobEntity
      description: Job response model representing an asynchronous operation.
    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
    JobStatus:
      type: string
      enum:
      - pending
      - running
      - succeeded
      - partially_succeeded
      - failed
      - cancelled
      title: JobStatus
      description: Enum for job status values.
    BatchParseProgress:
      properties:
        total:
          type: integer
          title: Total
          description: Total number of files in the batch
        succeeded:
          type: integer
          title: Succeeded
          description: Number of successfully parsed files
        failed:
          type: integer
          title: Failed
          description: Number of files that failed to parse
        cancelled:
          type: integer
          title: Cancelled
          description: Number of cancelled child jobs
        pending:
          type: integer
          title: Pending
          description: Number of files still pending (0 when job is terminal)
        child_jobs:
          items:
            $ref: '#/components/schemas/BatchChildJobInfo'
          type: array
          title: Child Jobs
          description: Per-child job status
      type: object
      required:
      - total
      - succeeded
      - failed
      - cancelled
      - pending
      - child_jobs
      title: BatchParseProgress
      description: Live progress tracking for a batch parse job.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
    AccountId:
      type: apiKey
      in: header
      name: x-selected-account-id
      description: Selected Account ID