API reference
Upload files and return controlled public file URLs.
This page renders the current v1 OpenAPI operation list into a human reference so builders can see every supported endpoint, request style, and response status before using the raw YAML contract.
Reviewed by GetFileURL product engineering. Last updated .
These endpoints are served under the public v1 API contract. Use bearer API keys from trusted runtimes, keep file IDs for lifecycle actions, and rely on stable error codes for workflow branches.
diagnoseUrl
URL diagnostics use the same outbound URL policy as remote URL ingest. The submitted URL is returned sanitized to the caller, but Convex diagnostic history stores only hostnames and URL hashes.
listFiles
uploadFile
deleteFile
getFile
createSignedDeliveryUrl
uploadFileFromUrl
Remote URL uploads require HTTPS, no URL credentials, standard port 443, an allowed public host, and a valid Content-Length header before quota is reserved.
createUploadSession
Creates a Convex-controlled upload session and an R2 multipart upload. The API key remains server-side; clients upload each part through GetFileURL's Upload/API Worker rather than receiving raw public R2 credentials or URLs.
completeUploadSession
Completes the R2 multipart upload, verifies the completed object size against the declared session size, finalizes Convex file state, and returns the same file response shape as standard upload.
uploadUploadSessionPart
Uploads a single binary part through the Upload/API Worker. The request must include a valid `Content-Length`; all non-final parts must match the session `part_size`, and the final part may be smaller.
getWorkspaceUsage
Returns Convex source-of-truth usage rollups, workspace usage state, plan limits, grace limits, and support target for the API key's workspace. It does not expose Stripe identifiers, billing provider records, private object keys, raw customer file URLs, or customer file contents.
Webhook receiver contracts describe what customer endpoints should accept when GetFileURL delivers lifecycle and usage events. Customer endpoints own the final URL path; the signature and payload shape stay versioned here.
receiveGetFileURLEvent
Breaking API behavior requires a new major path. Additive response fields can ship inside v1, but field removal or renaming requires a new version.
Use API keys from server routes, workers, scripts, or trusted automation credentials. Public browser bundles must not contain production upload credentials.
Upload, metadata, signed delivery URLs, delete, diagnostics, usage, scanner state, and webhook events are treated as one governed file handoff surface.
The YAML contract is the machine-readable source of truth. This page is rendered from the same file so people can scan the v1 endpoint and webhook surface quickly.
No. The repository-owned SDK source and release checks exist, but public npm package availability still waits for release automation and published package verification.
Start with POST /v1/files, keep the bearer key server-side, store file_id for cleanup, and branch on structured errors before adding multipart sessions or webhooks.