Skip to main content

How Drive Works

This page explains the drive model and the mechanics behind every Drive operation: how files and folders nest into a tree, how access and participant roles work, how browsing and searching behave, how signed-URL downloads work, and the three-step multipart upload flow in detail. For a quick orientation and copy-paste examples, start with the Drive introduction.

The drive model​

Drive holds two kinds of items:

  • Files — uploaded documents, images, videos, and other binary content. Each has a mimeType and size.
  • Folders — containers that group files and other folders.

Items nest through a parentId, building a file-system-like tree:

Project Assets (folder)
├── Designs (folder)
│   ├── logo.png
│   └── banner.jpg
└── report.pdf

Items without a parent sit at the drive root.

Access model​

Access follows ownership and sharing. With a Personal Access Token, the API returns only items the authenticated user owns or that have been shared with them. Shared participants carry a role that governs what they can do:

  • admin — full access, including managing participants.
  • member — can upload, download, create folders, and modify content.
  • viewer — read-only access (view metadata and download files).

Browsing and searching​

  • Tree — walks the hierarchy breadth-first. Omit parentId for root-level items, or pass a folder id for its subtree; control depth with depth (1–10, default 3). Each node has a hasChildren flag for lazy-loading explorers, and the response is capped at 500 items (with nextParentIds to continue when truncated).
  • Search — full-text search across accessible items by q, with optional sortBy, sortOrder, and limit (1–50, default 20).
  • Get file — returns metadata for a single file or folder.

Downloading files​

Call the file's …/download endpoint to get a time-limited signed URL ({ "url": "…" }). Fetch the file with a plain HTTP GET against that URL. Downloads apply to files, not folders.

Creating folders​

POST a name, with an optional parentId to nest the folder inside another. The response is the new folder item.

Uploading files (multipart flow)​

Uploads use an S3-style multipart flow, so files of any size upload reliably by splitting into parts that go directly to storage. There are three API calls; the actual part bytes are PUT straight to storage, not through Copera.

Step 1 — Start​

POST the file metadata to begin the upload:

{
  "fileName": "report.pdf",
  "fileSize": 5242880,
  "mimeType": "application/pdf",
  "parentId": "<optional folder id>"
}

The response gives you an uploadId and a fileKey. Both are required by the next two steps.

Step 2 — Get presigned URLs​

POST the uploadId, the fileKey, and parts — the number of parts you intend to upload (a count, not an array):

{ "uploadId": "<uploadId>", "fileKey": "<fileKey>", "parts": 3 }

You get back an array of { signedUrl, PartNumber }. Upload each chunk with an HTTP PUT to its signedUrl, and capture the ETag header that storage returns for each part.

Step 3 — Finalize​

POST the uploadId, the fileKey, and the collected parts to assemble the file and create the Drive record:

{
  "uploadId": "<uploadId>",
  "fileKey": "<fileKey>",
  "parts": [
    { "partNumber": 1, "eTag": "<etag-1>" },
    { "partNumber": 2, "eTag": "<etag-2>" },
    { "partNumber": 3, "eTag": "<etag-3>" }
  ]
}

The response is the created file item.

note

Watch the casing. Request bodies use lowercase uploadId, partNumber, and eTag. The presigned-URLs response uses signedUrl and PartNumber (capital P). The ETag for each part comes from the storage PUT response headers — you pass it back in finalize as eTag.

tip

If you don't need fine-grained control, the CLI's drive upload runs this entire flow for you, including directory uploads.

Authentication & scope​

Drive endpoints require a Personal Access Token (cp_pat_) with the access_drive scope. A token missing the scope gets a 403. See Authentication.

Reference​