openapi: 3.0.3
info:
  title: Reducto Cancel Extract Async API
  description: REST API for parsing, extracting, splitting, classifying, and editing complex documents. Supports PDFs, Word files, spreadsheets, presentations, and scanned images using layout-aware OCR and vision language models.
  version: v1.11.80-78-gc5c4ff11c
  contact:
    url: https://reducto.ai/
    email: support@reducto.ai
  license:
    name: Proprietary
servers:
- url: https://platform.reducto.ai
security:
- BearerAuth: []
tags:
- name: Extract Async
paths:
  /extract_async:
    post:
      summary: Extract Async
      operationId: extract_async_extract_async_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AsyncExtractConfig'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncExtractResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Extract Async
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
    Chunking:
      properties:
        chunk_mode:
          type: string
          enum:
          - variable
          - section
          - page
          - disabled
          - block
          - page_sections
          title: Chunk Mode
          description: Choose how to partition chunks. Variable mode chunks by character length and visual context. Section mode chunks by section headers. Page mode chunks according to pages. Page sections mode chunks first by page, then by sections within each page. Disabled returns one single chunk.
          default: disabled
        chunk_size:
          type: integer
          nullable: true
          title: Chunk Size
          description: The approximate size of chunks (in characters) that the document will be split into. Defaults to null, in which case the chunk size is variable between 250 - 1500 characters.
        chunk_overlap:
          type: integer
          title: Chunk Overlap
          description: Number of characters of overlap to include from adjacent chunks. Defaults to 0.
          default: 0
      type: object
      title: Chunking
    TenantThrottling:
      properties:
        tenant_id:
          type: string
          maxLength: 256
          minLength: 1
          title: Tenant Id
          description: Your identifier for the tenant (customer, workspace, organization) this request belongs to. Used only for noisy-neighbor throttling inside your account.
        max_share:
          type: number
          maximum: 1
          title: Max Share
          description: Maximum fraction of your account's concurrency ceiling this tenant may use, between 0 (exclusive) and 1. Defaults to 0.5.
          default: 0.5
          minimum: 0
          exclusiveMinimum: true
      type: object
      required:
      - tenant_id
      title: TenantThrottling
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Formatting:
      properties:
        add_page_markers:
          type: boolean
          title: Add Page Markers
          description: If True, add page markers to the output. Defaults to False. Useful for extracting data with page specific information.
          default: false
        table_output_format:
          type: string
          enum:
          - html
          - json
          - md
          - jsonbbox
          - dynamic
          - csv
          title: Table Output Format
          description: The mode to use for table output. Defaults to dynamic, which returns md for simpler tables and html for more complex tables.
          default: dynamic
        merge_tables:
          type: boolean
          title: Merge Tables
          description: A flag to indicate if consecutive tables with the same number of columns should be merged. Defaults to False.
          default: false
        include:
          items:
            type: string
            enum:
            - change_tracking
            - highlight
            - comments
            - hyperlinks
            - signatures
            - ignore_watermarks
          type: array
          title: Include
          description: A list of formatting to include in the output.
          default: []
      type: object
      title: Formatting
    UploadResponse:
      properties:
        file_id:
          type: string
          title: File Id
        presigned_url:
          type: string
          nullable: true
          title: Presigned Url
      type: object
      required:
      - file_id
      title: UploadResponse
    AsyncExtractResponse:
      properties:
        job_id:
          type: string
          title: Job Id
      type: object
      required:
      - job_id
      title: AsyncExtractResponse
    SplitLargeTables:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: If True, split large tables into smaller tables. Defaults to True.
          default: true
        size:
          anyOf:
          - type: integer
          - $ref: '#/components/schemas/SplitLargeTableSizes'
          title: Size
          description: The size of the tables to split into. Defaults to 50. Use 'row' and 'column' to independently specify the number of rows and columns to include when splitting. If you only want to split by rows or columns, set the other value to None.
          default: 50
      type: object
      title: SplitLargeTables
    Enhance:
      properties:
        agentic:
          items:
            anyOf:
            - $ref: '#/components/schemas/TableAgentic'
            - $ref: '#/components/schemas/FigureAgentic'
            - $ref: '#/components/schemas/TextAgentic'
          type: array
          title: Agentic
          description: Agentic uses vision language models to enhance the accuracy of the output of different types of extraction. This will incur a cost and latency increase.
          default: []
        summarize_figures:
          type: boolean
          title: Summarize Figures
          description: If True, summarize figures using a small vision language model. Defaults to True.
          default: true
        intelligent_ordering:
          type: boolean
          title: Intelligent Ordering
          description: If True, use an advanced vision language model to improve reading order accuracy, with a small increase in latency. Defaults to False.
          default: false
      type: object
      title: Enhance
    FigureAgentic:
      properties:
        scope:
          type: string
          title: Scope
          enum:
          - figure
        prompt:
          type: string
          nullable: true
          title: Prompt
          description: Custom prompt for figure agentic.
        advanced_chart_agent:
          type: boolean
          title: Advanced Chart Agent
          description: If True, use the advanced chart agent. Defaults to False.
          default: false
        return_overlays:
          type: boolean
          title: Return Overlays
          description: If True, return overlays for the figure. This is so you can use the overlays to double check the quality of the extraction
          default: false
      type: object
      required:
      - scope
      title: FigureAgentic
    HybridVpcSettings:
      properties:
        environment:
          type: string
          nullable: true
          title: Environment
          description: Named Hybrid VPC environment to use for this request. Only applies when your organization has Hybrid VPC environments configured.
      type: object
      title: HybridVpcSettings
    SplitLargeTableSizes:
      properties:
        row:
          type: integer
          nullable: true
          title: Row
          description: The number of rows to include in each chunk when splitting large tables. Does not chunk rows if set to None.
        column:
          type: integer
          nullable: true
          title: Column
          description: The number of columns to include in each chunk when splitting large tables. Does not chunk columns if set to None.
      type: object
      title: SplitLargeTableSizes
    ExtractSettings:
      properties:
        include_images:
          type: boolean
          title: Include Images
          description: If True, include images in the extraction.
          default: false
        optimize_for_latency:
          type: boolean
          title: Optimize For Latency
          description: If True, jobs will be processed with a higher throughput and priority at a higher cost. Defaults to False.
          default: false
        array_extract:
          type: boolean
          title: Array Extract
          description: If True, use array extraction.
          default: false
        deep_extract:
          type: boolean
          title: Deep Extract
          description: If True, use Deep Extract, an agentic extraction mode that iteratively refines its output to achieve near-perfect accuracy. Best for complex documents where accuracy is critical.
          default: false
        citations:
          $ref: '#/components/schemas/Citations'
          description: The citations to use for the extraction.
          default:
            enabled: false
            numerical_confidence: true
      type: object
      title: ExtractSettings
    TextAgentic:
      properties:
        scope:
          type: string
          title: Scope
          enum:
          - text
        prompt:
          type: string
          nullable: true
          title: Prompt
          description: 'Custom instructions for agentic text. Note: This only applies to form regions (key-value).'
      type: object
      required:
      - scope
      title: TextAgentic
    Instructions:
      properties:
        schema:
          title: Schema
          description: The JSON schema to use for the extraction.
          default: {}
        system_prompt:
          type: string
          title: System Prompt
          description: The system prompt to use for the extraction.
          default: Be precise and thorough.
      type: object
      title: Instructions
    AsyncExtractConfig:
      properties:
        async:
          $ref: '#/components/schemas/config__v3__AsyncConfig'
          description: The configuration options for asynchronous processing (default synchronous).
          default:
            priority: false
        input:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          - $ref: '#/components/schemas/UploadResponse'
          title: Input
          description: "For parse/split/extract pipelines, the URL of the document to be processed. You can provide one of the following:\n            1. A publicly available URL\n            2. A presigned S3 URL\n            3. A reducto:// prefixed URL obtained from the /upload endpoint after directly uploading a document\n            4. A jobid:// prefixed URL obtained from a previous /parse invocation\n            5. A list of URLs (for multi-document pipelines, V3 API only)\n\n            For edit pipelines, this should be a string containing the edit instructions "
        parsing:
          $ref: '#/components/schemas/ParseOptions'
          description: The configuration options for parsing the document. If you are passing in a jobid:// URL for the file, then this configuration will be ignored.
          default:
            enhance:
              agentic: []
              intelligent_ordering: false
              summarize_figures: true
            retrieval:
              chunking:
                chunk_mode: disabled
                chunk_overlap: 0
              embedding_optimized: false
              filter_blocks: []
            formatting:
              add_page_markers: false
              include: []
              merge_tables: false
              table_output_format: dynamic
            spreadsheet:
              clustering: accurate
              exclude: []
              include: []
              split_large_tables:
                enabled: true
                size: 50
            settings:
              embed_pdf_metadata: false
              embed_pdf_metadata_dpi: 100
              extraction_mode: hybrid
              force_url_result: false
              hybrid_vpc: {}
              ocr_system: standard
              persist_results: false
              return_images: []
              return_ocr_data: false
        instructions:
          $ref: '#/components/schemas/Instructions'
          description: The instructions to use for the extraction.
          default:
            schema: {}
            system_prompt: Be precise and thorough.
        settings:
          $ref: '#/components/schemas/ExtractSettings'
          description: The settings to use for the extraction.
          default:
            include_images: false
            optimize_for_latency: false
            array_extract: false
            deep_extract: false
            citations:
              enabled: false
              numerical_confidence: true
      type: object
      required:
      - input
      title: AsyncExtractConfig
    Retrieval:
      properties:
        chunking:
          $ref: '#/components/schemas/Chunking'
          default:
            chunk_mode: disabled
            chunk_overlap: 0
        filter_blocks:
          items:
            type: string
            enum:
            - Header
            - Footer
            - Title
            - Section Header
            - Page Number
            - List Item
            - Figure
            - Table
            - Key Value
            - Text
            - Comment
            - Signature
          type: array
          title: Filter Blocks
          description: A list of block types to filter out from 'content' and 'embed' fields. By default, no blocks are filtered.
          default: []
        embedding_optimized:
          type: boolean
          title: Embedding Optimized
          description: If True, use embedding optimized mode. Defaults to False.
          default: false
      type: object
      title: Retrieval
    PageRange:
      properties:
        start:
          type: integer
          nullable: true
          title: Start
          description: The page number to start processing from (1-indexed).
        end:
          type: integer
          nullable: true
          title: End
          description: The page number to stop processing at (1-indexed).
      type: object
      title: PageRange
    config__v3__AsyncConfig:
      properties:
        metadata:
          title: Metadata
          description: JSON metadata included in webhook request body. Defaults to None.
        priority:
          type: boolean
          title: Priority
          description: If True, attempts to process the job with priority if the user has priority processing budget available; by default, sync jobs are prioritized above async jobs.
          default: false
        webhook:
          anyOf:
          - $ref: '#/components/schemas/SvixWebhookConfig'
          - $ref: '#/components/schemas/DirectWebhookConfig'
          title: Webhook
          description: The webhook configuration for the asynchronous processing.
          nullable: true
      type: object
      title: AsyncConfig
    Settings:
      properties:
        ocr_system:
          type: string
          enum:
          - standard
          - legacy
          title: Ocr System
          description: Standard is our best multilingual OCR system. Legacy only supports germanic languages and is available for backwards compatibility.
          default: standard
        extraction_mode:
          type: string
          enum:
          - ocr
          - hybrid
          title: Extraction Mode
          description: The mode to use for text extraction from PDFs. OCR mode uses optical character recognition only. Hybrid mode combines OCR with embedded PDF text for best accuracy (default).
          default: hybrid
        force_url_result:
          type: boolean
          title: Force Url Result
          description: Force the result to be returned in URL form.
          default: false
        force_file_extension:
          type: string
          nullable: true
          title: Force File Extension
          description: Force the URL to be downloaded as a specific file extension (e.g. `.png`).
        return_ocr_data:
          type: boolean
          title: Return Ocr Data
          description: If True, return OCR data in the result. Defaults to False.
          default: false
        return_images:
          items:
            type: string
            enum:
            - figure
            - table
            - page
          type: array
          title: Return Images
          description: Whether to return images for the specified block types. 'page' returns full page images. By default, no images are returned.
          default: []
        embed_pdf_metadata:
          type: boolean
          title: Embed Pdf Metadata
          description: If True, embed OCR metadata into the returned PDF. Defaults to False.
          default: false
        embed_pdf_metadata_dpi:
          type: integer
          maximum: 250
          minimum: 50
          title: Embed Pdf Metadata Dpi
          description: Render DPI used when rasterizing the source PDF before embedding the OCR text layer (only applies when ``embed_pdf_metadata`` is True). Lower values produce dramatically smaller output PDFs; higher values preserve more detail when zoomed past 200%. Defaults to 100 (good for on-screen viewing); raise toward the source scan DPI for crisper output. Min 50, max 250.
          default: 100
        persist_results:
          type: boolean
          title: Persist Results
          description: If True, persist the results indefinitely. Defaults to False.
          default: false
        tenant_throttling:
          $ref: '#/components/schemas/TenantThrottling'
          nullable: true
          description: Per-tenant throttling for multi-tenant applications. Tag each request with your tenant's id to bound how much of your account's concurrency a single tenant can consume. Account-level throttles still apply.
        timeout:
          type: number
          nullable: true
          title: Timeout
          description: The timeout for the job in seconds.
        page_range:
          anyOf:
          - $ref: '#/components/schemas/PageRange'
          - items:
              $ref: '#/components/schemas/PageRange'
            type: array
          - items:
              type: integer
            type: array
          - items:
              type: string
            type: array
          title: Page Range
          description: The page range to process (1-indexed). By default, the entire document is processed. For spreadsheets, you can also provide a list of sheet names.
          nullable: true
        document_password:
          type: string
          nullable: true
          title: Document Password
          description: Password to decrypt password-protected documents.
        hybrid_vpc:
          $ref: '#/components/schemas/HybridVpcSettings'
          description: Hybrid VPC request-scoped settings.
          default: {}
      type: object
      title: Settings
    DirectWebhookConfig:
      properties:
        mode:
          type: string
          title: Mode
          default: direct
          enum:
          - direct
        url:
          type: string
          title: Url
      type: object
      required:
      - url
      title: DirectWebhookConfig
    TableAgentic:
      properties:
        scope:
          type: string
          title: Scope
          enum:
          - table
        prompt:
          type: string
          nullable: true
          title: Prompt
          description: Custom prompt for table agentic.
        mode:
          type: string
          enum:
          - default
          - auto
          - max
          title: Mode
          description: 'Mode for table agentic: ''default'' selectively applies enrichment only to tables likely to benefit, and ''max'' runs enrichment on all tables.'
          default: default
      type: object
      required:
      - scope
      title: TableAgentic
    Spreadsheet:
      properties:
        split_large_tables:
          $ref: '#/components/schemas/SplitLargeTables'
          default:
            enabled: true
            size: 50
        include:
          items:
            type: string
            enum:
            - cell_colors
            - formula
            - dropdowns
          type: array
          title: Include
          description: Whether to include cell color, formula, and dropdown information in the output.
          default: []
        clustering:
          type: string
          enum:
          - accurate
          - fast
          - disabled
          title: Clustering
          description: In a spreadsheet with different tables inside, we enable splitting up the tables by default. Accurate mode applies more powerful models for superior accuracy, at 5× the default per-cell rate. Disabling will register as one large table.
          default: accurate
        exclude:
          items:
            type: string
            enum:
            - hidden_sheets
            - hidden_rows
            - hidden_cols
            - styling
            - spreadsheet_images
          type: array
          title: Exclude
          description: Whether to exclude hidden sheets, rows, or columns in the output.
          default: []
        max_cell_count:
          type: integer
          minimum: 1
          nullable: true
          title: Max Cell Count
          description: Maximum total non-empty cells allowed across all sheets. If exceeded, the request is rejected with a 422 error. Set to null to disable the limit. Defaults to null.
      type: object
      title: Spreadsheet
    SvixWebhookConfig:
      properties:
        mode:
          type: string
          title: Mode
          default: svix
          enum:
          - svix
        channels:
          items:
            type: string
          type: array
          title: Channels
          description: A list of Svix channels the message will be delivered down, omit to send to all channels.
      type: object
      title: SvixWebhookConfig
    ParseOptions:
      properties:
        enhance:
          $ref: '#/components/schemas/Enhance'
          default:
            agentic: []
            summarize_figures: true
            intelligent_ordering: false
        retrieval:
          $ref: '#/components/schemas/Retrieval'
          default:
            chunking:
              chunk_mode: disabled
              chunk_overlap: 0
            filter_blocks: []
            embedding_optimized: false
        formatting:
          $ref: '#/components/schemas/Formatting'
          default:
            add_page_markers: false
            table_output_format: dynamic
            merge_tables: false
            include: []
        spreadsheet:
          $ref: '#/components/schemas/Spreadsheet'
          default:
            split_large_tables:
              enabled: true
              size: 50
            include: []
            clustering: accurate
            exclude: []
        settings:
          $ref: '#/components/schemas/Settings'
          default:
            ocr_system: standard
            extraction_mode: hybrid
            force_url_result: false
            return_ocr_data: false
            return_images: []
            embed_pdf_metadata: false
            embed_pdf_metadata_dpi: 100
            persist_results: false
            hybrid_vpc: {}
      type: object
      title: ParseOptions
    Citations:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: If True, include citations in the extraction.
          default: false
        numerical_confidence:
          type: boolean
          title: Numerical Confidence
          description: If True, enable numeric citation confidence scores. Defaults to True.
          default: true
      type: object
      title: Citations
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the Authorization header.