メインコンテンツまでスキップ

ファイル操作 API

ファイル一覧​

ワークスペース内のディレクトリにあるファイルを一覧表示します。

curl 'https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/files?path=/workspace' \
  -H 'Authorization: Bearer nt_xxx'

クエリパラメータ:

パラメータ型デフォルト説明
pathstring/workspace一覧表示するディレクトリ

レスポンス: 200 OK

{
  "files": [
    { "name": "src", "size": 4096, "isDirectory": true },
    { "name": "package.json", "size": 1234, "isDirectory": false },
    { "name": "README.md", "size": 567, "isDirectory": false }
  ]
}

ファイル読み取り​

ワークスペースからファイルの内容を読み取ります。

curl https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/files/workspace/package.json \
  -H 'Authorization: Bearer nt_xxx'

レスポンス: 200 OK — ファイル内容（バイナリ）

ファイル書き込み​

ワークスペース内のファイルにコンテンツを書き込みます。

curl -X PUT https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/files/workspace/hello.txt \
  -H 'Authorization: Bearer nt_xxx' \
  -d 'Hello from NanoTerm!'

リクエストボディ: ファイルの生コンテンツ

レスポンス: 200 OK

{
  "ok": true,
  "bytes": 3712,
  "mtime": "2026-05-06T08:01:23.000Z"
}

サーバーは書き込み後にファイルを stat し、実際のバイト数と mtime を返します。呼び出し側は bytes がアップロードサイズと一致 することを必ず確認してください。SDK の writeFile はこのチェックを 自動で行い、不一致なら throw します。

パス制約​

list / read / write の 3 エンドポイントは、/workspace 配下から 外れるパスを拒否します。シンボリックな脱出（/workspace/../etc）、 兄弟絶対パス（/etc/passwd, /proc/self/environ）、埋め込み NUL バイトは 400 INVALID_PATH を返します。入力は POSIX 正規化されて からチェックされるので、/workspace/./a/../b は /workspace/b に 正規化されて受理されます。

500 FILE_WRITE_BYTE_MISMATCH​

ディスク上のバイト数が受信したバイト数と異なるとき。経路上のプロキ シ／バッファ問題が典型例。リトライしてください。継続する場合は バグ報告を。

{
  "error": {
    "code": "FILE_WRITE_BYTE_MISMATCH",
    "message": "Wrote 3700 bytes to /workspace/foo but received 3712 bytes from client.",
    "retryable": true
  }
}