Session Files

List and download files created by agents during chat sessions

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.

TypeScript

const files = await client.agent.v1.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

Field	Type	Description
chatId	string	The chat session ID
files[].path	string	Relative path from /workspace
files[].name	string	Filename (last segment of path)
files[].sizeBytes	integer	File 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.

TypeScript

const response = await client.agent.v1.chat.files.download(chatId, 'report.md')
// response contains raw file bytes

The :filePath parameter supports nested paths (e.g., output/analysis.pdf).

Response headers

Header	Example	Description
Content-Type	application/pdf	MIME type based on file extension
Content-Disposition	attachment; filename="report.md"	Suggested filename for download
Content-Length	4821	File size in bytes

---

Error handling

Status	Condition
400	Missing or invalid file path, path traversal
401	Invalid API key
403	API key does not have agent:read permission
404	Chat session or file not found
410	Sandbox 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.