Documents API

Complete API reference for document management endpoints.

---

List Documents

Get a paginated list of documents.

GET /api/v1/documents

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
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)
order	string	Sort order (asc, desc)

Example

curl "https://api.archivus.app/api/v1/documents?page=1&limit=20&folder_id=folder_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant"

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...",
      "ai_tags": ["contract", "legal", "Q4"],
      "created_at": "2025-12-16T10:30:00Z",
      "updated_at": "2025-12-16T10:35:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

---

Get Document

Get a single document by ID.

GET /api/v1/documents/:id

Example

curl "https://api.archivus.app/api/v1/documents/doc_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant"

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"]
  },
  "created_at": "2025-12-16T10:30:00Z",
  "updated_at": "2025-12-16T10:35:00Z"
}

---

Upload Document

Upload a single document.

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
enable_ai	boolean	No	Enable AI processing (default: true)
tags	string[]	No	Manual tags
filename	string	No	Custom filename

Example

curl -X POST https://api.archivus.app/api/v1/documents/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -F "file=@document.pdf" \
  -F "enable_ai=true" \
  -F "folder_id=folder_xyz"

Response

{
  "id": "doc_abc123",
  "filename": "document.pdf",
  "status": "processing",
  "ai_status": "queued",
  "created_at": "2025-12-16T10: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
enable_ai	boolean	No	Enable AI processing

Example

curl -X POST https://api.archivus.app/api/v1/documents/upload-batch \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.pdf" \
  -F "files[]=@doc3.pdf"

Response

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

---

Update Document

Update document metadata.

PUT /api/v1/documents/:id

Request

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

Example

curl -X PUT https://api.archivus.app/api/v1/documents/doc_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Q4-Contract-2025.pdf",
    "tags": ["contract", "Q4"]
  }'

Response

Updated document object.

---

Delete Document

Delete a document permanently.

DELETE /api/v1/documents/:id

Example

curl -X DELETE https://api.archivus.app/api/v1/documents/doc_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN"

Response

{
  "message": "Document deleted successfully"
}

---

Download Document

Download the original document file.

GET /api/v1/documents/:id/download

Example

curl "https://api.archivus.app/api/v1/documents/doc_abc123/download" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -o document.pdf

Response

File download with appropriate Content-Type headers.

---

Get Document Content

Get extracted text content from document.

GET /api/v1/documents/:id/content

Example

curl "https://api.archivus.app/api/v1/documents/doc_abc123/content" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant"

Response

{
  "content": "Full extracted text content...",
  "content_type": "extracted_text",
  "length": 12345
}

---

Share Document

Share a document with a user or workspace.

POST /api/v1/documents/:id/share

Request

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

Or share with workspace:

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

Example

curl -X POST https://api.archivus.app/api/v1/documents/doc_abc123/share \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_xyz789",
    "permission": "view"
  }'

Response

{
  "share_id": "share_abc123",
  "document_id": "doc_abc123",
  "user_id": "user_xyz789",
  "permission": "view",
  "created_at": "2025-12-16T10:30:00Z"
}

---

List Shares

Get all shares for a document.

GET /api/v1/documents/:id/shares

Example

curl "https://api.archivus.app/api/v1/documents/doc_abc123/shares" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant"

Response

{
  "shares": [
    {
      "share_id": "share_abc123",
      "user_id": "user_xyz789",
      "user_name": "John Doe",
      "permission": "view",
      "created_at": "2025-12-16T10:30:00Z"
    }
  ]
}

---

Apply AI Tags

Apply AI-suggested tags to document.

POST /api/v1/documents/:id/apply-ai-tags

Example

curl -X POST https://api.archivus.app/api/v1/documents/doc_abc123/apply-ai-tags \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN"

Response

{
  "message": "AI tags applied successfully",
  "tags_applied": ["contract", "legal", "Q4-2025"]
}

---

Code Examples

Python

import requests

class ArchivusDocuments:
    def __init__(self, api_key, tenant):
        self.api_key = api_key
        self.tenant = tenant
        self.base_url = "https://api.archivus.app/api/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "X-Tenant-Subdomain": tenant
        }
    
    def list(self, **filters):
        url = f"{self.base_url}/documents"
        response = requests.get(url, headers=self.headers, params=filters)
        return response.json()
    
    def get(self, document_id):
        url = f"{self.base_url}/documents/{document_id}"
        response = requests.get(url, headers=self.headers)
        return response.json()
    
    def upload(self, file_path, folder_id=None, enable_ai=True):
        url = f"{self.base_url}/documents/upload"
        with open(file_path, "rb") as f:
            files = {"file": f}
            data = {"enable_ai": str(enable_ai).lower()}
            if folder_id:
                data["folder_id"] = folder_id
            response = requests.post(url, headers=self.headers, files=files, data=data)
        return response.json()
    
    def update(self, document_id, **updates):
        url = f"{self.base_url}/documents/{document_id}"
        response = requests.put(url, headers=self.headers, json=updates)
        return response.json()
    
    def delete(self, document_id):
        url = f"{self.base_url}/documents/{document_id}"
        response = requests.delete(url, headers=self.headers)
        return response.status_code == 200

# Usage
docs = ArchivusDocuments("YOUR_API_KEY", "your-tenant")
documents = docs.list(limit=10)
document = docs.get("doc_abc123")
new_doc = docs.upload("document.pdf", folder_id="folder_xyz")

JavaScript

class ArchivusDocuments {
  constructor(apiKey, tenant) {
    this.apiKey = apiKey;
    this.tenant = tenant;
    this.baseURL = 'https://api.archivus.app/api/v1';
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'X-Tenant-Subdomain': tenant
    };
  }
  
  async list(filters = {}) {
    const params = new URLSearchParams(filters);
    const response = await fetch(`${this.baseURL}/documents?${params}`, {
      headers: this.headers
    });
    return response.json();
  }
  
  async get(documentId) {
    const response = await fetch(`${this.baseURL}/documents/${documentId}`, {
      headers: this.headers
    });
    return response.json();
  }
  
  async upload(file, folderId = null, enableAI = true) {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('enable_ai', enableAI);
    if (folderId) formData.append('folder_id', folderId);
    
    const response = await fetch(`${this.baseURL}/documents/upload`, {
      method: 'POST',
      headers: this.headers,
      body: formData
    });
    return response.json();
  }
  
  async update(documentId, updates) {
    const response = await fetch(`${this.baseURL}/documents/${documentId}`, {
      method: 'PUT',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify(updates)
    });
    return response.json();
  }
  
  async delete(documentId) {
    const response = await fetch(`${this.baseURL}/documents/${documentId}`, {
      method: 'DELETE',
      headers: this.headers
    });
    return response.ok;
  }
}

// Usage
const docs = new ArchivusDocuments('YOUR_API_KEY', 'your-tenant');
const documents = await docs.list({ limit: 10 });
const document = await docs.get('doc_abc123');
const newDoc = await docs.upload(fileInput.files[0], 'folder_xyz');

---

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	50 MB	OCR support
Spreadsheets	.xlsx, .xls	100 MB	Full support
PowerPoint	.pptx, .ppt	100 MB	Full support

---

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"
}

---

Next Steps

• Chat API - Chat with your documents
• Search API - Search your documents
• Folders API - Organize documents
• Error Handling - Handle errors properly

---

Questions? Check the FAQ or contact support@ubiship.com