Documents API¶

Complete API reference for document management operations.

Overview¶

The Documents API provides endpoints for uploading, managing, searching, and downloading documents with AI-powered processing.

Key Features:

Upload single or batch documents
AI-powered extraction and analysis
Document sharing and permissions
Version management
Full-text and semantic search integration

List Documents¶

Get a paginated list of documents.

GET /api/v1/documents

Query Parameters¶

Parameter	Type	Description	Default
`page`	integer	Page number	1
`limit`	integer	Items per page (max: 100)	20
`folder_id`	string	Filter by folder	-
`tag_id`	string	Filter by tag	-
`search`	string	Search query	-
`sort`	string	Sort field (`name`, `created_at`, `updated_at`, `size`)	`created_at`
`order`	string	Sort order (`asc`, `desc`)	`desc`
`file_type`	string	Filter by file type	-
`date_start`	string	Filter by start date (ISO 8601)	-
`date_end`	string	Filter by end date (ISO 8601)	-

Example Request¶

cURLJavaScriptPython

curl "https://api.archivus.app/api/v1/documents?page=1&limit=20&folder_id=folder_abc123" \
  -H "X-API-Key: ak_live_YOUR_API_KEY"

const params = new URLSearchParams({
  page: '1',
  limit: '20',
  folder_id: 'folder_abc123'
});

const response = await fetch(`https://api.archivus.app/api/v1/documents?${params}`, {
  headers: { 'X-API-Key': 'ak_live_YOUR_API_KEY' }
});

const data = await response.json();

import requests

params = {
    'page': 1,
    'limit': 20,
    'folder_id': 'folder_abc123'
}

response = requests.get(
    'https://api.archivus.app/api/v1/documents',
    params=params,
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

data = response.json()

Response¶

{
  "data": [
    {
      "id": "doc_abc123",
      "filename": "contract.pdf",
      "original_filename": "Q4 Contract.pdf",
      "file_type": "application/pdf",
      "file_size": 1048576,
      "folder_id": "folder_xyz",
      "status": "completed",
      "ai_status": "completed",
      "ai_summary": "Q4 service contract with renewal terms...",
      "ai_tags": ["contract", "legal", "Q4"],
      "entities": {
        "people": ["John Doe", "Jane Smith"],
        "organizations": ["Acme Corp"],
        "dates": ["2025-12-31"]
      },
      "created_at": "2026-01-18T10:30:00Z",
      "updated_at": "2026-01-18T10:35:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

Get Document¶

Retrieve a single document by ID.

GET /api/v1/documents/{document_id}

Example Request¶

cURLJavaScriptPython

curl "https://api.archivus.app/api/v1/documents/doc_abc123" \
  -H "X-API-Key: ak_live_YOUR_API_KEY"

const response = await fetch('https://api.archivus.app/api/v1/documents/doc_abc123', {
  headers: { 'X-API-Key': 'ak_live_YOUR_API_KEY' }
});

const document = await response.json();

response = requests.get(
    'https://api.archivus.app/api/v1/documents/doc_abc123',
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

document = response.json()

Response¶

{
  "id": "doc_abc123",
  "filename": "contract.pdf",
  "original_filename": "Q4 Contract.pdf",
  "file_type": "application/pdf",
  "file_size": 1048576,
  "storage_path": "tenants/tenant-uuid/documents/...",
  "thumbnail_url": "https://storage.../thumbnail.jpg",
  "ai_thumbnail_url": "https://storage.../ai-thumbnail.jpg",
  "folder_id": "folder_xyz",
  "status": "completed",
  "ai_status": "completed",
  "ai_summary": "Q4 service contract...",
  "ai_tags": ["contract", "legal", "Q4"],
  "entities": {
    "people": ["John Doe", "Jane Smith"],
    "organizations": ["Acme Corp"],
    "dates": ["2025-12-31"]
  },
  "metadata": {
    "author": "John Doe",
    "pages": 15
  },
  "created_at": "2026-01-18T10:30:00Z",
  "updated_at": "2026-01-18T10:35:00Z"
}

Upload Document¶

Upload a single document with AI processing.

POST /api/v1/documents/upload

Request¶

Content-Type: multipart/form-data

Field	Type	Required	Description
`file`	file	Yes	Document file (max 500MB)
`folder_id`	string	No	Target folder ID
`enable_ai`	boolean	No	Enable AI processing (default: true)
`tags`	string[]	No	Manual tags
`filename`	string	No	Custom filename

Example Request¶

cURLJavaScriptPython

curl -X POST https://api.archivus.app/api/v1/documents/upload \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F "enable_ai=true" \
  -F "folder_id=folder_xyz"

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('enable_ai', 'true');
formData.append('folder_id', 'folder_xyz');

const response = await fetch('https://api.archivus.app/api/v1/documents/upload', {
  method: 'POST',
  headers: { 'X-API-Key': 'ak_live_YOUR_API_KEY' },
  body: formData
});

const document = await response.json();

files = {'file': open('contract.pdf', 'rb')}
data = {
    'enable_ai': 'true',
    'folder_id': 'folder_xyz'
}

response = requests.post(
    'https://api.archivus.app/api/v1/documents/upload',
    files=files,
    data=data,
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

document = response.json()

Response¶

{
  "id": "doc_abc123",
  "filename": "contract.pdf",
  "status": "processing",
  "ai_status": "queued",
  "created_at": "2026-01-18T10:30:00Z"
}

Batch Upload¶

Upload multiple documents at once (up to 10 files).

POST /api/v1/documents/upload-batch

Request¶

Content-Type: multipart/form-data

Field	Type	Required	Description
`files[]`	file[]	Yes	Document files (max 10, 500MB each)
`folder_id`	string	No	Target folder ID
`enable_ai`	boolean	No	Enable AI processing

Example Request¶

cURLJavaScriptPython

curl -X POST https://api.archivus.app/api/v1/documents/upload-batch \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.pdf" \
  -F "files[]=@doc3.pdf" \
  -F "folder_id=folder_xyz"

const formData = new FormData();
Array.from(fileInput.files).forEach(file => {
  formData.append('files[]', file);
});
formData.append('folder_id', 'folder_xyz');

const response = await fetch('https://api.archivus.app/api/v1/documents/upload-batch', {
  method: 'POST',
  headers: { 'X-API-Key': 'ak_live_YOUR_API_KEY' },
  body: formData
});

files = [
    ('files[]', open('doc1.pdf', 'rb')),
    ('files[]', open('doc2.pdf', 'rb')),
    ('files[]', open('doc3.pdf', 'rb'))
]
data = {'folder_id': 'folder_xyz'}

response = requests.post(
    'https://api.archivus.app/api/v1/documents/upload-batch',
    files=files,
    data=data,
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

Response¶

{
  "collection_id": "collection_xyz",
  "documents": [
    {
      "id": "doc_abc123",
      "filename": "doc1.pdf",
      "status": "processing"
    },
    {
      "id": "doc_def456",
      "filename": "doc2.pdf",
      "status": "processing"
    },
    {
      "id": "doc_ghi789",
      "filename": "doc3.pdf",
      "status": "processing"
    }
  ],
  "batch_job_id": "batch_xyz"
}

Update Document¶

Update document metadata.

PUT /api/v1/documents/{document_id}

Request Body¶

{
  "filename": "New Filename.pdf",
  "folder_id": "folder_xyz",
  "tags": ["important", "urgent"]
}

Example Request¶

cURLJavaScriptPython

curl -X PUT https://api.archivus.app/api/v1/documents/doc_abc123 \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Q4-Contract-2026.pdf",
    "tags": ["contract", "Q4"]
  }'

const response = await fetch('https://api.archivus.app/api/v1/documents/doc_abc123', {
  method: 'PUT',
  headers: {
    'X-API-Key': 'ak_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filename: 'Q4-Contract-2026.pdf',
    tags: ['contract', 'Q4']
  })
});

response = requests.put(
    'https://api.archivus.app/api/v1/documents/doc_abc123',
    json={
        'filename': 'Q4-Contract-2026.pdf',
        'tags': ['contract', 'Q4']
    },
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

Delete Document¶

Permanently delete a document.

DELETE /api/v1/documents/{document_id}

Example Request¶

cURLJavaScriptPython

curl -X DELETE https://api.archivus.app/api/v1/documents/doc_abc123 \
  -H "X-API-Key: ak_live_YOUR_API_KEY"

await fetch('https://api.archivus.app/api/v1/documents/doc_abc123', {
  method: 'DELETE',
  headers: { 'X-API-Key': 'ak_live_YOUR_API_KEY' }
});

requests.delete(
    'https://api.archivus.app/api/v1/documents/doc_abc123',
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'}
)

Download Document¶

Download the original document file.

GET /api/v1/documents/{document_id}/download

Example Request¶

cURLJavaScriptPython

curl "https://api.archivus.app/api/v1/documents/doc_abc123/download" \
  -H "X-API-Key: ak_live_YOUR_API_KEY" \
  -o document.pdf

const response = await fetch(
  'https://api.archivus.app/api/v1/documents/doc_abc123/download',
  { headers: { 'X-API-Key': 'ak_live_YOUR_API_KEY' } }
);

const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'document.pdf';
a.click();

response = requests.get(
    'https://api.archivus.app/api/v1/documents/doc_abc123/download',
    headers={'X-API-Key': 'ak_live_YOUR_API_KEY'},
    stream=True
)

with open('document.pdf', 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)

Get Document Content¶

Get extracted text content from the document.

GET /api/v1/documents/{document_id}/content

Response¶

{
  "content": "Full extracted text content from the document...",
  "content_type": "extracted_text",
  "length": 12345,
  "pages": 15
}

Share a document with a user or workspace.

POST /api/v1/documents/{document_id}/share

Request Body¶

Share with user:

{
  "user_id": "user_xyz789",
  "permission": "view"
}

Share with workspace:

{
  "workspace_id": "workspace_xyz",
  "permission": "edit"
}

Permissions: view, edit, admin

Response¶

{
  "share_id": "share_abc123",
  "document_id": "doc_abc123",
  "user_id": "user_xyz789",
  "permission": "view",
  "created_at": "2026-01-18T10:30:00Z"
}

Supported File Types¶

Type	Extensions	Max Size	AI Processing
PDF	`.pdf`	500 MB	Full support
Word	`.docx`, `.doc`	100 MB	Full support
Text	`.txt`, `.md`	50 MB	Full support
Images	`.jpg`, `.png`, `.tiff`, `.webp`	50 MB	OCR support
Spreadsheets	`.xlsx`, `.xls`, `.csv`	100 MB	Full support
PowerPoint	`.pptx`, `.ppt`	100 MB	Full support
Audio	`.mp3`, `.wav`, `.m4a`	200 MB	Transcription
Video	`.mp4`, `.mov`	500 MB	Transcription (Pro+)

Error Responses¶

Document Not Found¶

Status: 404 Not Found

{
  "error": "not_found",
  "code": "NOT_FOUND",
  "message": "Document with ID 'doc_abc123' not found"
}

File Too Large¶

Status: 413 Payload Too Large

{
  "error": "file_too_large",
  "code": "FILE_TOO_LARGE",
  "message": "File size exceeds maximum limit of 500MB"
}

Invalid File Type¶

Status: 415 Unsupported Media Type

{
  "error": "invalid_file_type",
  "code": "INVALID_FILE_TYPE",
  "message": "File type not supported. Supported types: pdf, docx, txt, jpg, png"
}

Next Steps¶

Search Documents

Learn how to search your uploaded documents

Search API
Chat with Documents

Ask questions about your documents

Chat API
Webhook Events

Get notified when documents are processed

Webhooks API

Documents API¶

Overview¶

List Documents¶

Query Parameters¶

Example Request¶

Response¶

Get Document¶

Example Request¶

Response¶

Upload Document¶

Request¶

Example Request¶

Response¶

Batch Upload¶

Request¶

Example Request¶

Response¶

Update Document¶

Request Body¶

Example Request¶

Delete Document¶

Example Request¶

Download Document¶

Example Request¶

Get Document Content¶

Response¶

Share Document¶

Request Body¶

Response¶

Supported File Types¶

Error Responses¶

Document Not Found¶

File Too Large¶

Invalid File Type¶

Next Steps¶