Storage APIs
File and object storage management for users. Provides folder CRUD, file upload/download (including pre-signed URLs), metadata management, search, and quota tracking.
All endpoints use POST /api/v1/storage/<method> with a JSON request body.
Field naming
Request bodies accept either snake_case or camelCase — both parse. Response bodies are
always camelCase (fileId, fullPath, requiredHeaders), because responses are encoded
with protojson. Fields that are unset, empty, zero, or false are omitted from the response
entirely rather than sent as null — read them with a default, not a presence check.
See the Storage guide for upload patterns, pre-signed URLs, folder management, and quota.
Authentication
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: Bearer Auth
Your API key. sk_… for backend-to-backend calls, pk_… for client apps.
Never valid on its own — see the combinations under Security below.
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 |