# 暂停 Deployment

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volces.com/api/v3/deployments/{deployment_id}/pause`

临时停止 Deployment 的定时触发（例如维护期间），无需删除配置。暂停不会中断已受理或正在运行的 Session，暂停期间仍可调用立即运行接口手动触发。

对已暂停的 Deployment 重复调用暂停接口会返回 `InvalidAction` 错误。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### Path 参数

**deployment_id** `string` `必选` | Deployment ID

要暂停的 Deployment ID。

## 响应参数

**agent** `object` | Agent 引用

Deployment 固定使用的 Agent 和版本。

**id** `string` | Agent ID

`agent.id`

Deployment 使用的 Agent ID。

**type** `string` | 对象类型

`agent.type`

Agent 引用类型，固定为 `agent`。

**version** `integer` | Agent 版本

`agent.version`

Deployment 固定使用的 Agent 版本号。

**created_at** `string` | 创建时间

Deployment 创建时间，采用 RFC 3339 格式。

**environment_id** `string` | Environment ID

每次运行使用的 Environment ID。

**id** `string` | Deployment ID

Deployment 的唯一标识符，以 `depl-` 开头，形如 `depl-<14位时间戳>-<10位随机字符>`。

**initial_events** `object[]` | 初始事件

每次运行创建新 Session 后发送的启动事件模板。

用户消息 `object`

用户消息事件。每次运行创建 Session 后，平台会把该消息作为启动任务的第一条用户输入发送给 Agent。

**content** `object[]` | 消息内容

`initial_events.content`

消息内容块列表。支持文本、图片、文档和视频，字段结构与发送会话事件接口中的 `user.message` 一致；详情请参见 [会话事件结构参考](/docs/sessions-events-reference-v2)。

**type** `string` | 内容类型

`initial_events.content.type`

内容块类型。完整结构请参见 [会话事件结构参考](/docs/sessions-events-reference-v2)。可选值：`text`、`image`、`document`、`video`。

**type** `string` | 事件类型

`initial_events.type`

事件类型，固定为 `user.message`。

**name** `string` | 名称

Deployment 名称。

**resources** `object[]` | 挂载资源

每次运行创建 Session 时使用的资源配置。

**type** `string` | 资源类型

`resources.type`

资源类型。`file` 表示通过 Files API 上传并挂载到 Session 的文件；`memory_store` 表示挂载到 Session 的记忆库；`tos` 表示挂载到 Session 的 TOS 对象目录。

**access** `string` | 访问权限

`resources.access`

每次运行创建的 Session 对该资源的访问权限。`read_only` 表示智能体只能读取资源；`read_write` 表示智能体可以读取和修改支持写入的资源。

**file_id** `string` | 文件 ID

`resources.file_id`

当 *type* 为 `file` 时，表示要挂载到 Session 的文件 ID，通过 Files API 上传文件后获得。

**memory_store_id** `string` | 记忆库 ID

`resources.memory_store_id`

当 *type* 为 `memory_store` 时，表示要挂载到 Session 的记忆库 ID。

**mount_path** `string` | 挂载路径

`resources.mount_path`

该资源在每次运行创建的 Session 运行环境中的挂载路径。

**tos_bucket** `string` | TOS 存储桶

`resources.tos_bucket`

当 *type* 为 `tos` 时，表示待挂载目录所在的 TOS 存储桶名称。

**tos_key** `string` | TOS 目录前缀

`resources.tos_key`

当 *type* 为 `tos` 时，表示 TOS 中待挂载目录的对象前缀。前缀必须以 `/` 结尾。

**tos_region** `string` | TOS 地域

`resources.tos_region`

当 *type* 为 `tos` 时，表示源存储桶所在地域的 Region ID。

**status** `string` | 运行状态

Deployment 的调度状态。`paused` 不接受定时触发，但仍允许手动运行；`archived_at` 有值时已归档，无论该字段取值如何都不再接受任何触发。取值：`active` / `paused`。

**tags** `object[]` | 标签

Deployment 标签列表。

**key** `string` | 标签键

`tags.key`

标签键，用于标识分类维度。

**value** `string` | 标签值

`tags.value`

标签值，用于记录该分类维度的具体内容。仅标签键不能为空。

**type** `string` | 对象类型

对象类型，固定为 `deployment`。

**updated_at** `string` | 更新时间

Deployment 最近更新时间，采用 RFC 3339 格式。

**vault_ids** `string[]` | 保管库 ID

每次运行创建 Session 时绑定的 Vault ID 列表。

**archived_at** `string` | 归档时间

Deployment 归档时间，采用 RFC 3339 格式。未归档时不返回该字段。

**description** `string` | 描述

Deployment 描述。未设置时不返回该字段。

**paused_reason** `object` | 暂停原因

Deployment 暂停的原因。*status* 为 `active` 时不返回该字段。

**type** `string` | 暂停类型

`paused_reason.type`

暂停原因类型。`manual` 表示调用暂停接口；`error` 表示 Run 遇到不可恢复错误后自动暂停。

**error** `object` | 暂停错误

`paused_reason.error`

自动暂停时的错误信息。*type* 为 `manual` 时不返回该字段。

**message** `string` | 错误信息

`paused_reason.error.message`

用于定位失败原因的可读信息。

**type** `string` | 错误类型

`paused_reason.error.type`

错误分类。

**schedule** `object` | 定时计划

定时触发计划。仅支持手动运行时不返回该字段。

**expression** `string` | Cron 表达式

`schedule.expression`

五段式 cron 表达式，格式为 `分钟 小时 日期 月份 星期`。例如 `0 9 * * 1-5` 表示在配置时区的工作日 09:00 触发；不支持秒、年份和 `@daily` 等快捷写法。

**timezone** `string` | 时区

`schedule.timezone`

cron 表达式使用的 IANA 时区，例如 `Asia/Shanghai`、`UTC` 或 `America/New_York`。平台按该时区计算计划触发时间。

**type** `string` | 计划类型

`schedule.type`

计划类型，固定为 `cron`。

**upcoming_runs_at** `string[]` | 后续计划时间

`schedule.upcoming_runs_at`

接下来最多 5 个理论计划时间，采用 RFC 3339 格式，不包含调度抖动。Deployment 暂停时仍返回按当前计划计算的时间；归档后返回空数组。

**last_run_at** `string` | 最近定时运行时间

`schedule.last_run_at`

最近一次定时 Run 的理论计划时间，采用 RFC 3339 格式。尚未定时触发时不返回该字段；手动 Run 不更新该字段。


## 代码示例

## 暂停 Deployment

### cURL


#### Request

```bash
curl -sS --fail-with-body -X POST "https://ark.cn-beijing.volces.com/api/v3/deployments/$DEPLOYMENT_ID/pause" \
  -H "Authorization: Bearer $ARK_API_KEY"
```

#### Response

```
{
  "type": "deployment",
  "id": "depl-20261020090000-a1b2c",
  "name": "工作日业务日报",
  "description": "汇总昨日业务数据并生成日报",
  "agent": {
    "type": "agent",
    "id": "agent-20261018090000-a1b2c",
    "version": 3
  },
  "environment_id": "env-20261018090500-d3e4f",
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "分析昨日业务数据，生成日报并列出异常指标。"
        }
      ]
    }
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "Asia/Shanghai",
    "upcoming_runs_at": [
      "2026-10-21T01:00:00Z",
      "2026-10-22T01:00:00Z"
    ]
  },
  "status": "paused",
  "resources": [],
  "vault_ids": [],
  "tags": [
    {
      "key": "business",
      "value": "daily-report"
    }
  ],
  "created_at": "2026-10-20T01:00:00Z",
  "updated_at": "2026-10-20T01:15:00Z",
  "paused_reason": {
    "type": "manual"
  }
}
```