Skip to main content
Every V4 run has a workspace. You can let the API create one automatically, create one yourself, or reuse an existing workspace across otherwise independent sessions.

Upload and attach input files

Uploading stores the file in the workspace and returns an upload ID. Pass that ID in attached_file_ids / attachedFileIds to make the file available to a specific run.
You can upload up to 10 files in one helper call. A run can attach up to 20 upload IDs.
Attachments are turn-scoped. Reusing a workspace does not automatically attach every uploaded file to every later run.

Retrieve files the agent creates

Ask the agent to save its output in the workspace, then list files with temporary download URLs:
Download URLs expire after 60 seconds, so request them immediately before downloading. Use cursor / next_cursor (nextCursor in TypeScript) to paginate large workspaces.

Reuse a workspace

  • Pass neither ID to runs.create() to create a new session and workspace.
  • Pass session_id / sessionId to continue the same conversation and workspace.
  • Pass only workspace_id / workspaceId to start a fresh conversation with existing files.
See Upload workspace files and List workspace files for limits and response fields.