Skip to main content

​
Overview

The Workspace Files API provides access to files generated during task execution within a session workspace. Agents can produce artifacts such as scripts, analysis results, or data exports during execution — this API lets you browse and retrieve those files.

​
Endpoints

EndpointMethodDescription
/api/v1/sessions/{sessionId}/filesGETList files in the workspace
/api/v1/sessions/{sessionId}/files/{path...}GETDownload a specific file

​
Security

Shannon enforces strict path security on all workspace file operations:
  • Path traversal protection — requests containing .. or absolute paths are rejected with 400 Bad Request
  • Symlink validation — symbolic links pointing outside the workspace are blocked
  • File size limit — downloads are capped at 100 MB per file
Path traversal attempts (e.g., ../../etc/passwd) are blocked at the gateway level. All paths are resolved relative to the session workspace root.

​
List Workspace Files

List files and directories within a session workspace. 
curl "http://localhost:8080/api/v1/sessions/{sessionId}/files" \
  -H "X-API-Key: sk_test_123456"

​
Path Parameters

ParameterTypeRequiredDescription
sessionIdstringYesSession ID (UUID or external_id)

​
Query Parameters

ParameterTypeRequiredDescription
pathstringNoSubdirectory path to list (defaults to workspace root /)
recursivebooleanNoIf true, list files recursively including subdirectories

​
Example with Subdirectory

curl "http://localhost:8080/api/v1/sessions/{sessionId}/files?path=output&recursive=true" \
  -H "X-API-Key: sk_test_123456"

​
Response

{
  "session_id": "abc-123",
  "path": "/",
  "files": [
    {
      "name": "analysis.py",
      "path": "/analysis.py",
      "size": 1234,
      "is_dir": false,
      "modified_at": "2026-03-10T10:00:00Z"
    },
    {
      "name": "output",
      "path": "/output",
      "size": 0,
      "is_dir": true,
      "modified_at": "2026-03-10T10:05:00Z"
    },
    {
      "name": "results.csv",
      "path": "/output/results.csv",
      "size": 56789,
      "is_dir": false,
      "modified_at": "2026-03-10T10:10:00Z"
    }
  ]
}

​
Response Fields

FieldTypeDescription
session_idstringSession identifier
pathstringThe listed directory path
filesarrayList of file entries
files[].namestringFile or directory name
files[].pathstringFull path relative to workspace root
files[].sizeintegerFile size in bytes (0 for directories)
files[].is_dirbooleanWhether the entry is a directory
files[].modified_atstringLast modification timestamp (ISO 8601)

​
Download File

Download a specific file from the session workspace. The response Content-Type is automatically detected based on file content. 
curl "http://localhost:8080/api/v1/sessions/{sessionId}/files/analysis.py" \
  -H "X-API-Key: sk_test_123456" \
  -o analysis.py

​
Path Parameters

ParameterTypeRequiredDescription
sessionIdstringYesSession ID (UUID or external_id)
path...stringYesFull file path within the workspace (e.g., output/results.csv)

​
Response

  • Content-Type: Automatically detected (e.g., text/plain, application/octet-stream, text/csv)
  • Body: Raw file content
If the Firecracker executor is unavailable, the gateway falls back to reading files from the local filesystem. This fallback is transparent to the client but may return a 502 if neither source is accessible.

​
Error Responses

StatusDescription
400Invalid session ID or path traversal attempt (.. or absolute path detected)
401Unauthorized — missing or invalid API key
404Session workspace not found, or file does not exist
413File exceeds 100 MB size limit
502Firecracker executor unavailable and local fallback also failed
All errors follow the standard format: 
{
  "error": "error message here"
}

​
Example Error: Path Traversal

{
  "error": "invalid path: traversal not allowed"
}

​
Example Error: File Too Large

{
  "error": "file exceeds maximum size limit (100MB)"
}

Sessions API

Manage sessions and view session history

Tool Execution

How agents generate workspace artifacts