# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kensho Extract Extractions API
  version: 1.0.0
extends: openapi/sp-global-extractions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/v3/extractions'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a document directly for structured extraction
      effect: write
      questions:
      - How do I send a PDF straight to Kensho Extract and get its titles, paragraphs and tables back?
      - Can I extract only certain pages of a document, like pages 1-5 and 7?
      - What is the largest file I can attach directly in a single extraction request?
      instructions:
      - text: Attach {file} directly and extract it as a {document_type} document with OCR set to {ocr} and enhanced tables {enhanced_table_extraction}.
        slots:
          file: requestBody.file
          document_type: requestBody.document_type
          ocr: requestBody.ocr
          enhanced_table_extraction: requestBody.enhanced_table_extraction
      - text: Upload {file} in the request body and extract only pages {pages}, also returning figures ({figure_extraction}).
        slots:
          file: requestBody.file
          pages: requestBody.pages
          figure_extraction: requestBody.figure_extraction
      - text: Send {file} for extraction tagged with my own document ID {document_id} at {priority} priority, including image locations ({include_images}).
        slots:
          file: requestBody.file
          document_id: requestBody.document_id
          priority: requestBody.priority
          include_images: requestBody.include_images
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/extractions/upload-url'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a pre-signed URL to upload a document for extraction
      effect: write
      questions:
      - Can I get a pre-signed upload link instead of attaching my document to the extraction request?
      - Which settings do I have to choose before I receive a pre-signed URL for my document?
      - Is there a way to cap the total number of pages extracted from a document I upload by link?
      instructions:
      - text: Get a pre-signed upload URL for a {document_type} document as {output_format}, OCR {ocr}, enhanced tables {enhanced_table_extraction}.
        slots:
          document_type: requestBody.document_type
          output_format: requestBody.output_format
          ocr: requestBody.ocr
          enhanced_table_extraction: requestBody.enhanced_table_extraction
      - text: Get an upload link for a document I'll send separately, extracting at most {num_pages_to_extract} pages.
        slots:
          num_pages_to_extract: requestBody.num_pages_to_extract
      - text: Reserve a pre-signed upload URL for document {document_id} at {priority} priority.
        slots:
          document_id: requestBody.document_id
          priority: requestBody.priority
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/extractions/upload-complete'].put
  update:
    x-apievangelist-phrasing:
      intent: Start extraction after uploading to the pre-signed URL
      effect: write
      questions:
      - Why hasn't extraction started even though my file finished uploading to the pre-signed link?
      - What do I call to tell the service my presigned upload is done?
      instructions:
      - text: Mark the upload for extraction request {request_id} as complete so processing begins.
        slots:
          request_id: requestBody.request_id
      - text: I've finished uploading to the pre-signed URL for {request_id}; kick off the extraction.
        slots:
          request_id: requestBody.request_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/extractions/{request_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve the extracted document for a request
      effect: read
      questions:
      - Where do I fetch the structured output once my document has been extracted?
      - Can I get the extracted content back with character offsets or element locations included?
      instructions:
      - text: Get the extracted document content for request {request_id}.
        slots:
          request_id: path.request_id
      - text: Return the extraction result for {request_id} inline as {output_format}.
        slots:
          request_id: path.request_id
          output_format: query.output_format
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/extractions/download-url/{request_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a download link for an extracted document
      effect: read
      questions:
      - Is there a file download link for a finished extraction rather than the inline response?
      - Which field holds the URL I use to download my extracted output?
      instructions:
      - text: Give me the output_url to download the extracted document for request {request_id}.
        slots:
          request_id: path.request_id
      - text: Fetch the download link for the finished extraction {request_id}.
        slots:
          request_id: path.request_id
      method: generated
      generated: '2026-10-01'