API Reference: Drive Module

This document details the RESTful API endpoints for the Drive module.

Base path: All endpoints are prefixed with /api.

---

1. Authentication

POST /api/auth/exchange

Exchange a Shell JWT for a Drive-scoped service JWT. Must be called before using any protected endpoint.

Body:

{ "token": "<shell_jwt>" }

Response:

{
  "access_token": "<drive_jwt>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

All subsequent requests must include the Drive JWT:

Authorization: Bearer <drive_jwt>

---

2. File Management API

POST /api/files/upload

Upload a new file.

Content-Type: multipart/form-data

Parameters:

• file: The binary file (Max 100MB).
• folderId: (Optional) Target folder ID.

Response: 201 Created — file metadata object.

GET /api/files

List files in the current organization.

Query Parameters:

• folderId: (Optional) Filter to a specific folder.
• q: Search by name (minimum 2 characters).
• limit: Number of results per page (default 50).
• offset: Pagination offset (default 0).

Response:

{ "data": [...], "total": 120 }

GET /api/files/:id/download

Stream the file binary directly to the client.

Response: Binary file stream with the correct Content-Type header.

DELETE /api/files/:id

Permanently delete a file from both the database and object storage.

Response: 204 No Content

---

3. Folder API

GET /api/folders

List folders. Pass parentId to navigate into a subfolder; omit for root-level folders.

Query Parameters:

• parentId: (Optional) Filter by parent folder.

POST /api/folders

Create a new folder.

Body:

{
  "name": "Project X Documents",
  "parentId": "uuid"
}

Response: 201 Created — folder object.

PATCH /api/folders/:id

Rename a folder. Non-admin users can only rename folders they created.

Body:

{ "name": "New Folder Name" }

Response: Updated folder object.

DELETE /api/folders/:id

Delete a folder and all its contents recursively (subfolders + files + share links).

Response: 204 No Content

---

4. Sharing API

POST /api/files/:id/share

Generate a public share link for a file.

Body:

{ "ttlDays": 7 }

ttlDays must be exactly 1, 3, or 7.

Response (201 Created):

{
  "data": {
    "url": "https://drive.venizia.ai/s/<token>",
    "expiresAt": "2026-04-01T00:00:00.000Z"
  }
}

GET /api/files/:id/share

List all active (non-revoked) share links for a file.

Response:

{
  "data": [
    { "id": "uuid", "token": "...", "expiresAt": "...", "createdBy": "uuid" }
  ]
}

DELETE /api/files/:id/share/:linkId

Revoke an active share link. Uses soft-delete via revokedAt timestamp.

Response: 204 No Content

---

5. Public Access

GET /api/public/files/:token

Download a file via a share token. No authentication required.

Validates that the token exists, has not expired (expiresAt > now), and has not been revoked before streaming the file.

Response: Binary file stream.

---

6. User Management (Admin only)

All endpoints in this section require an admin role.

GET /api/users

List all users. Supports page and limit query parameters.

POST /api/users

Provision a local user.

Body: { "email": string, "name"?: string, "roleId"?: string }

Response: 201 Created

GET /api/users/:id

Get a user record with their assigned roles.

PUT /api/users/:id

Update user status.

Body: { "status": "active" | "suspended" }

POST /api/users/:id/roles

Assign a role to a user.

Body: { "roleId": string }

DELETE /api/users/:id/roles/:roleId

Remove a role from a user.

GET /api/users/roles

List all available roles.

---

7. Standard Error Codes

Status Code	Description
413 Payload Too Large	File exceeds 100MB limit.
403 Forbidden	Access denied for this organization or resource owner.
404 Not Found	File or folder does not exist.
409 Conflict	Duplicate folder name in the same parent.
500 Server Error	Backend or storage failure.