Upload API
API-key upload intent and completion contract
An environment-bound API key with assets:write can create an upload intent on the NestJS API. Keep this key on your server. Browser dashboard uploads use a Clerk-session admin route instead.
POST /api/v1/uploads accepts JSON with filename, contentType (image/avif, image/gif, image/jpeg, image/png, or image/webp), and size in bytes. The current maximum is 25 MiB. The response contains intentId, uploadUrl, expiresAt, and contentType. PUT the exact bytes to uploadUrl with the returned content type, then call POST /api/v1/uploads/{intentId}/complete with the same bearer key. Completion checks the stored object length and content type before creating the asset. It is safe to retry completion.
Upload intent creation reserves the workspace storage quota. The server currently does not inspect image signatures or recover expired reservations automatically; those are launch blockers. An expired intent or mismatched object cannot complete.