Create environment - - Alibaba Cloud Documentation Center

Creates a new cloud environment to host Agent sessions.

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT>`
`Content-Type`	Yes	`application/json`

Request body

Parameter	Type	Required	Description
`name`	string	Yes	The name of the environment.
`description`	string	No	A description of the environment.
`config`	object	Yes	The environment configuration.
`config.type`	string	Yes	The environment type. The value is always `"cloud"`.
`config.networking`	object	No	Network access configuration.
`config.networking.type`	string	No	The network type. Valid values are `"unrestricted"`, `"limited"`, and `"allowed_hosts"`.
`config.networking.allowed_hosts`	array	No	A list of hosts to allow network access to. Required when the network type is `"allowed_hosts"`.
`config.networking.allow_package_managers`	boolean	No	Whether to allow package managers to access the network.
`config.packages`	object	No	Specifies packages to pre-install.
`config.packages.apt`	array	No	A list of apt packages to pre-install.
`config.packages.pip`	array	No	A list of pip packages to pre-install.
`config.packages.npm`	array	No	A list of npm packages to pre-install.
`metadata`	object	No	A set of key-value pairs to associate with the environment.

Example request

curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-env",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "limited"
      },
      "packages": {
        "apt": ["curl"]
      }
    }
  }'

Example response

HTTP 201 Created

{
  "id": "env_019e3bb39b6774d8878cd0b9d237574b",
  "type": "environment",
  "name": "doc-test-env",
  "description": "",
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited"
    },
    "packages": {
      "apt": ["curl"]
    }
  },
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T15:28:07.017808Z",
  "updated_at": "2026-05-18T15:28:07.017808Z"
}

Response fields

Parameter	Type	Description
`id`	string	The unique identifier for the environment. The value is prefixed with `env_`.
`type`	string	The resource type. The value is always `"environment"`.
`name`	string	The name of the environment.
`description`	string	The description of the environment.
`status`	string	The status of the environment. Possible values are `"ready"` and `"archived"`.
`config`	object	The environment configuration.
`archived`	boolean	Indicates whether the environment is archived.
`archived_at`	string\|null	The ISO 8601 timestamp when the environment was archived. Returns `null` if the environment is not archived.
`created_at`	string	The ISO 8601 timestamp when the environment was created.
`updated_at`	string	The ISO 8601 timestamp when the environment was last updated.

Error codes

HTTP	Type	Description
400	`invalid_request_error`	The request parameters are invalid. For example, the `config.type` field is missing.
401	`authentication_error`	Authentication failed. The Personal Access Token (PAT) is invalid or has expired.
403	`permission_error`	You do not have permission to perform this action.
409	`conflict_error`	An environment with the same name already exists.