Get sandbox administration details

Read a manageable hosted sandbox and apply its saved network override configuration.

GET https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes/{id}

Before you call this API

Prepare an identity valid in the current environment, configured administrator eligibility, and an accessible authentication workspace. A workspace Owner or Genesis taas:admin does not automatically qualify as this administrator. The example uses a personal access token and exactly one X-Workspace-ID. See AI Studio.

A 404 can also mean a temporary or pooled resource, or a resource hidden by a business creation/deletion intent. One 404 does not prove that all remote resources, credentials, and ownership have been cleaned up. update_available:null retains its meaning of unknown.

Request parameters

curl --get "https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes/sandbox-example" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $AUTH_WORKSPACE_ID"

Parameter

Type

Required

Description

X-API-Key

string

Yes in this example

A personal access token valid in the current environment for a configured administrator. Confirm other ordinary authentication methods, such as Bearer, for the environment.

X-Workspace-ID

string

Yes

Exactly one nonempty authentication workspace header. This is not a target filter or the workspace whose quota is managed.

id

string

Yes

Sandbox ID in the path.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspace": {
      "id": "target-workspace",
      "owner_id": "owner-example"
    },
    "id": "sandbox-example",
    "workspace_id": "target-workspace",
    "user_id": "owner-example",
    "name": "示例沙箱",
    "phase": "ready",
    "edge_agent_id": "sandbox-example",
    "network_mode": "limited",
    "network_tools": [
      "curl"
    ],
    "egress_endpoints": [
      {
        "host": "example.com",
        "ports": [
          443
        ]
      }
    ],
    "spec": "small",
    "disk_gi": 10,
    "created_at": "2026-11-12T06:00:00Z",
    "updated_at": "2026-11-12T06:00:00Z",
    "update_available": null
  }
}

Field

Type

Description

code

string

OK on success.

msg

string

OK on success.

data

object

Success data.

data.workspace

object, optional

Optional administration projection. The current Provider supplies at least ID/owner_id; names and account names are not guaranteed.

data.id

string

Object identifier; currently the remote resource name for a sandbox.

data.workspace_id

string

Workspace that owns the resource, separate from the authentication header workspace.

data.user_id

string

User information recorded in remote resource labels.

data.name

string

Display name.

data.phase

string

unknown, provisioning, ready, error, or deleting. This is not the complete IAM cleanup state.

data.edge_agent_id

string

Associated execution environment identifier.

data.network_mode

string

Currently limited or unrestricted; may be empty when historical labels are absent. This update does not switch modes.

data.network_tools

string (array of strings), optional

Tool egress allowlist; may be omitted when empty.

data.egress_endpoints

object (array of objects), optional

Explicit host/ports egress allowlist; may be omitted when empty.

data.spec

string

Specification projection; may be empty when reading historical labels. Creation enums do not imply required fields for historical records.

data.disk_gi

integer

Disk size in GiB. May be 0 when remote labels are absent or unparseable; this does not permit creation with 0.

data.compute_resource_id

string, optional

Optional associated compute resource ID.

data.created_at

string

Creation time in RFC3339.

data.updated_at

string

Update time in RFC3339 format; not guaranteed to support concurrent version control.

data.update_available

boolean / null

boolean or null. null means insufficient information to compare the current image, not false.

See common objects for all public nested fields. Omission and null are described separately.

Error responses

{"code":"ErrParamInvalid","msg":"Bad Request"}

Field

Type

Description

code

string

Error code for the current phase.

msg

string

Error message; service-classified errors are usually localized.

HTTP / code

Conditions and handling

400 / ErrParamInvalid

Authentication workspace is missing, request decoding or integer parsing failed, or quota fields are invalid.

400 / SANDBOX_INVALID_SPEC

Service validation failed, for example for a list window or network tool. SPEC in the name does not restrict it to creation specifications.

403 / COMPUTE_RESOURCE_SPEC_FORBIDDEN

The current principal is not a configured administrator, or the identity does not match at the permission-check boundary.

503 / COMPUTE_RESOURCE_SPEC_ADMIN_UNAVAILABLE

Classified unavailability of administrator directory or authorization information.

404 / SANDBOX_NOT_FOUND

Unmanaged, temporary, or pooled resource; nonexistent resource; or a hidden creation/deletion phase.

503 / SANDBOX_IAM_UNAVAILABLE or SANDBOX_NETWORK_STORAGE_UNAVAILABLE

Lifecycle identity or network persistence dependencies are unavailable.

500 / SANDBOX_ERROR or ErrServer

Unclassified Provider or other failures, or localization failure. These do not all return 503.

See errors and recovery for the recovery phases.

Last updated on