Code execution and the Files API

Files API Fundamentals

• Upload files (PDFs, images, text files) to Claude and receive a unique file ID
• Reference file IDs in future requests instead of including raw file data
• Returns file metadata object for tracking and retrieval

Code Execution Tool

• Runs Python code in isolated Docker containers on Claude's servers
• Claude can execute code multiple times and interpret results
• No network access — containers cannot make external API calls
• Output returned to Claude for analysis and interpretation

Combining Files API + Code Execution

• Upload file via Files API → get file ID
• Use container upload block (type: "container_upload" with file_id property) to make files accessible in Docker
• Claude executes code to process the file data
• Generated outputs (plots, reports, images) stored in container and downloadable via file IDs
• Eliminates manual code setup and execution

Practical Workflow

• Upload file using Files API → receive file ID
• Create container upload block with file ID in follow-up request
• Ask Claude to analyze the file
• Claude uses code execution to access, process, and analyze
• Download generated files using returned file IDs

Key Advantages

• Enables inspection and analysis of file contents without manual processing
• Versatile for data analysis and many other task types
• Flexible integration into developer applications
• Claude's response contains multiple blocks: text, tool use, and code execution results

Takeaways

• Upload files via Files API to get file IDs, then reference those IDs in future requests instead of raw file data
• Use container upload blocks (type: "container_upload" with file_id) to make uploaded files accessible to Python code execution in isolated Docker containers
• Claude can execute code multiple times to process files and generate outputs (plots, reports, images) that are downloadable via returned file IDs
• Code execution runs in isolated containers with no network access, so Claude interprets results locally
• This workflow eliminates manual code setup and enables seamless file inspection, analysis, and report generation within applications