Files

Uploads a file as multipart/form-data in a single shot. Spreadsheets can then be previewed and imported. Requires files:write. Accepts an optional Idempotency-Key header.

The 50 MB ceiling

This is a single-shot upload, which is what puts a ceiling on it at all. The default is 50 MB — and treat that as an upper bound the deployment must also honour, not a guarantee.

A size rule can only reject a request it actually received, so a body over PHP's own upload_max_filesize / post_max_size never reaches the validator and surfaces as a confusing 400 parameter_invalid with param: "file" — "file is required" — rather than a size error. An ingress body-size limit rejects it earlier still, with a bare 413 that is not in the API's error envelope at all. The three limits are configured in different places and nothing enforces that they agree.

Anything larger goes through multipart uploads, which do not send the bytes through the API at all, so none of the three limits apply.

Required attributes

Optional attributes

Retrieves a file's metadata by id. Requires files:read.

Parses a previously uploaded spreadsheet and returns, per sheet, the header labels, up to two example rows, and the data row count — everything you need to build an import mapping and rows value. Requires files:read.

Sheets come back in workbook order, which is the order a multi-level import consumes them: levels[0] reads the first sheet, levels[1] the second, and so on.

A file that exists but is not a spreadsheet this endpoint can parse returns 404 file_not_previewable — distinct from a missing id, which is 404 resource_missing.

Lists one page of a directory's direct children, files and folders interleaved. Requires files:read.

Switch on object to tell the two apart: a folder carries a path and no id, a file carries an id and no path.

Paths are normalized, so /exports/2026, exports/2026 and /exports/2026/ all name the same directory. . and .. segments, empty segments, and the | character are 400 parameter_invalid.

path joins the cursor's scope, so a cursor minted in one directory and replayed against another is 400 invalid_cursor.

There is no ?search= on files. The drive search underneath is unbounded, so exposing it would put an unpredictable scan behind a public endpoint. Until that is fixed, list a directory and filter client-side, or keep your own index of the ids you uploaded — the id is the stable handle, not the name.

Optional attributes

Returns a link, not the bytes. Requires files:read.

Objects run to tens of megabytes, and proxying one through the API would hold a worker for the whole transfer, pay egress twice, and put a request timeout between you and a download that is otherwise object storage's problem. Fetch url directly; it needs no Authorization header.

That is also the catch: the URL carries its own authorization, so it is a bearer credential for that one object until it expires. Don't log it, don't persist it in a query string, and don't hand it to a browser you don't trust.

The lifetime is 15 minutes by default — deliberately much shorter than the links the web app mints for a logged-in session, so a URL leaked through a log or a referrer is not a standing grant. expires_at is absolute, so cache the URL for its lifetime and re-request rather than calling per download.

Opens the upload and returns the part plan. Requires files:write.

part_size is 8 MiB, part_count is ceil(size / part_size), and part numbers run 1…part_count. Both come back on this call rather than being yours to choose — two different answers for one upload would let you sign a part the completion then refuses.

filename is rejected here, not sanitized — a deliberate divergence from POST /v1/files, which substitutes characters the Drive key layout cannot hold. There the name comes off a multipart part header the client may not control; here it is a field you typed, and silently storing an upload under a different name than the one you will complete against is worse than a 400. De-duplication still applies (export.csv → export (2).csv), so read the returned filename back.

Required attributes

Optional attributes

Presigns a batch of part numbers. Requires files:write.

Part URLs come in batches of at most 100, and each one lives 15 minutes. That is why they are requested a batch at a time instead of all at once on the create call: an upload with 600 parts would see the first batch expire long before you reached the last.

Re-signing costs nothing — the call computes signatures locally and never talks to object storage — so request the next batch as you go, and simply re-request a URL that expired before you got to it.

Required attributes

Assembles the parts into the finished file. Requires files:write.

Send every part number with the ETag its PUT returned. Completion emits file.created on the change feed — the same event the single-shot upload emits, because a file is a file regardless of how its bytes arrived.

A second complete against the same id, or a DELETE after completing, is 409 upload_completed.

Required attributes

Drops the parts and the Drive row, and frees the filename. Requires files:write.

That last part is the point: a client that gives up on a failed export.csv and retries should get export.csv back, not export (2).csv shadowed by a dead entry it can no longer see.

The cost of that choice, stated plainly: nothing about the upload survives, so a later call against the id is 404 resource_missing rather than a distinct "aborted" state.

Creates a directory. Requires files:write.

A folder is a stored row, not an object-storage prefix. The Drive keys items by directory and name, so a directory exists because something says it does — which is why uploading into a folder does not create it, and why this endpoint exists at all.

. and .. are rejected as names: they pass the character rule but could never be addressed again, because path parameters reject them as segments — so such a folder would be created unlistable. A name already taken in that directory is 409 folder_already_exists.

Folders emit no event.

Required attributes

Optional attributes