Scale AI Indexes API

openapi: 3.2.0
info:
  title: Document Understanding Indexes API
  description: API for uploading and processing documents
  version: 0.6.0
security:
- ApiKey: []
  AccountId: []
tags:
- name: Indexes
paths:
  /v1/projects/{project_id}/indexes:
    post:
      tags:
      - Indexes
      summary: Create Index
      description: 'Create an empty index (synchronous).


        Allocates the DB record, writes an empty serialized engine to blob

        storage with the provided config, and marks the index ``ready``. Files

        are added later via ``POST /indexes/{index_id}/files`` (which kicks off

        a batch-mutation workflow).'
      operationId: create_index_v1_projects__project_id__indexes_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/FileSystemIndexCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexEntity'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Indexes
      summary: List Indexes
      description: List all indexes for a project.
      operationId: list_indexes_v1_projects__project_id__indexes_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IndexEntityBase'
                title: Response List Indexes V1 Projects  Project Id  Indexes Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/indexes/{index_id}:
    get:
      tags:
      - Indexes
      summary: Get Index
      description: Get a specific index with nodes hydrated from blob storage.
      operationId: get_index_v1_projects__project_id__indexes__index_id__get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: index_id
        in: path
        required: true
        schema:
          type: string
          title: Index Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexEntity'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Indexes
      summary: Delete Index
      description: Delete an index and its blob storage.
      operationId: delete_index_v1_projects__project_id__indexes__index_id__delete
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: index_id
        in: path
        required: true
        schema:
          type: string
          title: Index Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/indexes/{index_id}/files:
    post:
      tags:
      - Indexes
      summary: Batch Upsert Files To Index
      description: Add or update a batch of files in an existing index. Async via Temporal.
      operationId: batch_upsert_files_to_index_v1_projects__project_id__indexes__index_id__files_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: index_id
        in: path
        required: true
        schema:
          type: string
          title: Index Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpsertFilesRequest'
      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'
    delete:
      tags:
      - Indexes
      summary: Batch Delete Files From Index
      description: Delete a batch of files from an existing index. Async via Temporal.
      operationId: batch_delete_files_from_index_v1_projects__project_id__indexes__index_id__files_delete
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: index_id
        in: path
        required: true
        schema:
          type: string
          title: Index Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchDeleteFilesRequest'
      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}/indexes/{index_id}/search:
    post:
      tags:
      - Indexes
      summary: Search Index
      description: Search the index for relevant document IDs.
      operationId: search_index_v1_projects__project_id__indexes__index_id__search_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: index_id
        in: path
        required: true
        schema:
          type: string
          title: Index Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/indexes/{index_id}/navigate:
    post:
      tags:
      - Indexes
      summary: Navigate Index
      description: Navigate the index hierarchy.
      operationId: navigate_index_v1_projects__project_id__indexes__index_id__navigate_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: index_id
        in: path
        required: true
        schema:
          type: string
          title: Index Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexNavigateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexNavigateResponse'
        '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.
    IndexStatus:
      type: string
      enum:
      - pending
      - ready
      - updating
      - failed
      title: IndexStatus
    BatchDeleteFilesRequest:
      properties:
        file_ids:
          items:
            type: string
          type: array
          maxItems: 1000
          minItems: 1
          title: File Ids
      type: object
      required:
      - file_ids
      title: BatchDeleteFilesRequest
      description: Request body for ``DELETE /indexes/{index_id}/files``.
    IndexEngineType:
      type: string
      enum:
      - file_system
      title: IndexEngineType
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IndexSearchRequest:
      properties:
        query:
          type: string
          title: Query
          description: Search query
        top_k:
          type: integer
          title: Top K
          description: Number of results to return
          default: 5
        current_node_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Node Id
          description: If specified, only search within this node's subtree
      type: object
      required:
      - query
      title: IndexSearchRequest
      description: Request body for searching an index.
    IndexNavigateResponse:
      properties:
        query:
          type: string
          title: Query
        nodes:
          items:
            $ref: '#/components/schemas/Node'
          type: array
          title: Nodes
      type: object
      required:
      - query
      - nodes
      title: IndexNavigateResponse
      description: Response body for ``POST /indexes/{index_id}/navigate``.
    IndexEntityBase:
      properties:
        id:
          type: string
          title: Id
          description: ID of the entity
        project_id:
          type: string
          title: Project Id
          description: ID of the project
        name:
          type: string
          title: Name
          description: Display name of the index
        engine_type:
          $ref: '#/components/schemas/IndexEngineType'
          description: Type of index engine
        status:
          $ref: '#/components/schemas/IndexStatus'
          description: Index status
          default: pending
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp
      type: object
      required:
      - id
      - project_id
      - name
      - engine_type
      - created_at
      - updated_at
      title: IndexEntityBase
      description: Index metadata (returned by list).
    BatchUpsertFilesRequest:
      properties:
        file_ids:
          items:
            type: string
          type: array
          maxItems: 1000
          minItems: 1
          title: File Ids
      type: object
      required:
      - file_ids
      title: BatchUpsertFilesRequest
      description: Request body for ``POST /indexes/{index_id}/files``.
    IndexSearchResponse:
      properties:
        query:
          type: string
          title: Query
        nodes:
          items:
            $ref: '#/components/schemas/Node'
          type: array
          title: Nodes
          description: Matched nodes ranked by relevance
      type: object
      required:
      - query
      - nodes
      title: IndexSearchResponse
      description: Response body for ``POST /indexes/{index_id}/search``.
    IndexEntity:
      properties:
        id:
          type: string
          title: Id
          description: ID of the entity
        project_id:
          type: string
          title: Project Id
          description: ID of the project
        name:
          type: string
          title: Name
          description: Display name of the index
        engine_type:
          $ref: '#/components/schemas/IndexEngineType'
          description: Type of index engine
        status:
          $ref: '#/components/schemas/IndexStatus'
          description: Index status
          default: pending
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp
        config:
          additionalProperties: true
          type: object
          title: Config
          description: Engine-specific config
        nodes:
          items:
            $ref: '#/components/schemas/Node'
          type: array
          title: Nodes
          description: Index tree nodes
      type: object
      required:
      - id
      - project_id
      - name
      - engine_type
      - created_at
      - updated_at
      title: IndexEntity
      description: Full index entity with nodes and config (returned by get by ID).
    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.
    Node:
      properties:
        id:
          type: string
          title: Id
        text:
          type: string
          title: Text
        level:
          type: integer
          title: Level
        parent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Id
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        children_ids:
          items:
            type: string
          type: array
          title: Children Ids
      type: object
      required:
      - id
      - text
      - level
      title: Node
    IndexNavigateRequest:
      properties:
        query:
          type: string
          title: Query
          description: Navigation query
        current_node_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Node Id
          description: Node ID to navigate from (None for root)
        top_k:
          type: integer
          title: Top K
          description: Number of results to return
          default: 5
      type: object
      required:
      - query
      title: IndexNavigateRequest
      description: Request body for navigating an index.
    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.
    FileSystemIndexCreateRequest:
      properties:
        model:
          type: string
          title: Model
          description: Model to use for summarization
          default: openai/gpt-5.2
        file_summarization_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: File Summarization Prompt
          description: Custom instructions for file summarization
        folder_summarization_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Folder Summarization Prompt
          description: Custom instructions for folder summarization
        name:
          type: string
          title: Name
          description: Display name of the index
        engine_type:
          type: string
          const: file_system
          title: Engine Type
          default: file_system
      type: object
      required:
      - name
      title: FileSystemIndexCreateRequest
      description: Create request for the file-system index engine.
    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