Folders API

Complete API reference for folder management endpoints.

---

List Folders

Get all folders.

GET /api/v1/folders

Query Parameters

Parameter	Type	Description
parent_id	string	Filter by parent folder
include_document_count	boolean	Include document count (default: true)

Example

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

Response

{
  "folders": [
    {
      "id": "folder_abc123",
      "name": "Contracts",
      "parent_id": null,
      "color": "#3B82F6",
      "icon": "folder",
      "document_count": 45,
      "created_at": "2025-12-16T10:30:00Z"
    }
  ]
}

---

Get Folder

Get a single folder by ID.

GET /api/v1/folders/:id

Example

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

Response

{
  "id": "folder_abc123",
  "name": "Contracts",
  "parent_id": null,
  "color": "#3B82F6",
  "icon": "folder",
  "document_count": 45,
  "created_at": "2025-12-16T10:30:00Z",
  "updated_at": "2025-12-16T10:30:00Z"
}

---

Create Folder

Create a new folder.

POST /api/v1/folders

Request

{
  "name": "Q4 Documents",
  "parent_id": "folder_abc123",
  "color": "#10B981",
  "icon": "folder-special"
}

Example

curl -X POST https://api.archivus.app/api/v1/folders \
  -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 '{
    "name": "Q4 Documents",
    "parent_id": "folder_abc123",
    "color": "#10B981"
  }'

Response

Created folder object.

---

Update Folder

Update folder metadata.

PUT /api/v1/folders/:id

Request

{
  "name": "Updated Folder Name",
  "color": "#EF4444",
  "icon": "folder-important"
}

Example

curl -X PUT https://api.archivus.app/api/v1/folders/folder_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 '{
    "name": "Updated Name",
    "color": "#EF4444"
  }'

Response

Updated folder object.

---

Delete Folder

Delete a folder (must be empty or use force=true).

DELETE /api/v1/folders/:id

Query Parameters

Parameter	Type	Description
force	boolean	Force delete even if not empty (default: false)

Example

curl -X DELETE "https://api.archivus.app/api/v1/folders/folder_abc123?force=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-Subdomain: your-tenant" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN"

Response

{
  "message": "Folder deleted successfully"
}

---

Nested Folders

Create subfolders for better organization:

# Create parent folder
curl -X POST https://api.archivus.app/api/v1/folders \
  -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 '{
    "name": "Legal",
    "parent_id": null
  }'

# Create subfolder
curl -X POST https://api.archivus.app/api/v1/folders \
  -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 '{
    "name": "Contracts",
    "parent_id": "folder_legal"
  }'

---

Code Examples

Python

import requests

class ArchivusFolders:
    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, parent_id=None):
        url = f"{self.base_url}/folders"
        params = {}
        if parent_id:
            params["parent_id"] = parent_id
        
        response = requests.get(url, headers=self.headers, params=params)
        return response.json()
    
    def create(self, name, parent_id=None, color="#3B82F6", icon="folder"):
        url = f"{self.base_url}/folders"
        data = {"name": name, "color": color, "icon": icon}
        if parent_id:
            data["parent_id"] = parent_id
        
        response = requests.post(url, headers=self.headers, json=data)
        return response.json()
    
    def update(self, folder_id, **updates):
        url = f"{self.base_url}/folders/{folder_id}"
        response = requests.put(url, headers=self.headers, json=updates)
        return response.json()
    
    def delete(self, folder_id, force=False):
        url = f"{self.base_url}/folders/{folder_id}"
        params = {"force": str(force).lower()} if force else {}
        response = requests.delete(url, headers=self.headers, params=params)
        return response.status_code == 200

# Usage
folders = ArchivusFolders("YOUR_API_KEY", "your-tenant")
all_folders = folders.list()
new_folder = folders.create("Contracts", color="#3B82F6")

JavaScript

class ArchivusFolders {
  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(parentId = null) {
    const url = new URL(`${this.baseURL}/folders`);
    if (parentId) url.searchParams.set('parent_id', parentId);
    
    const response = await fetch(url, { headers: this.headers });
    return response.json();
  }
  
  async create(name, parentId = null, color = '#3B82F6', icon = 'folder') {
    const data = { name, color, icon };
    if (parentId) data.parent_id = parentId;
    
    const response = await fetch(`${this.baseURL}/folders`, {
      method: 'POST',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    return response.json();
  }
  
  async update(folderId, updates) {
    const response = await fetch(`${this.baseURL}/folders/${folderId}`, {
      method: 'PUT',
      headers: { ...this.headers, 'Content-Type': 'application/json' },
      body: JSON.stringify(updates)
    });
    return response.json();
  }
  
  async delete(folderId, force = false) {
    const url = new URL(`${this.baseURL}/folders/${folderId}`);
    if (force) url.searchParams.set('force', 'true');
    
    const response = await fetch(url, {
      method: 'DELETE',
      headers: this.headers
    });
    return response.ok;
  }
}

// Usage
const folders = new ArchivusFolders('YOUR_API_KEY', 'your-tenant');
const allFolders = await folders.list();
const newFolder = await folders.create('Contracts', null, '#3B82F6');

---

Error Responses

Folder Not Found

Status: 404 Not Found

{
  "error": "not_found",
  "code": "NOT_FOUND",
  "message": "Folder not found"
}

Folder Not Empty

Status: 400 Bad Request

{
  "error": "folder_not_empty",
  "code": "FOLDER_NOT_EMPTY",
  "message": "Folder must be empty before deletion. Use force=true to delete anyway."
}

---

Next Steps

• Documents API - Upload documents to folders
• Organizing Documents Guide - Learn about organization strategies

---

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