Create Deployment

Updated at:

Creates a new Deployment, binding an Agent and configuring the trigger method. The request body carries the Agent reference, schedule, and initial events; the response returns the complete Deployment object.

Prerequisites

Endpoint and authentication configured. For details, see API overview and authentication.

Endpoint

POST /deployments

Request body

FieldRequiredTypeDescription
nameYesstringDeployment name, max 256 characters
descriptionNostringDescription of the deployment purpose
agentYesobjectAssociated Agent
environment_idNostringAssociated Environment ID
scheduleNoobjectScheduled trigger configuration; omit for manual trigger
initial_eventsYesarray<object>List of initial events sent to the Agent on trigger, 1-50 items
resourcesNoarray<object>List of mounted file resources
vault_idsNoarray<string>Associated Vault ID list
metadataNoobjectBusiness 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 order data from yesterday"
          }
        ]
      }
    ]
  }'

Response

{
  "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 order data from yesterday"
        }
      ]
    }
  ],
  "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

FieldTypeDescription
idstringDeployment ID
typestringFixed value deployment
namestringDeployment name
descriptionstringDescription of the deployment purpose
agentobject—
environment_idstring—
scheduleobject—
initial_eventsarray<object>—
resourcesarray<object>—
vault_idsarray<string>—
metadataobject—
statusstring—
paused_reasonobject | nullPause reason, returned only when the status is paused
archived_atstring | null—
created_atstring—
updated_atstring—
request_idstringUnique identifier of this request, include it when troubleshooting

Error codes

HTTP statusError codeDescription
400InvalidParameterRequired parameter missing or invalid.
401InvalidApiKeyInvalid API-key provided.