request_screenshot_upload

What it does

• Writes
• Account required

How a full-resolution screenshot on somebody’s disk reaches a render without its bytes transiting the conversation. It mints one signed upload URL per slot; you or the user’s shell PUT each raw PNG to its URL, and you pass the returned refs into the render tools. Use it in MCP clients that are not ChatGPT, and in automation, instead of inline base64 for anything real.

You can ask: “Create upload slots for these three Tidebook screenshots.”

Input

• countintegerrequiredmin 1max 10

  How many upload slots to mint (1–10, one per screenshot).

• namesarrayoptional

  Original filenames, one per slot in the same order (e.g. ["03_statistics.png", ...]). Each is encoded into that slot's ref, so the saved project re-loads by real filename even without re-passing name at render time. Optional.

  each item

  string

• familystringoptionalat least 1 characterat most 80 characters

  Optional screenshot-family coordinate for this batch (for example "android"). Omit for the project's base family. This does not add a renderable output device; it only tags which saved-project screenshot cell each returned slot represents.

• localestringoptionalat least 1 characterat most 80 characters

  Optional App Store locale coordinate for this batch (e.g. "de-DE"). It is returned on every slot as variant.locale and render_project uses it to select that locale's pixels; omit for the project's base locale.

Result

• okbooleanoptional

• slotsarrayoptional

  each item

  object

  • refstringrequired

  • uploadUrlstringrequiredformat uri

  • namestringoptional

  • variantobjectrequired

    The saved-project screenshot coordinate this slot was minted for. Pass it through with the slot's ref when overriding render_project.

    • familystringoptionalat least 1 characterat most 80 characters

      Device screenshot family (for example "android"). Omit for the project's base family; the two currently advertised iPhone outputs share that base family.

    • localestringoptionalat least 1 characterat most 80 characters

      App Store locale for these pixels. Omit for the project's base locale.

• instructionsstringoptional

• disclosureobjectoptional

  Stated because this call moved caller bytes into ShotOps storage. Relay it before or with the result; do not paraphrase the retention window.

  • movesstringrequired

    The bytes that left the caller’s control, in plain words.

  • whystringrequired

    What the move buys — never a restatement of the mechanism.

  • retentionDaysintegerrequiredgreater than 0

    How long ShotOps keeps it without an explicit retaining action. Read from the retention policy, never typed.

  • retainedBystringrequired

    The explicit action that keeps it past that window.

  • statementstringrequired

    The same four facts as one sentence, safe to relay verbatim.

Example

That request maps to this call:

{
  "name": "request_screenshot_upload",
  "arguments": {
    "count": 3,
    "names": [
      "01-today.png",
      "02-forecast.png",
      "03-spots.png"
    ],
    "locale": "en-US"
  }
}

One entry per slot: the signed upload URL to PUT to, and the ref to pass to a render.

Access and cost

• Needs an account, because the refs are account-scoped storage. Not available to an anonymous hosted caller.
• Free. Minting upload URLs spends no cloud credits.
• The reply discloses what the upload moves, why, how long an unretained upload is kept, and the one action that retains it: saving a project that references it. Say that before the bytes move.
• In ChatGPT, attachments go through import_screenshot instead. A user with a project can skip file transfer entirely and call render_project.

When it refuses

A PUT to the signed URL fails.

The URL is short-lived. Mint a fresh batch rather than retrying an expired one.

A ref renders as a missing shot.

The slot was minted but never uploaded to. Every ref you pass has to have had its PNG PUT to the matching URL first.

Where this fits

• Sending refs instead of base64 from CI
• Getting the screenshots in

What the agent is told

The title and description the server publishes on tools/list — this is the copy a model chooses between, reproduced verbatim.