メインコンテンツへスキップ

​
概要

ワークスペースファイル API は、セッションワークスペース内でタスク実行中に生成されたファイルへのアクセスを提供します。Agent は実行中にスクリプト、分析結果、データエクスポートなどの成果物を生成できます。この API を使用して、それらのファイルを一覧表示およびダウンロードできます。

​
エンドポイント

エンドポイントメソッド説明
/api/v1/sessions/{sessionId}/filesGETワークスペース内のファイルを一覧表示
/api/v1/sessions/{sessionId}/files/{path...}GET特定のファイルをダウンロード

​
セキュリティ

Shannon はすべてのワークスペースファイル操作に対して厳格なパスセキュリティを適用します：
  • パストラバーサル保護 — .. や絶対パスを含むリクエストは 400 Bad Request で拒否されます
  • シンボリックリンク検証 — ワークスペース外を指すシンボリックリンクはブロックされます
  • ファイルサイズ制限 — ダウンロードはファイルあたり 100 MB に制限されています
パストラバーサルの試行（例：../../etc/passwd）はゲートウェイレベルでブロックされます。すべてのパスはセッションワークスペースのルートからの相対パスとして解決されます。

​
ワークスペースファイルの一覧表示

セッションワークスペース内のファイルとディレクトリを一覧表示します。 
curl "http://localhost:8080/api/v1/sessions/{sessionId}/files" \
  -H "X-API-Key: sk_test_123456"

​
パスパラメータ

パラメータ型必須説明
sessionIdstringはいセッション ID（UUID または external_id）

​
クエリパラメータ

パラメータ型必須説明
pathstringいいえ一覧表示するサブディレクトリパス（デフォルトはワークスペースルート /）
recursivebooleanいいえtrue の場合、サブディレクトリを含めて再帰的にファイルを一覧表示

​
サブディレクトリの一覧表示例

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

​
レスポンス

{
  "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"
    }
  ]
}

​
レスポンスフィールド

フィールド型説明
session_idstringセッション識別子
pathstring一覧表示されたディレクトリパス
filesarrayファイルエントリのリスト
files[].namestringファイルまたはディレクトリ名
files[].pathstringワークスペースルートからの相対パス
files[].sizeintegerファイルサイズ（バイト）、ディレクトリの場合は 0
files[].is_dirbooleanエントリがディレクトリかどうか
files[].modified_atstring最終更新タイムスタンプ（ISO 8601）

​
ファイルのダウンロード

セッションワークスペースから特定のファイルをダウンロードします。レスポンスの Content-Type はファイル内容に基づいて自動的に検出されます。 
curl "http://localhost:8080/api/v1/sessions/{sessionId}/files/analysis.py" \
  -H "X-API-Key: sk_test_123456" \
  -o analysis.py

​
パスパラメータ

パラメータ型必須説明
sessionIdstringはいセッション ID（UUID または external_id）
path...stringはいワークスペース内の完全なファイルパス（例：output/results.csv）

​
レスポンス

  • Content-Type: 自動検出（例：text/plain、application/octet-stream、text/csv）
  • Body: 生のファイルコンテンツ
Firecracker エグゼキュータが利用できない場合、ゲートウェイはローカルファイルシステムからのファイル読み取りにフォールバックします。このフォールバックはクライアントに対して透過的ですが、どちらのソースもアクセスできない場合は 502 を返す可能性があります。

​
エラーレスポンス

ステータス説明
400無効なセッション ID またはパストラバーサルの試行（.. や絶対パスが検出された）
401認証されていない — API key がないか無効
404セッションワークスペースが見つからない、またはファイルが存在しない
413ファイルが 100 MB のサイズ制限を超過
502Firecracker エグゼキュータが利用不可で、ローカルフォールバックも失敗
すべてのエラーは標準フォーマットに従います： 
{
  "error": "error message here"
}

​
エラー例：パストラバーサル

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

​
エラー例：ファイルサイズ超過

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

​
関連コンテンツ

セッション API

セッションの管理とセッション履歴の表示

ツール実行

Agent がワークスペース成果物を生成する仕組み