Skip to main content
Some tools take a file (an image to edit, audio to transcribe). Pass a public URL, or upload the file and pass its file_… id wherever the tool’s input expects a URL.
1

Ask for an upload link

The answer holds the file id, its url (a short link such as https://g.spiral.ai/x7Kp2QvR9aLm, live once the bytes are uploaded), a short_upload_url and an upload_command that uses it.
2

Upload the bytes

Run upload_command, or send the file yourself with no header:
It answers the file once stored. The link works for 15 minutes and takes exactly size_bytes bytes. A file over 100 MiB has no short_upload_url: send it to upload_url with exactly the upload_headers, and no Authorization header (upload_command does that too).
3

Use the file

Put the file_… id, or the url, in the run’s input where the tool expects a URL. There is no confirm call.
An agent on your machine (Claude Code, Claude Desktop, any MCP client) calls the MCP tool upload_file with the file’s file_path and runs the upload_command it answers, once per file. The bytes never pass through the agent’s context, so it can upload many files without base64.
A tool may take smaller files than these; it says so when a run uses the file. The first run that uses a file also checks its first bytes: a file whose content is not the type it was uploaded as is refused there. Uploading needs a balance above $0, or a top-up you have completed; otherwise POST /v1/files answers 402 INSUFFICIENT_BALANCE. Uploads are kept for 7 days. Their url is public to whoever holds it, like an output’s link; GET /v1/files/{id} answers it again.