upload_create
Tier: write · Tags: upload, write
Mint a short-lived web link a user opens in their browser to upload a
file that a hosted MCP client (ChatGPT) cannot forward through a tool call.
Use this when a user references “the file I just uploaded” / “this image”
but the file never arrived as a tool argument - hosted MCP transports are
JSON-only. The flow is: mint → relay the returned instruction to the
user verbatim → user drops the file in the page and confirms → poll
upload_status(token=...) → reuse the resulting handle in
person_generate(source_upload_ids=[...]) or study_add_iteration(...).
workspace_id: UUID or short alias (e.g. w-6ec) of the workspace the
upload belongs to.
purpose: what the file is for - "person_source" (ground a person),
"study_media" (study iteration content), or "both" (default -
mints both handles from one upload so a single image serves person
grounding AND study media without re-uploading).
wait: OPT-IN convenience (default False). When True, the call
runs a short internal poll loop and returns once the user completes the
upload - but since the gating step is a human in a browser, prefer the
default: relay the link, then poll upload_status after the user
confirms. On wait=True timeout the PENDING session is returned (the
link is still live; poll upload_status later).
timeout: seconds to poll when wait=True (default 120s).
On success upload_url is the link to relay, token polls status, and
instruction is the ready-to-relay copy.
Returns an UploadSession keyed by ok; not_enabled means
this backend lacks hosted uploads, so fall back to a local path.
Full shape: docs_get(“reference/responses”).
Parameters
string
required
UUID or short alias (e.g. ‘w-6ec’, ‘p-abc’, ‘pt-072’)
"study_media" | "person_source" | "both"
Default:
"both".boolean
Default:
false.number
Default:
120.0.upload_status
Tier: read-only · Tags: read, upload
Check the live state of an out-of-band upload session minted by
upload_create.
Call this after relaying the upload link and the user confirms they’ve
uploaded. While status='pending', the returned next_action tells
you to poll again. On status='completed', result carries the
reusable handle(s) and suggestions names the exact downstream call:
person_generate(source_upload_ids=[...]) and/or
study_add_iteration(content_url=… / image_urls=[…]). On status='expired'
the link lapsed unused - mint a fresh one.
A failed read means the token is unknown, expired, or not yours: re-mint
via upload_create rather than falling back to a local path, since
holding a token already proves the feature is enabled here.
token: the opaque session token from upload_create.
Returns an UploadStatusResponse keyed by ok, with status
(pending / completed / expired), result and
next_action. Full shape: docs_get(“reference/responses”).
Parameters
string
required