接口參考

檔案

上載給 Agent 的檔案與 Agent 交付的檔案。

檔案在沙箱裡如何出現、Agent 如何交付，見檔案的輸入與交付。

POST/v1/files

上載檔案

權限: files:write
限流: 60 次/分鐘
成功: 201

請求體為 multipart/form-data，檔案放在 file 欄位中，每次只能上載一個。單個檔案最大 100 MiB。上載的檔案屬於項目，不屬於某個會話，可以在多個會話的訊息中重複使用。

表單欄位

filefile必填

檔案內容。檔名取客戶端提交的檔名中最後一段，例如 C:\data\sales.csv 保存為 sales.csv；長度 1–255 字元，不能含控制字元。

回應：檔案物件

idstring

檔案 ID，file_…。

filenamestring

檔名。

mime_typestring

檔案類型，由平台根據副檔名判斷，無法判斷時為 application/octet-stream。

size_bytesinteger

大小，單位位元組。

originstring

UPLOAD（你上載的）或 OUTPUT（Agent 交付的）。

session_idstring | null

Agent 交付檔案時所在的會話；上載的檔案為 null。

created_atstring

建立時間。

錯誤

狀態碼	type	原因
413	`file_too_large`	檔案超過 100 MiB；`details.max_bytes` 給出上限。
413	`content_too_large`	整個請求體超過上限。
400	`bad_request`	請求中不止一個檔案或欄位；每次只能上載一個檔案。
422	`validation_error`	缺少 `file` 欄位，或它不是檔案。
422	`invalid_filename`	檔名為空，或過長，或含控制字元。
502	`storage_error`	檔案儲存暫時不可用，可以重試。

請求

curl -s "$AXON_API/files" -H "Authorization: Bearer $AXON_KEY" -F "file=@sales.csv"

回應

{
  "id": "file_0c7d2e5f9a1b4c3d8e6f2a4b7c9d1e3f",
  "filename": "sales.csv",
  "mime_type": "text/csv",
  "size_bytes": 48213,
  "origin": "UPLOAD",
  "session_id": null,
  "created_at": "2026-10-08T02:14:51.207731Z"
}

GET/v1/files

檔案列表

權限: files:read
成功: 200

按建立時間從新到舊返回項目中的檔案，分頁方式見分頁。每個元素是檔案物件。

查詢參數

limitinteger

每頁條數，1–100，預設 20。

cursorstring

上一頁的 meta.next_cursor。

session_idstring

只返回該會話中 Agent 交付的檔案。

originstring

UPLOAD（你上載的）或 OUTPUT（Agent 交付的）。

請求

curl -s "$AXON_API/files?session_id=$SESSION" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "items": [
    {
      "id": "file_7b1e4a2c9d3f4e5a8b6c0d1e2f3a4b5c",
      "filename": "summary.csv",
      "mime_type": "text/csv",
      "size_bytes": 1532,
      "origin": "OUTPUT",
      "session_id": "ses_8d0f3b6a2c4e4f1a9b7c5d3e1f2a4b6c",
      "created_at": "2026-10-08T02:16:40.118240Z"
    }
  ],
  "meta": {"next_cursor": null}
}

GET/v1/files/{file_id}

查詢檔案

權限: files:read
成功: 200

返回檔案物件。

路徑參數

file_idstring必填

檔案 ID。

錯誤

狀態碼	type	原因
404	`file_not_found`	檔案不存在、已刪除或屬於其他項目。

請求

curl -s "$AXON_API/files/$FILE" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "id": "file_0c7d2e5f9a1b4c3d8e6f2a4b7c9d1e3f",
  "filename": "sales.csv",
  "mime_type": "text/csv",
  "size_bytes": 48213,
  "origin": "UPLOAD",
  "session_id": null,
  "created_at": "2026-10-08T02:14:51.207731Z"
}

GET/v1/files/{file_id}/content

下載檔案

權限: files:read
成功: 307

返回 307 跳轉，Location 是一個帶簽名、有效期 1 小時的下載連結。訪問它不需要 API Key，下載時檔名為 filename。

curl 要加 -L；Python httpx 要設 follow_redirects=True；Node.js 的 fetch 預設跟隨跳轉。
主流 HTTP 客戶端跟隨跳轉到其他域名時不會轉發 Authorization 頭，下載連結也不需要它。
下載連結過期後，再調用一次本接口即可拿到新的。如果要把檔案交給你的終端用戶，可以由伺服器端把這個地址轉給他們，在有效期內直接下載。

路徑參數

file_idstring必填

檔案 ID。

錯誤

狀態碼	type	原因
404	`file_not_found`	檔案不存在、已刪除或屬於其他項目。
502	`storage_error`	檔案儲存暫時不可用，可以重試。

請求

curl -sL "$AXON_API/files/$FILE/content" -H "Authorization: Bearer $AXON_KEY" -o summary.csv

回應頭

HTTP/1.1 307 Temporary Redirect
Location: https://<bucket>.<oss-endpoint>/files/file_0c7d…?OSSAccessKeyId=…&Expires=1791971048&Signature=…&response-content-disposition=attachment%3B%20filename%3D%22sales.csv%22…

DELETE/v1/files/{file_id}

刪除檔案

權限: files:write
限流: 60 次/分鐘
成功: 204（無回應體）

刪除後檔案不再出現在列表中，下載返回 404 file_not_found。已經發出的事件中的 files 保持不變，仍然記錄發送當時的檔案資訊。

路徑參數

file_idstring必填

檔案 ID。

錯誤

狀態碼	type	原因
404	`file_not_found`	檔案不存在、已刪除或屬於其他項目。

請求

curl -s -X DELETE "$AXON_API/files/$FILE" -H "Authorization: Bearer $AXON_KEY"

回應

204 No Content