Files and artifacts

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Files and published artifacts

Files live in the agent's environment. An artifact is a published copy of a file from an OpenAI-hosted environment. You can download that copy after the environment expires.

Upload files

For an OpenAI-hosted environment, supply input files in environment.files when you create the session. Choose each file's destination under /workspace.

Use type: "file_id" with a file_id from the Files API, or type: "inline" with base64-encoded data. Both forms require a path.

To add files after the environment connects, use the environment Files API.

Resolve upload errors

For HTTP 400, use error.param and error.message to identify the input to correct. For example, a destination outside /workspace returns:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "path must be an absolute POSIX path inside /workspace",
    "param": "path"
  }
}

The parameter follows the request structure. Here, i is the file's index, starting at 0 for the first file:

Use valid base64 data and file IDs, and choose an absolute path under /workspace. Check the file limits. Destinations that traverse a symlink, already exist, or have an overlong path component return HTTP 400.

Unexpected errors while installing a file return HTTP 500. Before retrying, check whether the destination was created, then follow the retry guidance.

Retrieve your files

From your own environment

Ask the agent to write its output to a known path. After the turn completes, retrieve the file through your provider or infrastructure. Save it in your application's storage before the environment expires or you delete it.

Files from self-hosted environments are not published through the Artifacts API, including files under /workspace/outputs. See Sandbox providers for provider-specific file access.

From an OpenAI-hosted environment

Ask the agent to save the file under /workspace/outputs, such as /workspace/outputs/report.pdf. OpenAI publishes outputs as immutable artifacts when the turn completes.

Pass your API client, session ID, completed turn ID, artifact path, and local destination to this function. It lists artifacts and downloads the file matching both the turn and path:

Find and download an artifact

# Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")

See the List artifacts, Retrieve metadata, and Download content references for request and response fields.

Download multiple files

The API downloads one artifact per request; it does not provide a batch-download endpoint. To download several files, list the artifacts and request each file's content. For a single download, ask the agent to bundle the results into a ZIP file under /workspace/outputs, then download that archive as one artifact.

File lifetime

Published artifacts survive environment expiration. Download anything you need to retain before deleting the session.

Artifacts cannot be uploaded or edited through this API. To publish a new version, ask the agent to update the file and complete another turn. Use the turn ID and path to distinguish versions.

Delete an artifact when you no longer need the published copy. Deletion leaves the file in the environment intact.

File limits