Skip to main content
While a chat session is active, agents create files in their sandbox workspace — reports, analysis results, code, and more. The session files endpoints let you list and download those files before the sandbox terminates.
Sandbox files are ephemeral. Once the sandbox terminates (session ends or times out), files are no longer available and the endpoints return 410 Gone. To persist files permanently, have the agent upload them to a vault using casedev vault upload.

​
List files

Endpoint
GET /agent/v1/chat/:id/files
Returns user-created files in the sandbox workspace. Infrastructure files (agent config, logs, internal state) are automatically filtered out. 
const files = await client.agents.chat.files.list(chatId)

for (const file of files.files) {
  console.log(`${file.path} (${file.sizeBytes} bytes)`)
}
Response
{
  "chatId": "chat_abc123",
  "files": [
    {
      "path": "report.md",
      "name": "report.md",
      "sizeBytes": 4821
    },
    {
      "path": "output/analysis.pdf",
      "name": "analysis.pdf",
      "sizeBytes": 128400
    }
  ]
}

​
Response fields

FieldTypeDescription
chatIdstringThe chat session ID
files[].pathstringRelative path from /workspace
files[].namestringFilename (last segment of path)
files[].sizeBytesintegerFile size in bytes

​
Download a file

Endpoint
GET /agent/v1/chat/:id/files/:filePath
Downloads a specific file by its relative workspace path. Returns the raw file bytes with appropriate Content-Type and Content-Disposition headers. 
const response = await client.agents.chat.files.download(chatId, 'report.md')
// response contains raw file bytes
The :filePath parameter supports nested paths (e.g., output/analysis.pdf).

​
Response headers

HeaderExampleDescription
Content-Typeapplication/pdfMIME type based on file extension
Content-Dispositionattachment; filename="report.md"Suggested filename for download
Content-Length4821File size in bytes

​
Error handling

StatusCondition
400Missing or invalid file path, path traversal
401Invalid API key
403API key does not have agent:read permission
404Chat session or file not found
410Sandbox has terminated — files no longer exist
A 410 response means the sandbox has been destroyed. Files created during the session are gone. Design your workflows to download or upload important files before the session ends.

​
Authentication

Both endpoints require an API key with agent:read permission. The API key must be the same one that owns the chat session.