Create Deployment

Prerequisites

Endpoint and authentication configured. For details, see Overview and authentication.

Endpoint

POST /deployments

Request body

Field	Required	Type	Description
`name`	Yes	string	Deployment name, max 256 characters
`description`	No	string	Description of the deployment's purpose
`agent`	Yes	object	Associated Agent. Contains `id` (string, required) and `version` (integer; locks to a specific Agent version; omit to use the latest version)
`environment_id`	No	string	Associated Environment ID
`schedule`	No	object	Schedule trigger configuration; omit for manual trigger. Contains `type` (`cron`), `expression` (cron expression), and `timezone`
`initial_events`	Yes	array<object>	Initial events sent to the Agent on trigger, 1–50 items
`resources`	No	array<object>	Mounted file resources. Each item contains `type` (`file`), `file_id`, and `mount_path`
`vault_ids`	No	array<string>	Associated Vault ID list
`metadata`	No	object	Custom key-value pairs

Request example

curl -X POST "$AGENTSTUDIO_URL/deployments" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-order-summary",
    "agent": {
      "id": "agent_xxx",
      "version": 12
    },
    "environment_id": "env_xxx",
    "schedule": {
      "type": "cron",
      "expression": "0 9 * * 1-5",
      "timezone": "Asia/Shanghai"
    },
    "initial_events": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Summarize yesterday's order data"
          }
        ]
      }
    ]
  }'

Response example

{
  "id": "depl_xxx",
  "type": "deployment",
  "name": "daily-order-summary",
  "status": "active",
  "agent": {
    "id": "agent_xxx",
    "version": 12
  },
  "environment_id": "env_xxx",
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "Asia/Shanghai",
    "last_run_at": null,
    "next_run_at": "2026-07-28T01:00:00Z"
  },
  "initial_events": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize yesterday's order data"
        }
      ]
    }
  ],
  "resources": [],
  "vault_ids": [],
  "metadata": {},
  "paused_reason": null,
  "archived_at": null,
  "created_at": "2026-07-28T01:00:00Z",
  "updated_at": "2026-07-28T01:00:00Z",
  "request_id": "req_xxx"
}

Response fields

Field	Type	Description
`id`	string	Deployment ID
`type`	string	Always `deployment`
`name`	string	Deployment name
`description`	string	Deployment purpose description
`agent`	object	Snapshot of the associated Agent at the locked version; contains `id`, `type`, `version`, `name`, `description`, `model`, `system`, `tools`, `skills`, `mcp_servers`
`environment_id`	string	Associated Environment ID
`schedule`	object	Schedule trigger configuration. Contains `type`, `expression`, `timezone`, `last_run_at` (string \| null), `next_run_at` (string \| null)
`initial_events`	array<object>	Initial events sent to the Agent on trigger
`resources`	array<object>	Mounted file resources; each item has `type`, `file_id`, `mount_path`
`vault_ids`	array<string>	Associated Vault ID list
`metadata`	object	Custom key-value pairs
`status`	string	Deployment status: `active` or `paused`
`paused_reason`	object \| null	Pause reason; returned only when the status is `paused`
`archived_at`	string \| null	Archive timestamp; `null` if not archived
`created_at`	string	Creation time, ISO 8601
`updated_at`	string	Last update time, ISO 8601
`request_id`	string	Unique request identifier

Error codes

HTTP status	Error code	Description
400	`InvalidParameter`	Required parameter missing or invalid
401	`InvalidApiKey`	Invalid API key provided

​Prerequisites

​Endpoint

​Request body

​Request example

​Response example

​Response fields

​Error codes

Prerequisites

Endpoint

Request body

Request example

Response example

Response fields

Error codes