Storage APIs
Manage files and folders, issue signed upload/download URLs, and inspect tracked storage usage.
User-facing calls act for the authenticated beneficiary. A backend sk_… key uses an authorized X-On-Behalf-Of selection with users:impersonate; a client pk_… key accompanies that user’s JWT from the configured issuer. Never expose a secret key in a client. Raw identity headers and recipient IDs are not authentication. See Authentication.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
Signed URLs are bearer credentials and can be reused until their expiry. An upload URL is followed by direct upload and registration; issuing the URL neither registers the file nor reserves quota. Registration checks the stored object’s size. Its MIME metadata is not content validation.
Related guide: Files and storage
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
Authentication
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: Bearer Auth
Project/service API key. Use pk_… only with a verified end-user JWT; backend sk_… calls that require a user use authorized on-behalf-of context. Management operations can have different requirements; consult the operation and authentication guide.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |
The end user this call acts for. Required with an sk_… key, because a secret
key identifies your tenant and not a user; omitting it returns
401 authenticated user_id is required. The key needs the users:impersonate
scope or the call fails with 403 insufficient_scope.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-On-Behalf-Of |
The end user's own JWT, issued by the OIDC provider configured on the
publishable key. Required alongside a pk_… key, and supplies the user
identity in place of X-On-Behalf-Of.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |
📄️ Overview
Manage files and folders, issue signed upload/download URLs, and inspect tracked storage usage.
📄️ Upload registration and URL expiry
overview}
🗃️ Endpoints
15 items
🗃️ Models
6 items
Document ID: DOC-CP-files-data-api-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-CP-files-data-api-overview#overview |
| JSON conventions | DOC-CP-files-data-api-overview#json-conventions |
| Authentication | DOC-CP-files-data-api-overview#authentication |