Documents
Documents are files you upload for a conversation to read. Each document belongs to the user who uploaded it; you only ever see, extract, download, or delete your own.
Upload a file with Upload a document, then extract its text for a model to read. Uploads are capped at 16 MB per request.
The document object
One stored file in the caller's library.
Attributes
-
document_idintegerThe document's unique identifier.
-
document_namestringThe original file name.
-
document_typenullable stringThe detected MIME type.
-
categorystringHow the document was created:
uploaded,generated, orother. -
created_atstringWhen the document was stored.
-
download_urlstringRelative URL to download the file. Present when listing documents.
{
"document_id": 501,
"document_name": "q3-report.pdf",
"document_type": "application/pdf",
"category": "uploaded",
"created_at": "Tue, 01 Sep 2026 09:30:00 GMT",
"download_url": "/api/documents/501/download"
}List documents
GET /api/documents
Returns the caller's documents, grouped by category.
Returns the caller's documents grouped into uploaded, generated, and other. Each item includes a download_url for Download a document.
- Authentication
- Bearer token How it works
Parameters
No parameters.
Returns
Returns the caller's documents grouped by category in data.
curl "$VDF_BASE_URL/api/documents" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/api/documents`, {
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.get(
f"{os.environ['VDF_BASE_URL']}/api/documents",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"data": {
"uploaded": [
{
"document_id": 501,
"document_name": "q3-report.pdf",
"document_type": "application/pdf",
"category": "uploaded",
"created_at": "Tue, 01 Sep 2026 09:30:00 GMT",
"download_url": "/api/documents/501/download"
}
],
"generated": [],
"other": []
}
}Upload a document
POST /api/documents/upload
Stores a file in the caller's document library.
Uploads a file to the caller's library and returns its identifier. Optionally associate it with a chat session by supplying session_id. The maximum request size is 16 MB.
- Authentication
- Bearer token How it works
Form fields multipart/form-data
-
filefile RequiredThe file to store.
-
session_idintegerA chat session to associate the document with.
Returns
Returns the stored document's identifier and detected type.
Errors
- 400 No file was provided, no file was selected, or
session_idwas not a valid integer.
curl -X POST "$VDF_BASE_URL/api/documents/upload" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
-F "file=@q3-report.pdf" \
-F "session_id=128"import { openAsBlob } from 'node:fs';
const form = new FormData();
form.append('file', await openAsBlob('q3-report.pdf'), 'q3-report.pdf');
form.append('session_id', '128');
const response = await fetch(`${process.env.VDF_BASE_URL}/api/documents/upload`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
body: form,
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
with open("q3-report.pdf", "rb") as file:
response = requests.post(
f"{os.environ['VDF_BASE_URL']}/api/documents/upload",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
data={
"session_id": "128",
},
files={"file": file},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"document_id": 501,
"file_type": "application/pdf"
}Extract a document's text
POST /api/documents/{document_id}/extract
Returns the text extracted from a stored document.
Extracts and returns the text of a document already in the caller's library. Supports PDFs (with OCR for scanned pages), images, Word and Excel files, and HTML. The caller must own the document.
- Authentication
- Bearer token How it works
Path parameters
-
document_idinteger RequiredThe document to extract.
Returns
Returns the extracted text, with the document's document_id, document_name, and type.
Errors
- 404 No such document belongs to the caller, or the stored file is missing.
- 400 The file's type is not supported for extraction.
curl -X POST "$VDF_BASE_URL/api/documents/501/extract" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/api/documents/501/extract`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.post(
f"{os.environ['VDF_BASE_URL']}/api/documents/501/extract",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"document_id": 501,
"document_name": "q3-report.pdf",
"document_type": "application/pdf",
"text": "Q3 results summary...",
"file_type": "application/pdf"
}Download a document
GET /api/documents/{document_id}/download
Returns the stored file as an attachment.
Returns the original file for a document the caller owns, as a download.
- Authentication
- Bearer token How it works
Path parameters
-
document_idinteger RequiredThe document to download.
Returns
Returns the file as an attachment.
Errors
- 404 No such document belongs to the caller, or the stored file is missing.
curl "$VDF_BASE_URL/api/documents/501/download" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
-o download.binconst response = await fetch(`${process.env.VDF_BASE_URL}/api/documents/501/download`, {
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const file = await response.blob();import os
import requests
response = requests.get(
f"{os.environ['VDF_BASE_URL']}/api/documents/501/download",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
stream=True,
timeout=30,
)
response.raise_for_status()
with open("download.bin", "wb") as output:
for chunk in response.iter_content(chunk_size=65536):
output.write(chunk)Delete a document
DEL /api/documents/{document_id}
Permanently deletes a document the caller owns and removes its stored file. This cannot be undone.
- Authentication
- Bearer token How it works
Path parameters
-
document_idinteger RequiredThe document to delete.
Returns
Returns success: true, deleted: true, and the document_id.
Errors
- 404 No such document belongs to the caller.
curl -X DELETE "$VDF_BASE_URL/api/documents/501" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"const response = await fetch(`${process.env.VDF_BASE_URL}/api/documents/501`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.VDF_ACCESS_TOKEN}`,
},
});
if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
const data = await response.json();import os
import requests
response = requests.delete(
f"{os.environ['VDF_BASE_URL']}/api/documents/501",
headers={"Authorization": f"Bearer {os.environ['VDF_ACCESS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
data = response.json(){
"success": true,
"deleted": true,
"document_id": 501
}