Skip to Content
API 參考API 端點目錄

API 端點目錄

路徑省略前綴 {BASE}/private/module/sandbox。所有端點經 get_sandbox_principal；未授權回 404。

公司設定

方法 + 路徑用途認證請求回應
GET /settings讀公司 sandbox 設定company manager—SandboxCompanySettingsResponse
PUT /settings更新保留天數 + 允許區域company managerSandboxCompanySettingsUpdateSandboxCompanySettingsResponse

SandboxCompanySettingsUpdate：run_content_retention_days(1..365)、unreferenced_image_retention_days(1..90)、allowed_regions(≥1)、policy_version(樂觀鎖 CAS)。CAS 不符 → 409。

環境 / 版本 / 建置（前綴 /environments）

方法 + 路徑用途請求回應
GET /environments列環境（含系統策展）q: page_size,page_token,lifecycleSandboxEnvironmentListResponse
POST /environments建環境SandboxEnvironmentCreateRequestSandboxEnvironmentResponse
GET /environments/{id}取環境—SandboxEnvironmentResponse
PATCH /environments/{id}改名稱/描述SandboxEnvironmentUpdateRequestSandboxEnvironmentResponse
POST /environments/{id}/archive歸檔環境—SandboxEnvironmentResponse
GET /environments/{id}/versions列版本q: page_size,page_token,lifecycleSandboxEnvironmentVersionListResponse
POST /environments/{id}/versions建不可變版本SandboxEnvironmentVersionCreateRequestSandboxEnvironmentVersionResponse
GET /environments/{id}/versions/{vid}取版本（輪詢 ready）—SandboxEnvironmentVersionResponse
POST /environments/{id}/versions/{vid}/archive歸檔版本—SandboxEnvironmentVersionResponse
POST /environments/{id}/versions/{vid}/builds佇列一次建置SandboxBuildAttemptCreateRequestSandboxBuildAttemptResponse
GET /environments/{id}/versions/{vid}/builds列建置q: page_size,page_tokenSandboxBuildAttemptListResponse
GET /environments/{id}/versions/{vid}/builds/{aid}取建置（輪詢）—SandboxBuildAttemptResponse
POST /environments/{id}/versions/{vid}/builds/{aid}/cancel取消建置—SandboxBuildAttemptResponse
POST /environments/{id}/versions/{vid}/retry-build重試失敗建置—SandboxBuildAttemptResponse
POST /environments/{id}/versions/{vid}/retry-provisioning重試區域佈建—SandboxEnvironmentVersionResponse

請求欄位

  • SandboxEnvironmentCreateRequest：name(1–256)、description(≤2048)。
  • SandboxEnvironmentVersionCreateRequest：source_digest(必填, ^sha256:[0-9a-f]{64}$)、source_ref(≤1024)、resource_profile(standard/performance/large/xlarge)。
  • SandboxBuildAttemptCreateRequest：build_region(≤64, 預設 asia-east1)、build_profile(≤32, 預設 standard)。

回應重點欄位

  • SandboxEnvironmentVersionResponse：id、environment_id、version_number、state、security_state、resource_profile、capacity_retained、ready_at?…；擁有者專屬：source_digest?、source_ref?（借用視圖省略）。
  • SandboxBuildAttemptResponse：id、environment_version_id、attempt_number、status、phase、terminal_class、stage_code、error_code、build_region、build_profile、report_total_bytes（無任何憑證/金鑰）。

任務 / 版本 / 分享（前綴 /tasks）

方法 + 路徑用途請求回應
GET /tasks列任務q: page_size,page_token,lifecycleSandboxTaskListResponse
POST /tasks建任務（draft）SandboxTaskCreateRequestSandboxTaskResponse
GET /tasks/{id}取任務—SandboxTaskResponse
GET /tasks/{id}/versions列版本q: 分頁,lifecycleSandboxTaskVersionListResponse
POST /tasks/{id}/versions建 draft 版本SandboxTaskVersionCreateRequestSandboxTaskVersionResponse
GET /tasks/{id}/versions/{vid}取版本—SandboxTaskVersionResponse
PATCH /tasks/{id}/versions/{vid}改 draft 版本SandboxTaskVersionUpdateRequestSandboxTaskVersionResponse
POST /tasks/{id}/versions/{vid}/publish發布版本—SandboxTaskVersionResponse
POST /tasks/{id}/versions/{vid}/archive歸檔版本—SandboxTaskVersionResponse
GET /tasks/{id}/shares列分享（預設 lifecycle=all）q: 分頁,lifecycleSandboxShareGrantListResponse
POST /tasks/{id}/shares分享給部門/公司/聊天室SandboxShareCreateRequestSandboxShareGrantResponse
POST /tasks/{id}/shares/{gid}/revoke撤銷分享SandboxShareRevokeRequestSandboxShareGrantResponse

請求欄位

  • SandboxTaskCreateRequest：name(1–256)、description(≤2048)、owner_scope(chatroom/department/company)、owner_id(pattern)、agent_enabled(預設 false)。
  • SandboxTaskVersionCreateRequest：environment_version_id、startup_script(≤1MiB)、work_script(≤1MiB)、ordinary_env?、input_instructions?(≤64KiB)、input_example?(≤64KiB)、timeout_seconds(預設1800)、secret_slot_declarations?、requires_confirmation(預設 false)、output_policy?。
  • SandboxShareCreateRequest：target_kind、target_id。SandboxShareRevokeRequest：reason(≤512)。

回應重點：SandboxTaskVersionResponse 含 state、content_state、requires_confirmation、secret_slot_names[]、update_available；擁有者專屬：startup_script?、work_script?、ordinary_env?、secret_slot_declarations?（借用視圖省略）。

綁定（前綴 /bindings）

方法 + 路徑用途請求回應
POST /bindings把已發布版本釘進聊天室SandboxBindingCreateRequestSandboxBindingResponse
GET /bindings/{id}取綁定—SandboxBindingResponse
POST /bindings/{id}/accept-version明確升級到新版本SandboxBindingAcceptVersionRequestSandboxBindingResponse
POST /bindings/{id}/revoke撤銷綁定SandboxBindingRevokeRequestSandboxBindingResponse

SandboxBindingCreateRequest：chatroom_id、task_id、task_version_id。回應含 update_available、authority_applicable、state。

Secret / 授權（路徑 /secrets*、/secret-approvals*）

需 consumer-scope manager；建立/輪替/撤銷要帶 Idempotency-Key；值永不回顯。

方法 + 路徑用途請求回應
POST /secrets建立 secret 值SandboxSecretWriteRequestSandboxSecretOperationResponse
POST /secrets/rotate輪替值SandboxSecretWriteRequestSandboxSecretOperationResponse
POST /secrets/revoke撤銷值SandboxSecretRevokeRequestSandboxSecretOperationResponse
GET /secrets/{id}取遮蔽 binding—SandboxSecretBindingResponse
POST /secret-approvals借用授權（精確 digest）SandboxSecretApprovalCreateRequestSandboxSecretApprovalResponse
POST /secret-approvals/{id}/revoke撤銷授權SandboxSecretApprovalRevokeRequestSandboxSecretApprovalResponse

SandboxSecretWriteRequest：consumer_scope、consumer_id、task_id、slot_name、value(1..64KiB, 不記錄)。SandboxSecretApprovalCreateRequest：task_version_digest(sha256:)、slot_names(1..100)、risk_accepted: true(必為 true)。digest 不符 → 409。

執行（路徑帶 /chatrooms/{chatroom_id}/...）

方法 + 路徑用途受限 key請求回應
GET /chatrooms/{cid}/menu列可執行任務✅q: page_size(預設50)SandboxMenuResponse
POST /chatrooms/{cid}/runs提交手動執行✅SandboxManualRunSubmitRequest + Idempotency-KeySandboxRunDetailResponse
GET /chatrooms/{cid}/runs列 run（受限只見自己）✅q: page_size,status[]SandboxRunListResponse
GET /chatrooms/{cid}/runs/{rid}取 run 狀態（輪詢）✅—SandboxRunDetailResponse
GET /chatrooms/{cid}/runs/{rid}/content內容旗標（無本體）✅—SandboxRunContentResponse
GET /chatrooms/{cid}/runs/{rid}/artifacts列產出物✅q: page_size,lifecycleSandboxRunArtifactListResponse
POST /chatrooms/{cid}/runs/{rid}/artifacts/{aid}/download授權並發下載 capability✅—SandboxArtifactDownloadCapabilityResponse
POST /chatrooms/{cid}/runs/{rid}/cancel取消自己的 run✅—SandboxRunDetailResponse
POST /chatrooms/{cid}/runs/{rid}/retry以新身分重試終態 run❌ 404Idempotency-KeySandboxRunDetailResponse
POST /chatrooms/{cid}/quick-runmanager-only 原子 quick run❌ 404SandboxQuickRunRequest + Idempotency-KeySandboxQuickRunResponse

請求欄位

  • SandboxManualRunSubmitRequest：task_version_id、input(canonical JSON)、timeout_seconds?。
  • SandboxQuickRunRequest：name、environment_version_id、startup_script、work_script、ordinary_env、input、timeout_seconds(必填)。

回應重點

  • SandboxRunDetailResponse：id、chatroom_id、status、resource_profile、principal_type、auth_method、task_id、task_version_id、timeout_seconds、submission_source、input_digest、retry_of_run_id、error_code、queued_at?、terminal_at?。
  • SandboxRunContentResponse：state、has_input、has_output、has_log、has_artifact_bundle、input_digest（只有旗標）。
  • SandboxArtifactDownloadCapabilityResponse：capability_token、expires_at、content_type、content_disposition、x_content_type_options: nosniff（無原始 key/URL）。

不對前端開放（僅供理解）

  • /sandbox-control/*：控制面（OIDC + capability），include_in_schema=False。
  • /root/sandbox/*：營運/root。

欄位或路徑若與後端不符，以 src/routers/private/modules/sandbox/ 與 src/schemas/sandbox.py 為準。

Last updated on
總覽狀態列舉值