Appearance
Documents
Upload, search, and manage documents in the dataroom.
List documents
GET
/v1/documents
List the documents readable by the caller. By default the most recently updated
documents come first; pass sort=name to order alphabetically by name
(case-insensitive, A to Z).
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
folder_id
When set, only documents linked to this folder are returned.
limit
Type
integer
Default
50Maximum
200Minimum
1offset
Type
integer
Default
0Minimum
0sort
Result order. updated_at (default): most recently updated first. name: alphabetical by name, case-insensitive, A to Z.
Type
string
Valid values
"updated_at""name"Default
"updated_at"mine
When true, only documents created by the caller.
Type
boolean
Default
falseResponses
Successful Response
application/json
JSON "has_more": false, "items": [ { "char_count": 0, "chunking_complete": false, "chunking_stale": false, "content_preview": "", "created_at": "string", "created_by": "string", "created_by_name": "string", "embedding_complete": false, "embedding_stale": false, "folder_ids": [ "string" ], "has_preview_pdf": false, "has_stored_original": false, "id": "string", "import_source_provider": "string", "import_source_url": "string", "name": "string", "page_count": 0, "source_format": "string", "updated_at": "string", "updated_by": "string" } ], "total": 0, "total_pages": 0
{
}
Samples
Create Document
POST
/v1/documents
Upload a document. Use target_folder_id for shared, team, or personal folders. Omit target_folder_id to place in org personal folder.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
multipart/form-data
Valid values
"token""semantic"Default
"token"Chunk and embed after upload
Default
trueAny of
Any of
Minimum
0Destination folder. Omit for org personal folder.
Any of
Format
"uuid"Any of
Minimum
1Responses
Successful Response
application/json
JSON "char_count": 0, "chunking_complete": false, "chunking_stale": false, "content": "string", "content_preview": "", "created_at": "string", "created_by": "string", "created_by_name": "string", "embedding_complete": false, "embedding_stale": false, "folder_ids": [ "string" ], "has_preview_pdf": false, "has_stored_original": false, "id": "string", "import_source_provider": "string", "import_source_url": "string", "ingest_job_id": "string", "name": "string", "page_count": 0, "parse_job_id": "string", "source_format": "string", "updated_at": "string", "updated_by": "string"
{
}
Samples
Get one chunk
GET
/v1/documents/chunks/{chunk_id}
Fetch a single chunk by id, for showing the passage behind a citation.
Authorized through the parent document.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
chunk_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "chunk_id": "string", "chunk_index": 0, "content": "string", "content_offset": 0, "document_id": "string", "document_name": "string", "images": [ { "bbox": [ 0, 0, 0, 0 ], "id": "string", "kind": "string", "page": 0, "text_source": "string" } ], "page_number": 0, "visibility": "string"
{
}
Samples
Import Documents From Connector
POST
/v1/documents/import-from-connector
Import one or more remote files via an org connector connection.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
Connector connection to import through, from GET /connectors/connections.
Format
"uuid"Files to import, at most 50 per request. Each is imported by its own job.
Identifier the provider gave the file when you browsed the connection: an item id for Google Drive, OneDrive and SharePoint, a path for Dropbox, an object key for S3.
Folder on the provider holding the file, such as /Projects. Joined with name when file_id is not a full path.
MIME type the provider reported for the file when you browsed the connection. When provided, an unimportable file is rejected in this response instead of failing later in its import job.
File name within folder, and the display name the imported document is given.
Same value as file_id, named for providers that address files by path. Send one or the other; sending both requires them to be equal.
Folder on the provider to read every file from, such as /Projects. A folder set on an individual file overrides this.
Any of
Min Length
1Provider folders to import whole, each as the path that browsing the connection returned for it. Every importable file inside, including subfolders, is imported; files that can't be imported come back as error results. Not subject to the 50-file limit.
EchoMode folder UUID where imported documents are placed.
Any of
Format
"uuid"Responses
Successful Response
application/json
JSON "results": [ { "document_id": "string", "error": "string", "file_id": "string", "job_id": "string", "name": "string", "status": "string" } ]
{
}
Samples
Import Document From Url
POST
/v1/documents/import-from-url
Import from a URL as a background job; poll the returned job id.
depth=1 imports one file or page: Google Drive, Dropbox and S3 links download through
the org connector, file URLs are fetched directly, other pages are scraped.
depth above 1 crawls linked pages. A single page already crawled returns
job_id null with already_crawled and the existing document.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
1 imports the single file or page; above 1 crawls linked pages.
Default
1Maximum
4Minimum
1Destination folder. Omit for org personal folder.
Any of
Format
"uuid"Display name for a single-file or single-page import.
Any of
Min Length
1Default
truehttp(s) page or file URL, or a Google Drive, Dropbox or S3 link.
Min Length
1Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Samples
Create a document from pasted text
POST
/v1/documents/paste
Create a document from pasted text rather than an uploaded file. The text is
chunked and embedded the same way an upload is.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
Min Length
1Valid values
"text""markdown""code"Destination folder. Omit for org personal folder.
Any of
Format
"uuid"Responses
Successful Response
application/json
JSON "char_count": 0, "chunking_complete": false, "chunking_stale": false, "content": "string", "content_preview": "", "created_at": "string", "created_by": "string", "created_by_name": "string", "embedding_complete": false, "embedding_stale": false, "folder_ids": [ "string" ], "has_preview_pdf": false, "has_stored_original": false, "id": "string", "import_source_provider": "string", "import_source_url": "string", "ingest_job_id": "string", "name": "string", "page_count": 0, "parse_job_id": "string", "source_format": "string", "updated_at": "string", "updated_by": "string"
{
}
Samples
Documents with image text to check
GET
/v1/documents/review-needed
Documents the caller can edit that have images whose text may have been misread,
most recently flagged first. An image leaves the list once someone confirms or
corrects it with PATCH /documents/{document_id}/images/{image_id}.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
limit
Type
integer
Default
50Maximum
200Minimum
1Responses
Successful Response
application/json
JSON "items": [ { "document_id": "string", "flagged_at": "string", "images": 0, "name": "string" } ]
{
}
Samples
Search documents
GET
/v1/documents/search
Full-text search across readable documents, combining document-name matching
with ranked search over chunk content. Results are documents, not chunks.
By default the best matches come first; pass sort=name to order the same
matches alphabetically by name (case-insensitive, A to Z), or sort=updated_at
to order them by most recently updated first.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
q
Type
string
Default
""Max Length
200Min Length
1limit
Type
integer
Default
20Maximum
50Minimum
1offset
Type
integer
Default
0Minimum
0sort
Result order. relevance (default): best match first. name: the same matches, alphabetical by name, case-insensitive, A to Z. updated_at: the same matches, most recently updated first.
Type
string
Valid values
"relevance""name""updated_at"Default
"relevance"Responses
Successful Response
application/json
JSON "items": [ { "char_count": 0, "content_preview": "", "created_at": "string", "created_by": "string", "folder_ids": [ "string" ], "id": "string", "name": "string", "page_count": 0, "rank": 0, "source_format": "string", "updated_at": "string" } ], "query": "string", "total": 0
{
}
Samples
Delete a document
DELETE
/v1/documents/{document_id}
Delete a document. It stops appearing in listings, search, and retrieval, and
stops being used to answer questions.
The document is marked deleted and its stored file is retained; its chunks and
embeddings are removed. Deleting the same document twice returns 404.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
Samples
Get a document
GET
/v1/documents/{document_id}
Get full document details, including its extracted content.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "char_count": 0, "chunking_complete": false, "chunking_stale": false, "content": "string", "content_preview": "", "created_at": "string", "created_by": "string", "created_by_name": "string", "embedding_complete": false, "embedding_stale": false, "folder_ids": [ "string" ], "has_preview_pdf": false, "has_stored_original": false, "id": "string", "import_source_provider": "string", "import_source_url": "string", "ingest_job_id": "string", "name": "string", "page_count": 0, "parse_job_id": "string", "source_format": "string", "updated_at": "string", "updated_by": "string"
{
}
Samples
Update a document
PATCH
/v1/documents/{document_id}
Rename the document, move it to another folder, or record its source URL.
Every field is optional; omitted fields are left alone.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Any of
Min Length
1Where the document came from, for citation and de-duplication.
Any of
Move the document into this folder. A document linked into several folders
gains this link instead of losing the others.
Any of
Format
"uuid"Responses
Successful Response
application/json
JSON "char_count": 0, "chunking_complete": false, "chunking_stale": false, "content": "string", "content_preview": "", "created_at": "string", "created_by": "string", "created_by_name": "string", "embedding_complete": false, "embedding_stale": false, "folder_ids": [ "string" ], "has_preview_pdf": false, "has_stored_original": false, "id": "string", "import_source_provider": "string", "import_source_url": "string", "ingest_job_id": "string", "name": "string", "page_count": 0, "parse_job_id": "string", "source_format": "string", "updated_at": "string", "updated_by": "string"
{
}
Samples
Check chunking progress
GET
/v1/documents/{document_id}/chunking-status
Whether the document has finished being split, and how many chunks exist.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "chunk_count": 0, "chunking_complete": true, "document_id": "string"
{
}
Samples
List a document's chunks
GET
/v1/documents/{document_id}/chunks
The pieces the document was split into for retrieval, in order, each with the
text that is searched and whether it is searchable yet.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "document_id": "string", "items": [ { "chunk_index": 0, "chunk_kind": "string", "content": "string", "contextual_text": "string", "embedded": true, "embedded_at": "string", "embedding_model": "string", "id": "string", "token_count": 0 } ]
{
}
Samples
Get a download URL
GET
/v1/documents/{document_id}/download-url
Time-limited URL for the original file. Available only while the upload is
still stored; check has_stored_original first.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "expires_in": 0, "url": "string"
{
}
Samples
Check embedding progress
GET
/v1/documents/{document_id}/embedding-status
Whether the document is searchable yet. Until every chunk is embedded, retrieval sees only part of it.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "chunks_embedded": 0, "chunks_total": 0, "document_id": "string", "embedding_complete": true
{
}
Samples
Stream the stored file
GET
/v1/documents/{document_id}/file
Stream the original bytes for inline preview, rather than redirecting to a
time-limited URL. Word uploads stream their PDF rendering when one exists.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
JSON
[
]
Samples
Replace the stored file
PUT
/v1/documents/{document_id}/file
Upload a new version of the document's file. Its chunks are discarded and,
unless ingest is false, it is chunked and embedded again with the given settings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Request Body
multipart/form-data
Valid values
"token""semantic"Default
"token"Default
trueAny of
Minimum
0Any of
Minimum
1Responses
Successful Response
application/json
JSON "char_count": 0, "chunking_complete": false, "chunking_stale": false, "content": "string", "content_preview": "", "created_at": "string", "created_by": "string", "created_by_name": "string", "embedding_complete": false, "embedding_stale": false, "folder_ids": [ "string" ], "has_preview_pdf": false, "has_stored_original": false, "id": "string", "import_source_provider": "string", "import_source_url": "string", "ingest_job_id": "string", "name": "string", "page_count": 0, "parse_job_id": "string", "source_format": "string", "updated_at": "string", "updated_by": "string"
{
}
Samples
Locate a passage on its page
GET
/v1/documents/{document_id}/highlight
Boxes covering the document text between start and end (character offsets into
the document's text, as citation spans give them), on the page the passage starts on.
Draw them over GET /documents/{document_id}/pages/{page}.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Query Parameters
start*
Type
Requiredinteger
Minimum
0end*
Type
Requiredinteger
Minimum
0Responses
Successful Response
application/json
JSON "boxes": [ { "x0": 0, "x1": 0, "y0": 0, "y1": 0 } ], "page": 0, "page_height": 0, "page_width": 0, "pages": [ { "height": 0, "width": 0 } ]
{
}
Samples
List a document's images
GET
/v1/documents/{document_id}/images
Images found in the document, in page order, with the text each one contributes.
Pass needs_review=true for the images whose text may be wrong and should be
checked by a person.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Query Parameters
needs_review
Responses
Successful Response
application/json
JSON "can_edit": true, "ingestion_mode": "string", "items": [ { "bbox": [ 0, 0, 0, 0 ], "editable": true, "id": "string", "kind": "string", "llm_model": "string", "needs_review": true, "ocr_confidence": 0, "ocr_text": "string", "page": 0, "review_items": [ { "box": [ 0, 0, 0, 0 ], "kind": "string", "note": "string", "ocr": "string", "text": "string" } ], "reviewed_at": "string", "text": "string", "text_boxes": [ { "box": [ 0, 0, 0, 0 ], "score": 0, "text": "string" } ], "text_source": "string" } ], "reingest_pending": "string"
{
}
Samples
Get an image from a document
GET
/v1/documents/{document_id}/images/{image_id}
A PNG of one image found in the document, cropped from its page. Chunk
responses list the images behind a passage under images.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"image_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
JSON
[
]
Samples
Correct or confirm an image's text
PATCH
/v1/documents/{document_id}/images/{image_id}
Send text to replace the image's text, or an empty body to confirm it is right.
Either way the image no longer needs review. A text change re-indexes the document.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"image_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Corrected text for the image. Omit to confirm the current text is right. A change re-indexes the document for search and answers.
Any of
Max Length
50000Min Length
1Responses
Successful Response
application/json
JSON "bbox": [ 0, 0, 0, 0 ], "editable": true, "id": "string", "kind": "string", "llm_model": "string", "needs_review": true, "ocr_confidence": 0, "ocr_text": "string", "page": 0, "review_items": [ { "box": [ 0, 0, 0, 0 ], "kind": "string", "note": "string", "ocr": "string", "text": "string" } ], "reviewed_at": "string", "text": "string", "text_boxes": [ { "box": [ 0, 0, 0, 0 ], "score": 0, "text": "string" } ], "text_source": "string"
{
}
Samples
List the folders a document is in
GET
/v1/documents/{document_id}/links
A document is readable exactly when one of these folders is readable by the
caller, so this is also the document's effective access list.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "document_id": "string", "links": [ { "folder_id": "string", "folder_name": "string" } ]
{
}
Samples
Link a document into a folder
POST
/v1/documents/{document_id}/links
Add the document to another folder. Linking into a more broadly shared folder
is rejected unless promote is set, since it would widen who can read it.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Format
"uuid"Default
falseResponses
Successful Response
application/json
JSON "char_count": 0, "chunking_complete": false, "chunking_stale": false, "content": "string", "content_preview": "", "created_at": "string", "created_by": "string", "created_by_name": "string", "embedding_complete": false, "embedding_stale": false, "folder_ids": [ "string" ], "has_preview_pdf": false, "has_stored_original": false, "id": "string", "import_source_provider": "string", "import_source_url": "string", "ingest_job_id": "string", "name": "string", "page_count": 0, "parse_job_id": "string", "source_format": "string", "updated_at": "string", "updated_by": "string"
{
}
Samples
Unlink a document from a folder
DELETE
/v1/documents/{document_id}/links/{folder_id}
Remove one folder link. The document itself is kept; removing its last link
leaves it reachable only by its owner.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"folder_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
Samples
List the size of every page
GET
/v1/documents/{document_id}/page-sizes
Page sizes of the document's PDF (the preview PDF for office files), for laying
out GET /documents/{document_id}/pages/{page} before the images load.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "pages": [ { "height": 0, "width": 0 } ]
{
}
Samples
List a PDF's text page by page
GET
/v1/documents/{document_id}/pages
The text used for search and answers, split by page, with the parts read from
images marked. Image text is the current text: a model's re-reading or a person's
correction replaces the OCR reading.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "available": true, "can_edit": true, "pages": [ { "height": 0, "page": 0, "passages": [ { "box": [ 0, 0, 0, 0 ], "end": 0, "image_id": "string", "kind": "string", "needs_review": true, "start": 0, "text_source": "string" } ], "reread_options": [ { "image_count": 0, "mode": "string" } ], "text": "string", "width": 0 } ]
{
}
Samples
Get a page of a PDF as an image
GET
/v1/documents/{document_id}/pages/{page}
A PNG of one page of the document's PDF (the preview PDF for office files).
scale is pixels per PDF unit.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"page*
Type
Requiredinteger
Query Parameters
scale
Pixels per PDF unit; large pages are capped.
Type
number
Default
2Maximum
3Minimum
1Responses
Successful Response
JSON
[
]
Samples
Correct a page's text
PATCH
/v1/documents/{document_id}/pages/{page}
Replaces one page's text in what search and answers use, keeps the history of the
change, and re-indexes the document. Image text left unchanged on the page stays
linked to its image.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"page*
Type
Requiredinteger
Request Body
application/json
The page's corrected text. Replaces the page's text for search and answers and re-indexes the document.
Max Length
200000Responses
Successful Response
application/json
JSON "height": 0, "page": 0, "passages": [ { "box": [ 0, 0, 0, 0 ], "end": 0, "image_id": "string", "kind": "string", "needs_review": true, "start": 0, "text_source": "string" } ], "reread_options": [ { "image_count": 0, "mode": "string" } ], "text": "string", "width": 0
{
}
Samples
Re-read a page's images with a model
POST
/v1/documents/{document_id}/pages/{page}/reread
hybrid re-reads the images on the page OCR was unsure of; llm re-reads every image
only OCR has read. The document is re-indexed afterwards. Images a person confirmed
or corrected are kept. Model reads count toward the uploader's inference limit.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"page*
Type
Requiredinteger
Request Body
application/json
Valid values
"hybrid""llm"Responses
Successful Response
application/json
JSON "document_id": "string", "ingestion_mode": "string", "job_id": "string"
{
}
Samples
Get the words on a page and where they are
GET
/v1/documents/{document_id}/pages/{page}/text
Words of the PDF's text and lines read from its images, with boxes in the same
coordinates as GET /documents/{document_id}/highlight, for laying selectable text
over GET /documents/{document_id}/pages/{page}. Empty when the page has no PDF.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"page*
Type
Requiredinteger
Responses
Successful Response
application/json
JSON "height": 0, "width": 0, "words": [ { "text": "string", "x0": 0, "x1": 0, "y0": 0, "y1": 0 } ]
{
}
Samples
Get a document's RAG config
GET
/v1/documents/{document_id}/rag-config
Get the retrieval configuration for a document: how it is split into chunks,
how queries search it, and how results are reranked.
chunking.method is token or semantic; chunking.target_tokens is the
target chunk size and chunking.overlap_tokens the overlap between adjacent
chunks. retrieval.mode is vector, word_match, or hybrid, with
retrieval.rrf_k controlling how smoothly hybrid blends the two rankings.
reranking.reranker_type is cross_encoder or llm, and reranking.top_k
is how many chunks survive reranking.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "config": { "chunking": { "method": "token", "overlap_tokens": 200, "target_tokens": 512 }, "embedding": { "model": "string" } }
{
}
Samples
Update a document's RAG config
PATCH
/v1/documents/{document_id}/rag-config
Update the retrieval configuration for a document. Every section and field is
optional; omitted ones keep their saved values. When reranking.top_k is omitted
it is lowered to fit the retrieval pool if needed. Returns the full updated config.
Changing chunking settings does not re-chunk the document on its own; queue a
re-ingest with redo=true to rebuild chunks under the new settings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
document_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
Any of
Any of
Responses
Successful Response
application/json
JSON "config": { "chunking": { "method": "token", "overlap_tokens": 200, "target_tokens": 512 }, "embedding": { "model": "string" } }
{
}