> ## Documentation Index
> Fetch the complete documentation index at: https://browseruse-0aece648-magnus-streaming-api-link.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces & files

> Persistent file storage across sessions. Upload input files, download results, and share data across tasks.

Workspaces are the recommended way to handle all file operations — uploading input files and downloading results. Prefer workspaces over session-level file uploads.

See your workspace IDs at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=workspaces).

## Upload a file

Upload a file to a workspace, then tell the agent to use it.

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from browser_use_sdk.v3 import AsyncBrowserUse

  client = AsyncBrowserUse()
  workspace = await client.workspaces.create(name="my-workspace")

  # Get a presigned upload URL
  upload = await client.workspaces.upload_files(
      str(workspace.id),
      files=[{"name": "people.csv", "contentType": "text/csv", "size": 45}],
  )

  # Upload the file
  with open("people.csv", "rb") as f:
      async with httpx.AsyncClient() as http:
          await http.put(
              upload.files[0].upload_url,
              content=f.read(),
              headers={"Content-Type": "text/csv", "Content-Length": "45"},
          )

  # Tell the agent to use it
  result = await client.run(
      "Read people.csv and tell me who works at Google",
      workspace_id=str(workspace.id),
  )
  print(result.output)
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk/v3";
  import { readFileSync } from "fs";

  const client = new BrowserUse();
  const workspace = await client.workspaces.create({ name: "my-workspace" });

  // Get a presigned upload URL
  const upload = await client.workspaces.uploadFiles(workspace.id, {
    files: [{ name: "people.csv", contentType: "text/csv", size: 45 }],
  });

  // Upload the file
  await fetch(upload.files[0].uploadUrl, {
    method: "PUT",
    headers: { "Content-Type": "text/csv", "Content-Length": "45" },
    body: readFileSync("people.csv"),
  });

  // Tell the agent to use it
  const result = await client.run(
    "Read people.csv and tell me who works at Google",
    { workspaceId: workspace.id },
  );
  console.log(result.output);
  ```
</CodeGroup>

## Download files

Run a task that saves files to a workspace, then download them.

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from browser_use_sdk.v3 import AsyncBrowserUse

  client = AsyncBrowserUse()
  workspace = await client.workspaces.create(name="my-workspace")

  # Agent saves files to the workspace
  result = await client.run(
      "Go to Hacker News and save the top 3 posts as posts.json",
      workspace_id=str(workspace.id),
  )

  # List and download files
  files = await client.workspaces.files(str(workspace.id), include_urls=True)
  for f in files.files:
      print(f"{f.path} ({f.size} bytes)")

      async with httpx.AsyncClient() as http:
          resp = await http.get(f.url)
          with open(f.path, "wb") as out:
              out.write(resp.content)
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk/v3";
  import { writeFileSync } from "fs";

  const client = new BrowserUse();
  const workspace = await client.workspaces.create({ name: "my-workspace" });

  // Agent saves files to the workspace
  const result = await client.run(
    "Go to Hacker News and save the top 3 posts as posts.json",
    { workspaceId: workspace.id },
  );

  // List and download files
  const files = await client.workspaces.files(workspace.id, { includeUrls: true });
  for (const f of files.files) {
    console.log(`${f.path} (${f.size} bytes)`);

    const resp = await fetch(f.url);
    writeFileSync(f.path, Buffer.from(await resp.arrayBuffer()));
  }
  ```
</CodeGroup>

## Manage workspaces

<CodeGroup>
  ```python Python theme={null}
  workspace = await client.workspaces.get(workspace_id)
  updated = await client.workspaces.update(workspace_id, name="renamed")
  workspaces = await client.workspaces.list()
  await client.workspaces.delete(workspace_id)
  ```

  ```typescript TypeScript theme={null}
  const workspace = await client.workspaces.get(workspaceId);
  const updated = await client.workspaces.update(workspaceId, { name: "renamed" });
  const workspaces = await client.workspaces.list();
  await client.workspaces.delete(workspaceId);
  ```
</CodeGroup>

<Warning>
  Deleting a workspace permanently removes all its files. This cannot be undone.
</Warning>