media_upload_link

com.riddle/creator · Verify this server

Creates a single-use link for uploading ONE media file into the media library. Call it when the user has a LOCAL file for a Riddle: this server cannot receive bytes, so the upload is yours. A link expires after 5 minutes, dies on first use (successful or not), and only 20 are handed out per account per 5 minutes - so create one immediately before each upload, a batch one file at a time rather than the links up front, and never store or share one. Check the file BEFORE minting a link, since a link a rejected file burns is gone: an image, a video or an audio file, at most 10 MB (some environments cap lower - "maxBytes" and "allowedTypes" in the answer are the authoritative pair). Returns {uploadUrl, expiresAt (UTC), singleUse, maxBytes, allowedTypes, usage, requiresNetworkAccessTo}. POST the file to "uploadUrl" as multipart/form-data under the field name "file" - "usage" is that command ready to run, e.g. curl -F 'file=@/path/to/image.png' '<uploadUrl>' (the link carries its own signature, so no API key or header). That POST leaves your environment and needs outbound HTTPS to the host in "requiresNetworkAccessTo" (allowlist the wildcard it gives; in Claude only an admin can change that organization setting). If it is blocked or does not resolve, tell the user which host to allow - do not retry or look for another way in. The POST answers with {mediaId, type, width, height, size, folderId}: "mediaId" is the ONLY handle - use it as "media": {"type": "Image", "mediaId": <mediaId>} in a block (riddle://reference/riddle-builder/block-types). Never guess a url for it: a CDN url passed as a plain "url" media is re-downloaded as a second, unrelated copy - the account pays twice and this file records no usage, which makes an image in a live Riddle look safe to delete. The file lands in the account's "AI Uploads" folder tagged "AI Upload" (fixed, so the user can review what an agent uploaded in one place), counts against their storage, and media_delete removes it again.