S&P Global

Kensho Extract API

Transforms unstructured PDF and image documents into machine-readable JSON, identifying titles, subtitles, paragraphs, tables, and footers in natural reading order. Optional OCR and Figure Extraction (FigEx). REST API at extract.kensho.com with asynchronous extractions and presigned upload/download URLs.

Documentation GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /v3/extractions Submit a document directly for structured extraction · Create extractions #

Ask an LLM

“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?”

Tell an agent

Attach {file} directly and extract it as a {document_type} document with OCR set to {ocr} and enhanced tables {enhanced_table_extraction}.

Upload {file} in the request body and extract only pages {pages}, also returning figures ({figure_extraction}).

POST /v3/extractions/upload-url Get a pre-signed URL to upload a document for extraction · Upload URL To Submit A Document For Extraction #

Ask an LLM

“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?”

Tell an agent

Get a pre-signed upload URL for a {document_type} document as {output_format}, OCR {ocr}, enhanced tables {enhanced_table_extraction}.

Get an upload link for a document I'll send separately, extracting at most {num_pages_to_extract} pages.

PUT /v3/extractions/upload-complete Start extraction after uploading to the pre-signed URL · Mark The Upload As Complete To Start Extraction #

Ask an LLM

“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?”

Tell an agent

Mark the upload for extraction request {request_id} as complete so processing begins.

I've finished uploading to the pre-signed URL for {request_id}; kick off the extraction.

GET /v3/extractions/{request_id} Retrieve the extracted document for a request · Get extractions by request id #

Ask an LLM

“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?”

Tell an agent

Get the extracted document content for request {request_id}.

Return the extraction result for {request_id} inline as {output_format}.

GET /v3/extractions/download-url/{request_id} Get a download link for an extracted document · Retrieve The Extracted Document's Download URL #

Ask an LLM

“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?”

Tell an agent

Give me the output_url to download the extracted document for request {request_id}.

Fetch the download link for the finished extraction {request_id}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/sp-global:kensho-extract-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  version: 3.0.0
  title: Kensho Extract Extractions API
  description: Kensho Extract allows users to quickly transform their unstructured documents into a machine-readable format that identifies titles, subtitles, paragraphs, tables, and footers detected within the document in their natural reading order.
servers:
- url: https://extract.kensho.com/
tags:
- name: Extractions
paths:
  /v3/extractions:
    post:
      description: Submit a document for extraction
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - file
              - document_type
              - ocr
              - enhanced_table_extraction
              type: object
              properties:
                file:
                  type: string
                  description: The document to extract. The maximum file size is 100MB.
                  format: binary
                document_type:
                  type: string
                  description: 'The output document format. Kensho Extract offers three document types: `hierarchical`, `hierarchical_v2`, and `general`.

                    Please refer to our [overview page](home) for a detailed breakdown of which model will provide the most optimal output for your use case.

                    '
                ocr:
                  type: string
                  description: 'Identifies whether the document is scanned or is a native pdf. This must be `true` or `false`.

                    See the [OCR](ocr) page for more information.

                    '
                enhanced_table_extraction:
                  type: string
                  description: 'Use our newest model to extract data from complex tables more accurately than ever.                     This must be `true` or `false`.

                    '
                figure_extraction:
                  type: string
                  description: 'Use our newest model to extract data from figures.                     This must be `true` or `false`.

                    See the [Figure Extraction](figex) page for more information.

                    '
                include_images:
                  type: string
                  description: 'Whether to return the locations of images. This must be `true` or `false`.

                    '
                include_relations:
                  type: string
                  description: 'Whether to return the relations between items. This must be `true` or `false`.

                    '
                document_id:
                  type: string
                  description: A custom document identifier.
                priority:
                  type: string
                  enum:
                  - low
                  description: The priority level. Anything besides `low` will be considered `high` priority.
                pages:
                  type: string
                  description: 'This specifies the pages to extract. Page numbers start at 1. Format: `1-5,7,11,14-16`.'
                return_absolute_pdf_page_numbers:
                  type: boolean
                  default: false
                  description: 'Whether to return absolute PDF page numbers in the output. Absolute PDF page numbers refer to the original page numbers requested, while relative page numbers start at 0 and increment by 1 for each page requested

                    '
                output_format:
                  type: string
                  description: 'This can be `structured_document`, `structured_document_with_locations`, or `structured_document_with_char_offsets`. It determines if the response format will include location bounding box information.

                    <br>

                    Including this parameter requires making a call to `/v3/extractions/download-url/{request_id}` to obtain a URL for downloading the document from AWS.

                    '
      responses:
        '200':
          description: The request was successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    format: uuid
        '400':
          description: This can be any combination of the required parameters are not provided, a parameter that is invalid, or if a specific pages is requested in the `pages` parameter and that page is not in the document. E.g., requesting page 57 for a 10 page document.
        '401':
          description: The authentication token is missing or invalid.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      summary: Create extractions
      x-summary-source: derived
      operationId: postV3Extractions
      x-operation-id-source: derived
  /v3/extractions/upload-url:
    post:
      summary: Upload URL To Submit A Document For Extraction
      description: Creates the request and returns a pre-signed upload URL to upload the document for extraction.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - output_format
              - document_type
              - ocr
              - enhanced_table_extraction
              type: object
              properties:
                output_format:
                  type: string
                  description: This can be `structured_document`, `structured_document_with_locations`, or `structured_document_with_char_offsets`. It determines if the extracted document format will include location bounding box information and character offsets.
                document_type:
                  type: string
                  description: 'The output document format. Kensho Extract offers three document types: `hierarchical`, `hierarchical_v2`, and `general`.

                    Please refer to our [overview page](home) for a detailed breakdown of which model will provide the most optimal output for your use case.

                    '
                ocr:
                  type: string
                  description: 'Identifies whether the document is scanned or is a native pdf. This must be `true` or `false`.

                    See the [OCR](ocr) page for more information.

                    '
                enhanced_table_extraction:
                  type: string
                  description: 'Use our newest model to extract data from complex tables more accurately than ever. This must be `true` or `false`.

                    '
                figure_extraction:
                  type: string
                  description: 'Use our newest model to extract data from figures. This must be `true` or `false`.

                    See the [Figure Extraction](figex) page for more information.

                    '
                document_id:
                  type: string
                  description: A custom document identifier.
                priority:
                  type: string
                  enum:
                  - low
                  description: The priority level. Anything besides `low` will be considered `high` priority.
                pages:
                  type: string
                  description: 'This specifies the pages to extract. Page numbers start at 1. Format: `1-5,7,11,14-16`.'
                num_pages_to_extract:
                  type: integer
                  description: This specifies the total number of pages to extract.
            encoding:
              file:
                contentType: application/pdf
        required: true
      responses:
        '200':
          description: The request was successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    format: uuid
                  upload_spec:
                    type: object
                    properties:
                      url:
                        type: string
                        description: The URL to POST the document upload to. Returns 204 on success. Refer to the AWS pre-signed URL documentation for detailed information on specific response codes and their meanings.
                      fields:
                        type: object
                        additionalProperties:
                          type: string
                        description: Fields required in the form data of the POST request for uploading the document to the `url`.
        '400':
          description: This can be any combination of the required parameters are not provided or parameter value is invalid.
        '401':
          description: The authentication token is missing or invalid.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      operationId: postV3ExtractionsUploadUrl
      x-operation-id-source: derived
  /v3/extractions/upload-complete:
    put:
      summary: Mark The Upload As Complete To Start Extraction
      description: Call this after the document has been uploaded to the pre-signed URL returned by `/v3/extractions/upload-url`. The extraction process will not begin until this endpoint is called.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - request_id
              type: object
              properties:
                request_id:
                  type: uuid
                  description: The request_id for the extraction.
        required: true
      responses:
        '204':
          description: The request was marked as uploaded successfully.
        '400':
          description: The request_id was not provided by the client, or was not created via `/v3/extractions/upload-url`.
        '401':
          description: The authentication token is missing or invalid.
        '404':
          description: The request_id or the uploaded document could not be found.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      operationId: putV3ExtractionsUploadComplete
      x-operation-id-source: derived
  /v3/extractions/{request_id}:
    get:
      description: Retrieve the extracted document
      parameters:
      - name: request_id
        in: path
        description: request uuid
        required: true
        schema:
          type: string
          format: uuid
      - name: output_format
        in: query
        description: This can be `structured_document`, `structured_document_with_locations`, or `structured_document_with_char_offsets`. It determines if the response format will include location bounding box information.
        required: false
        schema:
          type: string
          default: structured_document_with_locations
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - failed
                    - pending
                  error:
                    type: string
                  output:
                    type: object
                    $ref: '#/components/schemas/Output'
                  metadata:
                    type: object
                    properties: {}
        '400':
          description: 'The request_id was not provided by the client, or output_format was specified when the request was created.

            <br>

            If output_format was specified when the request was created, /v3/extractions/download-url/{request_id} must be called to get a pre-signed URL to retrieve the extracted output.

            '
        '401':
          description: The authentication token is missing or invalid.
        '404':
          description: The request_id could not be found.
        '405':
          description: The request is on a different API version than the POST request that created the request.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      summary: Get extractions by request id
      x-summary-source: derived
      operationId: getV3ExtractionsByRequestId
      x-operation-id-source: derived
  /v3/extractions/download-url/{request_id}:
    get:
      summary: Retrieve The Extracted Document's Download URL
      description: GET the `output_url` in the response to download the extracted document.
      parameters:
      - name: request_id
        in: path
        description: request uuid
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - failed
                    - pending
                    - awaiting_document_upload
                    - awaiting_document_upload_complete_notification
                  error:
                    type: string
                  output_url:
                    type: string
                  metadata:
                    type: object
                    properties: {}
        '400':
          description: The request_id was not provided by the client, or output_format was not specified when the request was created.
        '401':
          description: The authentication token is missing or invalid.
        '404':
          description: The request_id could not be found.
        '405':
          description: The request is on a different API version than the POST request that created the request, the document has not been uploaded, or /v3/extractions/upload-complete has not been called to marked the upload complete.
        default:
          description: An unexpected error occurred.
      security:
      - bearerAuth: []
      tags:
      - Extractions
      operationId: getV3ExtractionsDownloadUrlByRequestId
      x-operation-id-source: derived
components:
  schemas:
    Output:
      type: object
      properties:
        content_tree:
          type: object
          $ref: '#/components/schemas/ContentTree'
        annotations:
          type: object
          $ref: '#/components/schemas/Annotations'
      required:
      - content_tree
      - annotations
    Annotations:
      type: array
      description: Additional data about structure of the document that references text content nodes by their UIDs
      items:
        type: object
        description: Individual annotation
        properties:
          type:
            type: string
            description: Type of an annotation, (e.g. table structure / row header, etc.).
          content_uids:
            type: array
            description: Non-empty list of UIDs of content nodes corresponding to the annotation.
            items:
              type: string
            minItems: 1
          data:
            type: object
        required:
        - type
        - content_uids
    ContentTree:
      type: object
      properties:
        uid:
          type: string
          description: Identifier for a content node that is unique across all nodes in a document
        type:
          type: string
          description: Type of a content node, must be one of document|paragraph|H1|H2|table|table_cell|table_title
        content:
          type: string
          description: Text that corresponds to the content node (optional)
        children:
          type: array
          description: List of child content nodes (recursive)
          items:
            $ref: '#'
      required:
      - uid
      - type
      - content
      - children
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Kensho Extract API

Operations 5

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification