Adding files

Upload files and mount them in your container for reading and processing.

You can provide files to your agent by uploading them via the Files API and mounting them in the session's container.

All Managed Agents API requests require the `managed-agents-2026-04-01` beta header. The SDK sets the beta header automatically.

Uploading files

First, upload a file using the Files API:

file=$(curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/files" \
  -F file=@data.csv)
file_id=$(jq -er '.id' <<<"${file}")
printf 'File ID: %s\n' "${file_id}"

FILE_ID=$(ant beta:files upload \
  --file data.csv \
  --transform id --format yaml)

file = client.beta.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")

const file = await client.beta.files.upload({
  file: await toFile(readFile("data.csv"), "data.csv", { type: "text/csv" }),
});
console.log(`File ID: ${file.id}`);

await using var stream = File.OpenRead(csvPath);
var file = await client.Beta.Files.Upload(new() { File = stream });
Console.WriteLine($"File ID: {file.ID}");

csvFile, err := os.Open("data.csv")
if err != nil {
	panic(err)
}
defer csvFile.Close()

file, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
	File: csvFile,
})
if err != nil {
	panic(err)
}
fmt.Printf("File ID: %s\n", file.ID)

var file = client.beta().files().upload(
    FileUploadParams.builder().file(dataCsv).build()
);
IO.println("File ID: " + file.id());

$ch = curl_init('https://api.anthropic.com/v1/files');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('ANTHROPIC_API_KEY'),
        'anthropic-version: 2023-06-01',
        'anthropic-beta: files-api-2025-04-14',
    ],
    CURLOPT_POSTFIELDS => ['file' => new CURLFile($csvPath, 'text/csv', 'data.csv')],
]);
$file = json_decode(curl_exec($ch));
echo "File ID: {$file->id}\n";

file = client.beta.files.upload(file: Pathname(csv_path))
puts "File ID: #{file.id}"

Mounting files in a session

Mount uploaded files into the container by adding them to the resources array when creating a session:

The `mount_path` is optional, but make sure the uploaded file has a descriptive name so the agent knows what it is looking for.

session=$(
  jq -n \
    --arg agent_id "${agent_id}" \
    --arg environment_id "${environment_id}" \
    --arg file_id "${file_id}" \
    '{
      agent: $agent_id,
      environment_id: $environment_id,
      resources: [
        {
          type: "file",
          file_id: $file_id,
          mount_path: "/workspace/data.csv"
        }
      ]
    }' | curl --fail-with-body -sS "${auth[@]}" "${base_url}/sessions" --json @-
)
session_id=$(jq -er '.id' <<<"${session}")

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment "$ENVIRONMENT_ID" \
  --transform id --format yaml <<EOF
resources:
  - type: file
    file_id: $FILE_ID
    mount_path: /workspace/data.csv
EOF
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/workspace/data.csv",
        },
    ],
)

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "file",
      file_id: file.id,
      mount_path: "/workspace/data.csv",
    },
  ],
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Resources =
    [
        new BetaManagedAgentsFileResourceParams
        {
            Type = "file",
            FileID = file.ID,
            MountPath = "/workspace/data.csv",
        },
    ],
});

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
		OfFile: &anthropic.BetaManagedAgentsFileResourceParams{
			Type:      anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
			FileID:    file.ID,
			MountPath: anthropic.String("/workspace/data.csv"),
		},
	}},
})
if err != nil {
	panic(err)
}

var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addResource(
            BetaManagedAgentsFileResourceParams.builder()
                .type(BetaManagedAgentsFileResourceParams.Type.FILE)
                .fileId(file.id())
                .mountPath("/workspace/data.csv")
                .build()
        )
        .build()
);

$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    resources: [
        BetaManagedAgentsFileResourceParams::with(
            type: 'file',
            fileID: $file->id,
            mountPath: '/workspace/data.csv',
        ),
    ],
);

session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "file",
      file_id: file.id,
      mount_path: "/workspace/data.csv"
    }
  ]
)

A new file_id will be created that references the instance of the file in the session. These copies do not count against your storage limits.

Multiple files

Mount multiple files by adding entries to the resources array:

```json curl hidelines={1,-1} { "resources": [ { "type": "file", "file_id": "file_abc123", "mount_path": "/workspace/data.csv" }, { "type": "file", "file_id": "file_def456", "mount_path": "/workspace/config.json" }, { "type": "file", "file_id": "file_ghi789", "mount_path": "/workspace/src/main.py" } ] } ```

resources = [
    {"type": "file", "file_id": "file_abc123", "mount_path": "/workspace/data.csv"},
    {"type": "file", "file_id": "file_def456", "mount_path": "/workspace/config.json"},
    {"type": "file", "file_id": "file_ghi789", "mount_path": "/workspace/src/main.py"},
]

const _ = {
  resources: [
    { type: "file", file_id: "file_abc123", mount_path: "/workspace/data.csv" },
    { type: "file", file_id: "file_def456", mount_path: "/workspace/config.json" },
    { type: "file", file_id: "file_ghi789", mount_path: "/workspace/src/main.py" }
  ]
};

var resources = new[]
{
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_abc123", MountPath = "/workspace/data.csv" },
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_def456", MountPath = "/workspace/config.json" },
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_ghi789", MountPath = "/workspace/src/main.py" },
};

resources := []anthropic.BetaSessionNewParamsResourceUnion{
	{OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_abc123", MountPath: anthropic.String("/workspace/data.csv")}},
	{OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_def456", MountPath: anthropic.String("/workspace/config.json")}},
	{OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_ghi789", MountPath: anthropic.String("/workspace/src/main.py")}},
}

var resources = List.of(
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_abc123").mountPath("/workspace/data.csv").build(),
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_def456").mountPath("/workspace/config.json").build(),
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_ghi789").mountPath("/workspace/src/main.py").build()
);

$resources = [
    ['type' => 'file', 'file_id' => 'file_abc123', 'mount_path' => '/workspace/data.csv'],
    ['type' => 'file', 'file_id' => 'file_def456', 'mount_path' => '/workspace/config.json'],
    ['type' => 'file', 'file_id' => 'file_ghi789', 'mount_path' => '/workspace/src/main.py'],
];

resources = [
  {type: "file", file_id: "file_abc123", mount_path: "/workspace/data.csv"},
  {type: "file", file_id: "file_def456", mount_path: "/workspace/config.json"},
  {type: "file", file_id: "file_ghi789", mount_path: "/workspace/src/main.py"}
]

A maximum of 100 files is supported per session.

Managing files on a running session

You can add or remove files from a session after creation using the session resources API. Each resource has an id returned when it is added (or listed), which you use for deletes.

resource=$(
  jq -n --arg file_id "${file_id}" '{type: "file", file_id: $file_id}' \
    | curl --fail-with-body -sS "${auth[@]}" \
        "${base_url}/sessions/${session_id}/resources" --json @-
)
resource_id=$(jq -er '.id' <<<"${resource}")
printf '%s\n' "${resource_id}"  # "sesrsc_01ABC..."

RESOURCE_ID=$(ant beta:sessions:resources create \
  --session-id "$SESSION_ID" \
  --type file \
  --file-id "$FILE_ID" \
  --transform id --format yaml)

resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sesrsc_01ABC..."

const resource = await client.beta.sessions.resources.add(session.id, {
  type: "file",
  file_id: file.id,
});
console.log(resource.id); // "sesrsc_01ABC..."

var resource = await client.Beta.Sessions.Resources.Add(session.ID, new()
{
    Type = "file",
    FileID = file.ID,
});
Console.WriteLine(resource.ID);  // "sesrsc_01ABC..."

resource, err := client.Beta.Sessions.Resources.Add(ctx, session.ID, anthropic.BetaSessionResourceAddParams{
	BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{
		Type:   anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
		FileID: file.ID,
	},
})
if err != nil {
	panic(err)
}
fmt.Println(resource.ID) // "sesrsc_01ABC..."

var resource = client.beta().sessions().resources().add(
    session.id(),
    ResourceAddParams.builder()
        .betaManagedAgentsFileResourceParams(
            BetaManagedAgentsFileResourceParams.builder()
                .type(BetaManagedAgentsFileResourceParams.Type.FILE)
                .fileId(file.id())
                .build()
        )
        .build()
);
IO.println(resource.id()); // "sesrsc_01ABC..."

$resource = $client->beta->sessions->resources->add(
    $session->id,
    type: 'file',
    fileID: $file->id,
);
echo "{$resource->id}\n";  // "sesrsc_01ABC..."

resource = client.beta.sessions.resources.add(
  session.id,
  type: "file",
  file_id: file.id
)
puts resource.id # "sesrsc_01ABC..."

List all resources on a session with resources.list. To remove a file, call resources.delete with the resource ID:

curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/sessions/${session_id}/resources" \
  | jq -r '.data[] | "\(.id) \(.type)"'

curl --fail-with-body -sS "${auth[@]}" -X DELETE \
  "${base_url}/sessions/${session_id}/resources/${resource_id}" >/dev/null

ant beta:sessions:resources list --session-id "$SESSION_ID"

ant beta:sessions:resources delete \
  --session-id "$SESSION_ID" \
  --resource-id "$RESOURCE_ID"

listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)

const listed = await client.beta.sessions.resources.list(session.id);
for (const entry of listed.data) {
  console.log(entry.id, entry.type);
}

await client.beta.sessions.resources.delete(resource.id, {
  session_id: session.id,
});

var listed = await client.Beta.Sessions.Resources.List(session.ID);
foreach (var entry in listed.Data)
{
    var type = entry.Match<string>(repository => repository.Type, fileResource => fileResource.Type);
    Console.WriteLine($"{entry.ID} {type}");
}

await client.Beta.Sessions.Resources.Delete(resource.ID, new() { SessionID = session.ID });

listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{})
if err != nil {
	panic(err)
}
for _, entry := range listed.Data {
	fmt.Println(entry.ID, entry.Type)
}

if _, err := client.Beta.Sessions.Resources.Delete(ctx, resource.ID, anthropic.BetaSessionResourceDeleteParams{
	SessionID: session.ID,
}); err != nil {
	panic(err)
}

var listed = client.beta().sessions().resources().list(session.id());
for (var entry : listed.data()) {
    if (entry.isFile()) {
        var fileResource = entry.asFile();
        IO.println(fileResource.id() + " " + fileResource.type());
    } else if (entry.isGitHubRepository()) {
        var repoResource = entry.asGitHubRepository();
        IO.println(repoResource.id() + " " + repoResource.type());
    }
}

client.beta().sessions().resources().delete(
    resource.id(),
    ResourceDeleteParams.builder().sessionId(session.id()).build()
);

$listed = $client->beta->sessions->resources->list($session->id);
foreach ($listed->data as $entry) {
    echo "{$entry->id} {$entry->type}\n";
}

$client->beta->sessions->resources->delete($resource->id, sessionID: $session->id);

listed = client.beta.sessions.resources.list(session.id)
listed.data.each { puts "#{it.id} #{it.type}" }

client.beta.sessions.resources.delete(resource.id, session_id: session.id)

Listing and downloading session files

Use the Files API to list files scoped to a session and download them.

```bash curl # List files associated with a session curl -fsSL "https://api.anthropic.com/v1/files?scope_id=sesn_abc123" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01"

Download a file

curl -fsSL "https://api.anthropic.com/v1/files/$FILE_ID/content"
-H "x-api-key: $ANTHROPIC_API_KEY"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: managed-agents-2026-04-01"
-o output.txt


```python Python
# List files associated with a session
files = client.beta.files.list(
    scope_id="sesn_abc123",
    betas=["managed-agents-2026-04-01"],
)
for f in files:
    print(f.id, f.filename)

# Download a file
content = client.beta.files.download(files.data[0].id)
content.write_to_file("output.txt")

// List files associated with a session
const files = await client.beta.files.list({
  scope_id: "sesn_abc123",
  betas: ["managed-agents-2026-04-01"],
});
for (const f of files.data) {
  console.log(f.id, f.filename);
}

// Download a file
const content = await client.beta.files.download(files.data[0].id);
await content.writeToFile("output.txt");

// List files associated with a session
var files = await client.Beta.Files.List(new FileListParams
{
    ScopeID = "sesn_abc123",
    Betas = ["managed-agents-2026-04-01"],
});

// Download a file
byte[] content = await client.Beta.Files.Download(files.Data[0].ID);
await File.WriteAllBytesAsync("output.txt", content);

// List files associated with a session
files, err := client.Beta.Files.List(ctx, anthropic.BetaFileListParams{
	ScopeID: anthropic.String("sesn_abc123"),
	Betas:   []anthropic.AnthropicBeta{"managed-agents-2026-04-01"},
})
if err != nil {
	panic(err)
}

// Download a file
resp, err := client.Beta.Files.Download(ctx, files.Data[0].ID, anthropic.BetaFileDownloadParams{})
if err != nil {
	panic(err)
}
defer resp.Body.Close()
fileContent, _ := io.ReadAll(resp.Body)
os.WriteFile("output.txt", fileContent, 0644)

// List files associated with a session
var files = client.beta().files().list(FileListParams.builder()
    .scopeId("sesn_abc123")
    .addBeta(AnthropicBeta.of("managed-agents-2026-04-01"))
    .build());

// Download a file
try (HttpResponse response = client.beta().files().download(files.data().get(0).id())) {
    try (InputStream body = response.body()) {
        Files.copy(body, Path.of("output.txt"), StandardCopyOption.REPLACE_EXISTING);
    }
}

// List files associated with a session
$files = $client->beta->files->list(
    scopeID: 'sesn_abc123',
    betas: ['managed-agents-2026-04-01'],
);

// Download a file
$content = $client->beta->files->download($files->data[0]->id);
file_put_contents('output.txt', $content);

# List files associated with a session
files = client.beta.files.list(
  scope_id: "sesn_abc123",
  betas: ["managed-agents-2026-04-01"]
)

# Download a file
content = client.beta.files.download(files.data[0].id)
File.binwrite("output.txt", content.read)

Supported file types

The agent can work with any file type, including:

Source code (.py, .js, .ts, .go, .rs, etc.)
Data files (.csv, .json, .xml, .yaml)
Documents (.txt, .md)
Archives (.zip, .tar.gz) - the agent can extract these using bash
Binary files - the agent can process these with appropriate tools

File paths

Files mounted in the container are read-only copies. The agent can read them but cannot modify the original uploaded file. To work with modified versions, the agent writes to new paths within the container.

Files are mounted at the exact path you specify
Parent directories are created automatically
Paths should be absolute (starting with /)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding files

Uploading files

Mounting files in a session

Multiple files

Managing files on a running session

Listing and downloading session files

Download a file

Supported file types

File paths

FilesExpand file tree

files.md

Latest commit

History

files.md

File metadata and controls

Adding files

Uploading files

Mounting files in a session

Multiple files

Managing files on a running session

Listing and downloading session files

Download a file

Supported file types

File paths