Skip to main content
Hand a document or page body to Sidecars by reference. The host uploads the file with a shell command, then passes a short upload_id to create_document, edit_document, create_page or write_page in place of the content. Inline content is fine for a section or a short page. Use an upload when the content is already a file on disk or is larger than about 8 KB: an inline argument makes the model re-type every byte (a 100 KB file is roughly 25,000 output tokens), and past a few kilobytes some hosts need several chunked calls or refuse the argument outright. An upload sends the same file in seconds.

​
request_upload_url

Scope: documents:write (step-up) · Kind: write · Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false
Upload a markdown or HTML file by reference instead of pasting it into a tool argument. Use it when the content is already a file on disk or is over ~8 KB and you can run a shell command: call this, run the returned curl command with your file’s path (expect HTTP 200), then pass upload_id to create_document / edit_document (format markdown) or create_page / write_page (format html) in place of the content.

​
Parameters

​
'markdown' | 'html'
required
markdown for create_document / edit_document, html for create_page / write_page.

​
Returns

​
string
Pass as upload_id to the write tool.
​
string
Single-use PUT URL on the server’s /uploads/ route.
​
'PUT'
​
string
​
number
400,000 for both formats.
​
string
ISO time; the URL stops accepting a body after 5 minutes.
​
string
ISO time; an uploaded file waits 30 minutes for the write that uses it.
​
string
A ready-to-run command; replace <path> with the file’s path and keep the double quotes, so a path with spaces stays one argument.

​
Uploading

A successful upload answers 200 with {"upload_id", "byte_size", "sha256"}.

​
Using the upload

Pass upload_id instead of content_markdown (documents) or html (pages) — never both. Everything else about the write is unchanged: the same role checks, expected_version rules, human-edit protection, checkpoints and audit. An uploaded markdown body is written whole, up to 400,000 bytes, rather than stopping at the 60,000-character inline cap. The write that lands uses the upload up. A refused write — a version conflict, a busy document — leaves it in place, so retry with the same upload_id.

​
Permissions and side effects

  • The upload URL only stores bytes. It cannot create or change anything on its own; the write call does, authenticated as you.
  • An upload is bound to the person and workspace that requested it, is single-use, and deletes itself (with its bytes) when used or after 30 minutes.
  • At most 20 unused uploads per person at a time (too_many_uploads).
  • Uploaded HTML is rendered exactly like inline HTML: scripts, handlers and embeds are removed at render, in a sandboxed frame.

​
Limitations

  • Needs a host that can run a shell command (Claude Code, Codex, Cursor’s agent). Hosts without one send content inline.
  • Hosts that sandbox network access need the Sidecars server’s domain on their allowlist for the curl to reach it.