Skip to main content

​
Introduction

The Drive in Copera is a file storage system organized as a tree of files and folders. This guide explains the drive model, how access control works, and how to upload, download, and search files through the Public API.

​
Drive Structure

The drive organizes items into two types:
  • Files — uploaded documents, images, videos, and other binary content.
  • Folders — containers that group files and other folders into a hierarchy.

​
Hierarchy

Items can be nested inside folders using the parentId property. This creates a familiar file-system-like tree:
  • Project Assets (folder)
    • Designs (folder)
      • logo.png (file)
      • banner.jpg (file)
    • report.pdf (file)
Items without a parent sit at the root of the drive.

​
Access Model

Drive access is determined by ownership and sharing:
  • Owner — the user who created the file or folder. Owners have full control.
  • Shared participants — other users who have been granted access with a specific role:
    • admin — full access including managing participants.
    • member — can upload, download, create folders, and modify content.
    • viewer — read-only access (view metadata and download files).
When using a Personal Access Token, the API returns drive items based on the authenticated user’s access. You can only interact with items you own or that have been shared with you.

​
PAT Permissions

Your Personal Access Token must include the ACCESS_DRIVE scope to use the Drive API endpoints. Tokens without this scope will receive a 403 Forbidden response.
Use the Drive Tree endpoint to navigate the folder hierarchy:
  • Fetch root-level items by calling the endpoint without a parentId.
  • Fetch a subtree by passing a folder ID as parentId.
  • Control depth with the depth parameter (1-10, default 3).
Each node includes a hasChildren flag, which is useful for building lazy-loading file explorers — only fetch deeper levels when a user expands a folder.

​
Searching Files

The Search Files endpoint provides full-text search across all drive items accessible to the authenticated user. Pass a query string with the q parameter, and optionally control sorting and result limits with sortBy, sortOrder, and limit.

​
Downloading Files

To download a file:
  1. Call the Download File endpoint with the file ID.
  2. The API returns a CloudFront signed URL valid for 3 hours.
  3. Use the signed URL to download the file via a standard HTTP GET request.
Download is only available for files, not folders.

​
Uploading Files

File uploads use a multipart upload flow via S3. This approach supports large files reliably by splitting them into parts. See the Multipart Upload endpoint for the full step-by-step process:
  1. Start the upload with file metadata to get an uploadId and fileKey.
  2. Request presigned URLs for each part of the file.
  3. Upload each part directly to S3 using the presigned URLs.
  4. Finalize the upload by submitting the part ETags to create the drive item.

​
Creating Folders

Use the Create Folder endpoint to create new folders. Provide a name and optionally a parentId to nest the folder inside an existing one.

​
Example Workflow

A typical workflow for managing drive files through the API:
  1. Navigate the tree — GET /public/v1/drive/tree to explore the folder hierarchy.
  2. Create a folder — POST /public/v1/drive/folders with a name and optional parent.
  3. Upload a file — Use the multipart upload flow to upload a file into the folder.
  4. Search files — GET /public/v1/drive/search?q=keyword to find files by name.
  5. Download a file — GET /public/v1/drive/files/{fileId}/download to get a signed download URL.
  6. Get file details — GET /public/v1/drive/files/{fileId} to retrieve metadata.

​
Summary

  • The drive organizes files and folders in a tree hierarchy.
  • Access is based on ownership and shared participant roles (admin, member, viewer).
  • Navigate the hierarchy using the tree endpoint with parentId and depth for lazy loading.
  • Search across all accessible files with full-text search.
  • Download files via CloudFront signed URLs (valid for 3 hours).
  • Upload files using the three-step multipart upload flow via S3.
  • Your PAT must include the ACCESS_DRIVE scope.