跳转到主要内容
POST /api/v1/cloud/environments/{environment_id}/work/{work_id}/heartbeat 为 work item 发送 heartbeat，并延长 worker lease。第一次成功 heartbeat 会将 starting item 推进到 active。 建议使用 expected_last_heartbeat 做乐观 lease 所有权校验。如果该 item 已被其他 worker 接管，接口会返回 412。

​
路径参数

参数类型说明
environment_idstringEnvironment ID，前缀为 env_
work_idstringWork item ID，前缀为 work_

​
请求头

头部必选说明
Authorization是Bearer $QODER_PAT

​
查询参数

参数类型必选说明
expected_last_heartbeatstring否NO_HEARTBEAT 或服务端上一次返回的 heartbeat 时间戳。省略时表示无条件更新
desired_ttl_secondsinteger否期望的 lease TTL。必须为正整数；服务端会将接受值限制在 10 到 600 秒范围内

​
示例请求

curl -X POST "https://api.qoder.com/api/v1/cloud/environments/env_019e64e01a137caf953ac2ac7b42ec5c/work/work_019f3be4fd2475d9a784bf2c739e1194/heartbeat?expected_last_heartbeat=NO_HEARTBEAT&desired_ttl_seconds=60" \
  -H "Authorization: Bearer $QODER_PAT"

​
示例响应

HTTP 200 OK 
{
  "type": "work_heartbeat",
  "last_heartbeat": "2026-07-01T08:15:06.120394Z",
  "lease_extended": true,
  "state": "active",
  "ttl_seconds": 60
}

​
响应字段

返回 Work heartbeat 对象。

​
错误码

HTTPtype触发条件
400invalid_request_errordesired_ttl_seconds 不是正整数
400invalid_request_errorexpected_last_heartbeat 既不是 NO_HEARTBEAT，也不是 RFC 3339 时间戳
400invalid_request_errorEnvironment 不是 self_hosted
401authentication_errorPAT 无效或过期
403permission_error无权限执行此操作
404not_found_errorEnvironment 或 work item 不存在
409invalid_request_errorWork item 为 queued 或 stopped，不能 heartbeat
412precondition_failed_errorexpected_last_heartbeat 与当前 lease owner 不匹配
完整错误信封格式见 错误参考。

​
相关

云端环境

选择 Agent 运行的容器、网络与依赖。