> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Extract Document
Submit a uploaded file, an internet-reachable URL, or any kind of raw text for document parsing. If you have configured a webhook,
we will notify you when the job is complete, be it a success or a failure.
Once submitted, the API will return a parse response with a `parse_id` field. You can query the status and results of the parse operation
with the [Get Parse Result](./get) endpoint.
## Using a schema
For this operation, you must provide one or more schemas to guide the extraction process. The schema must be in the form of a JSON Schema object.
The JSON Schema object can be provided in the `structured_extraction_options` array, which can contain multiple objects.
Known limitations include:
* The schema can only be at most 5 levels deep
* Root level fields must be objects
Page Classification labels can be combined
with structured extraction, to make the API perform structured extraction on a subset
of pages.
## Accepted input types
This endpoint accepts three input types via the request body:
| Field | Description |
| ---------- | ---------------------------------------------------------------------------------- |
| `file_id` | ID of a file previously uploaded to Tensorlake |
| `file_url` | Publicly accessible URL of a file |
| `raw_text` | Raw text content (e.g. Markdown), submitted inline with `mime_type: text/markdown` |
If you're iterating on an extraction schema, you can run OCR once, upload the Markdown output as a file, and reuse the resulting `file_id` for every subsequent extraction call — paying only for extraction tokens, not document processing.
## OpenAPI
````yaml post /documents/v2/extract
openapi: 3.1.0
info:
title: Tensorlake API
description: >-
Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
Workflows
license:
name: ''
version: 0.1.0
servers:
- url: https://api.tensorlake.ai/
security:
- bearerAuth: []
tags:
- name: Tensorlake Cloud API
description: >-
Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
Workflows
paths:
/documents/v2/extract:
post:
tags:
- extract
operationId: post_extract
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractRequest'
required: true
responses:
'200':
description: Created parse job details
content:
application/json:
schema:
$ref: '#/components/schemas/ParseCreatedResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized. Invalid or missing credentials
'403':
description: Forbidden. You do not have permission to access this resource
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'422':
description: Invalid properties in request body
content:
text/plain: {}
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
ExtractRequest:
allOf:
- $ref: '#/components/schemas/RequestFileInfo'
- $ref: '#/components/schemas/ExtractionRequestConfiguration'
- type: object
properties:
labels:
type:
- object
- 'null'
description: >-
Additional metadata to identify the extraction request. The
labels are
returned in the extraction response.
additionalProperties: {}
propertyNames:
type: string
example:
priority: high
source: email
ParseCreatedResponse:
type: object
required:
- parse_id
- created_at
properties:
parse_id:
type: string
description: >-
The unique identifier for the parse job
This is the ID that can be used to track the status of the parse
job.
Used in the `GET /documents/v2/parse/{parse_id}` endpoint to
retrieve
the status and results of the parse job.
created_at:
type: string
description: |-
The creation date and time of the parse job.
The date is in RFC 3339 format.
ApiError:
type: object
required:
- message
- code
- timestamp
properties:
message:
type: string
description: A human-readable error message
code:
$ref: '#/components/schemas/ApiErrorCode'
description: The error code, which can be used to programmatically handle errors
timestamp:
type: integer
format: int64
description: Millis since Unix epoch; easy to parse in every language
trace_id:
type:
- string
- 'null'
description: Optional request correlation-id for distributed tracing
details:
description: Optional field-level validation errors, etc.
RequestFileInfo:
allOf:
- type: object
properties:
page_range:
type: string
description: >-
Comma-separated list of page numbers or ranges to parse (e.g.,
'1,2,3-5'). Default: all pages.
examples:
- 1-5,8,10
file_name:
type: string
description: Name of the file. Only populated when using file_id.
examples:
- document.pdf
- oneOf:
- type: object
title: file_id
required:
- file_id
properties:
file_id:
type: string
description: >-
ID of the file previously uploaded to Tensorlake. Has
tensorlake- (V1) or file_ (V2) prefix.
examples:
- file_abc123xyz
mime_type:
type: string
enum:
- application/pdf
- >-
application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/msword
- >-
application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.ms-powerpoint
- application/vnd.apple.keynote
- image/jpeg
- image/tiff
- text/plain
- text/html
- text/markdown
- text/x-markdown
- >-
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/vnd.ms-excel.sheet.macroenabled.12
- application/vnd.ms-excel
- text/xml
- text/csv
- image/png
- text/rtf
- application/rtf
- application/octet-stream
- application/pkcs7-mime
- application/x-pkcs7-mime
- application/pkcs7-signature
- type: object
title: file_url
required:
- file_url
properties:
file_url:
type: string
format: uri-template
description: >-
External URL of the file to parse. Must be publicly
accessible.
examples:
- >-
https://pub-226479de18b2493f96b64c6674705dd8.r2.dev/real-estate-purchase-all-signed.pdf
mime_type:
type: string
enum:
- application/pdf
- >-
application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/msword
- >-
application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.ms-powerpoint
- application/vnd.apple.keynote
- image/jpeg
- image/tiff
- text/plain
- text/html
- text/markdown
- text/x-markdown
- >-
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/vnd.ms-excel.sheet.macroenabled.12
- application/vnd.ms-excel
- text/xml
- text/csv
- image/png
- text/rtf
- application/rtf
- application/octet-stream
- application/pkcs7-mime
- application/x-pkcs7-mime
- application/pkcs7-signature
- type: object
title: raw_text
required:
- raw_text
- mime_type
properties:
raw_text:
type: string
description: The raw text content to parse.
examples:
- This is the document content...
mime_type:
type: string
enum:
- application/pdf
- >-
application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/msword
- >-
application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.ms-powerpoint
- application/vnd.apple.keynote
- image/jpeg
- image/tiff
- text/plain
- text/html
- text/markdown
- text/x-markdown
- >-
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/vnd.ms-excel.sheet.macroenabled.12
- application/vnd.ms-excel
- text/xml
- text/csv
- image/png
- text/rtf
- application/rtf
- application/octet-stream
- application/pkcs7-mime
- application/x-pkcs7-mime
- application/pkcs7-signature
description: 'File source - must be exactly one of: file_id, file_url, or raw_text'
ExtractionRequestConfiguration:
type: object
properties:
structured_extraction_options:
type: array
items:
$ref: '#/components/schemas/StructuredExtractionOptions'
description: >-
The properties of this object define the configuration for
structured
data extraction.
If this object is present, the API will perform structured data
extraction on the document.
additionalProperties: false
ApiErrorCode:
oneOf:
- type: string
enum:
- QUOTA_EXCEEDED
- type: string
enum:
- INVALID_JSON_SCHEMA
- type: string
enum:
- INVALID_CONFIGURATION
- type: string
enum:
- INVALID_PAGE_CLASSIFICATION
- type: string
enum:
- ENTITY_NOT_FOUND
- type: string
enum:
- ENTITY_ALREADY_EXISTS
- type: string
enum:
- INVALID_FILE
- type: string
enum:
- INVALID_PAGE_RANGE
- type: string
enum:
- INVALID_MIME_TYPE
- type: string
enum:
- INVALID_DATASET_NAME
- type: string
enum:
- INVALID_JOB_STATE
- type: string
enum:
- INTERNAL_ERROR
- type: string
enum:
- INVALID_MULTIPART
- type: string
enum:
- MULTIPART_STREAM_END
- type: string
enum:
- CLIENT_DISCONNECT
- type: string
enum:
- INVALID_ID
- type: object
required:
- INVALID_QUERY_PARAMS
properties:
INVALID_QUERY_PARAMS:
type: object
required:
- property
properties:
property:
type: string
message:
type:
- string
- 'null'
StructuredExtractionOptions:
type: object
required:
- schema_name
- json_schema
properties:
schema_name:
type: string
description: >-
The name of the schema. This is used to tag the structured data
output
with a name in the response.
json_schema:
description: >-
The JSON schema to guide structured data extraction from the file.
This schema should be a valid JSON schema that defines the structure
of
the data to be extracted.
The API supports a subset of the JSON schema specification.
This value must be provided if `structured_extraction` is present in
the
request.
skip_ocr:
type: boolean
description: >-
Boolean flag to skip converting the document blob to OCR text before
structured data extraction.
If set to `true`, the API will skip the OCR step and directly
extract
structured data from the document.
The default is `false`.
prompt:
type:
- string
- 'null'
description: |-
The prompt to use for structured data extraction.
If not provided, the default prompt will be used.
model_provider:
$ref: '#/components/schemas/Model'
description: >-
The model provider to use for structured data extraction.
The default is `tensorlake`, which uses our private model, and runs
on
our servers.
partition_strategy:
$ref: '#/components/schemas/PartitionStrategy'
description: >-
Strategy to partition the document before structured data
extraction.
The API will return one structured data object per partition. This
is
useful when you want to extract certain fields from every page.
Options -
* `None`(*default*) - no partitioning is applied.
* `Page` - partition the document into pages.
* `Section` - partition the document into sections.
A section is defined as a group of text blocks that are visually
separated from other text blocks by whitespace or other visual
elements.
* `Fragment` - partition the document by fragments.
A fragment is defined as a group of text blocks, images, tables,
etc.
that are visually grouped together.
* `Patterns` - partition the document by custom patterns.
This requires providing start_patterns and end_patterns to define
the
custom patterns. Patterns are defined as strings specific to the
document content. The start_patterns and end_patterns are used to
identify the beginning and end of each partition.
page_classes:
type:
- array
- 'null'
items:
type: string
description: |-
Filter the pages of the document to be used for structured data
extraction by providing a list of page classes.
The default is `None`, which means all pages will be used.
provide_citations:
type:
- boolean
- 'null'
description: |-
Flag to enable visual citations in the structured data output.
It returns the bounding boxes of the coordinates of the document
where the structured data was extracted from.
The default is `false`.
additionalProperties: false
Model:
type: string
enum:
- tensorlake
- gemini3
- sonnet
- gpt4o_mini
PartitionStrategy:
oneOf:
- type: string
title: none
description: |-
No partitioning is applied. The entire document is used for
structured data extraction.
enum:
- none
- type: string
title: page
description: |-
Partition the document into pages. Each page is used for structured
data extraction separately.
enum:
- page
- type: string
title: section
description: |-
Partition the document into sections. Each section is used for
structured data extraction separately.
A section is defined as a group of text blocks that are visually
separated from other text blocks by whitespace or other visual
elements.
enum:
- section
- type: string
title: fragment
description: >-
Partition the document by fragments. Each fragment is used for
structured data extraction separately.
A fragment is defined as a group of text blocks, images, tables,
etc.
that are visually grouped together.
enum:
- fragment
- type: object
title: patterns
description: >-
Partition the document by custom patterns. Each pattern match is
used
for structured data extraction separately.
This requires providing start_patterns and end_patterns to define
the custom patterns.
Patterns are defined as strings specific to the document content.
The start_patterns and end_patterns are used to identify the
beginning and end of each partition.
required:
- patterns
properties:
patterns:
type: object
description: >-
Partition the document by custom patterns. Each pattern match is
used
for structured data extraction separately.
This requires providing start_patterns and end_patterns to
define
the custom patterns.
Patterns are defined as strings specific to the document
content.
The start_patterns and end_patterns are used to identify the
beginning and end of each partition.
required:
- start_patterns
- end_patterns
properties:
start_patterns:
type: array
items:
type: string
end_patterns:
type: array
items:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````