创建 Worker 任务

方法: POST

端点: /api/v2/worker-tasks

认证: 支持 Authorization: Bearer <YOUR_API_KEY>、api-key: <YOUR_API_KEY> 和 ?token=<YOUR_API_KEY>。推荐优先使用 Bearer token。

在线试用

POST/api/v2/worker-tasksCreate worker task

AuthenticationRequired

Auth mode

API token

Stored only in this browser tab. Sent only to https://openapi.coreclaw.com.

Request BodyRequiredapplication/json

FieldTypeRequiredDescription

descriptionstringOptionalTask description.

inputanyRequiredWorker input payload. Put Worker form fields under `input.parameters.custom`. If left empty in the playground, it will try to load schema defaults before sending.

recipient_emailstringOptionalEmail address notified when the task finishes.

schedule_datestringOptionalStart date/time for the schedule. YYYY-MM-DD or YYYY-MM-DD HH:mm.

schedule_dayintegerOptionalDay of month for monthly schedule (1-31). Single-day compatibility field; prefer schedule_days. Constraints: range 1-31.

schedule_day_intervalintegerOptionalRepeat every N days for daily schedules. Default 1. Constraints: minimum 1.

schedule_daysstringOptionalDays of month for monthly schedules, comma-separated (e.g. 1,15,31).

schedule_enabledenum: 0, 1OptionalSchedule switch. 0=disabled, 1=enabled. Constraints: allowed values: `0`, `1`.

schedule_hour_intervalintegerOptionalRepeat every N hours for schedule_type=5. Required when type 5. Range 1-23. Constraints: range 1-23.

schedule_minute_intervalintegerOptionalRepeat every N minutes for schedule_type=6. Required when type 6. Range 1-59. Constraints: range 1-59.

schedule_once_datestringOptionalOnce schedule date in YYYY-MM-DD.

schedule_timestringOptionalSchedule time in HH:mm.

schedule_timezonestringOptionalIANA timezone for the schedule. Default Asia/Shanghai (e.g. UTC, America/New_York).

schedule_typeenum: 1, 2, 3, 4, 5, 6OptionalSchedule type. 1=daily, 2=weekly, 3=monthly, 4=once, 5=every N hours, 6=every N minutes. Constraints: allowed values: `1`, `2`, `3`, `4`, `5`, `6`.

schedule_weekdayenum: 1, 2, 3, 4, 5, 6, 7OptionalWeekday for weekly schedule. 1=Monday ... 7=Sunday. Single-day compatibility field; prefer schedule_weekdays. Constraints: range 1-7; allowed values: `1`, `2`, `3`, `4`, `5`, `6`, `7`.

schedule_weekdaysstringOptionalDays of week for weekly schedules, comma-separated (e.g. 1,3,5).

task_template_idintegerOptionalAssociated task template ID.

titlestringRequiredTask title.

versionstringOptionalOptional Worker version. Omit it unless you have confirmed a concrete available version for this Worker; not every Worker accepts `latest`.

worker_idstringRequiredWorker slug or path. Use owner~name for path values.

Request body (JSON)

什么时候使用这个接口

用于创建一个新的 Worker 任务模板，保存 Worker 标识、输入参数和可选的调度配置。

请求体

使用 Content-Type: application/json 发送请求体。表格中的必填/选填描述字段本身是否必须提供；整个请求体是否必填以在线试用区的 Request Body 标记为准。

字段	必填	类型	说明
`description`	否	`string`	任务模板描述，可选。
`input`	是	`any`	Worker 输入参数。Worker 表单字段通常放在 `input.parameters.custom` 下；应先读取该 Worker 的 input schema，再按 schema 构造。
`recipient_email`	否	`string`	任务结束时接收通知的邮箱。
`schedule_day`	否	`integer`	每月调度时的日期（1-31）。单日兼容字段；建议使用 `schedule_days`。
`schedule_day_interval`	否	`integer`	每天调度时每 N 天执行一次，默认 1。
`schedule_days`	否	`string`	每月调度时的日期列表，逗号分隔，如 `1,15,31`。
`schedule_enabled`	否	`enum: 0, 1`	调度开关：1 启用，0 关闭。
`schedule_hour_interval`	否	`integer`	`schedule_type=5` 时每 N 小时执行一次，必填。范围 1-23。
`schedule_minute_interval`	否	`integer`	`schedule_type=6` 时每 N 分钟执行一次，必填。范围 1-59。
`schedule_once_date`	否	`string`	单次调度的日期，格式 `YYYY-MM-DD`。
`schedule_time`	否	`string`	调度执行时间，格式 `HH:mm`。
`schedule_timezone`	否	`string`	调度所在 IANA 时区，默认 `Asia/Shanghai`（如 `UTC`、`America/New_York`）。
`schedule_type`	否	`enum: 1, 2, 3, 4, 5, 6`	调度类型：1=每天，2=每周，3=每月，4=单次，5=每 N 小时，6=每 N 分钟。
`schedule_weekday`	否	`enum: 1, 2, 3, 4, 5, 6, 7`	每周调度时的星期几（1=周一 … 7=周日）。单日兼容字段；建议使用 `schedule_weekdays`。
`schedule_weekdays`	否	`string`	每周调度时的星期几列表，逗号分隔，如 `1,3,5`。
`task_template_id`	否	`integer`	关联的任务模板 ID。
`title`	是	`string`	任务模板标题，用于展示和搜索。
`version`	否	`string`	可选 Worker 版本。除非已经确认该 Worker 存在某个具体可用版本，否则建议省略；并非所有 Worker 都接受 `latest` 作为显式版本值。
`worker_id`	是	`string`	Worker 标识。接受 Worker slug，也支持把 `owner/name` 写成 `owner~name`。

调度说明

启用调度时需将 schedule_enabled 设为 1，并同时提供 schedule_type 及该类型要求的字段：

`schedule_type`	含义	配套字段
`1`	每天	`schedule_time`；可选 `schedule_day_interval`（每 N 天，默认 1）。
`2`	每周	`schedule_time`；`schedule_weekdays`（如 `1,3,5`）或 `schedule_weekday`。
`3`	每月	`schedule_time`；`schedule_days`（如 `1,15,31`）或 `schedule_day`。
`4`	单次	`schedule_once_date`（`YYYY-MM-DD`）和 `schedule_time`。
`5`	每 N 小时	`schedule_hour_interval`（1-23）。
`6`	每 N 分钟	`schedule_minute_interval`（1-59）。

调度按 schedule_timezone（默认 Asia/Shanghai）解释。API 生成的 cron 为 console 兼容格式：带秒字段且带 CRON_TZ 前缀，例如 CRON_TZ=Asia/Shanghai 0 30 9 * * *。console 调度器只注册这种格式的调度。

JSON 示例

{
  "description": "Scrape Google Maps business records on a schedule.",
  "input": {
    "parameters": {
      "custom": {
        "keywords": [
          "coffee"
        ],
        "base_location": "New York,USA",
        "max_results": 1
      }
    }
  },
  "schedule_day": 1,
  "schedule_enabled": 0,
  "schedule_once_date": "2026-08-01",
  "schedule_time": "09:00",
  "schedule_type": 1,
  "schedule_weekday": 1,
  "title": "Google Maps Scraper (Task)",
  "worker_id": "coreclaw~google-maps-scraper"
}

每 5 分钟执行：

{
  "worker_id": "demo-worker",
  "title": "每 5 分钟执行的任务",
  "input": {
    "parameters": {
      "custom": {
        "keyword": "coffee"
      }
    }
  },
  "schedule_enabled": 1,
  "schedule_type": 6,
  "schedule_minute_interval": 5,
  "schedule_timezone": "Asia/Shanghai"
}

每 2 小时执行：

{
  "worker_id": "demo-worker",
  "title": "每 2 小时执行的任务",
  "schedule_enabled": 1,
  "schedule_type": 5,
  "schedule_hour_interval": 2,
  "schedule_timezone": "Asia/Shanghai"
}

请求示例

curl -X POST "https://openapi.coreclaw.com/api/v2/worker-tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"description":"Scrape Google Maps business records on a schedule.","input":{"parameters":{"custom":{"keywords":["coffee"],"base_location":"New York,USA","max_results":1}}},"schedule_day":1,"schedule_enabled":0,"schedule_once_date":"2026-08-01","schedule_time":"09:00","schedule_type":1,"schedule_weekday":1,"title":"Google Maps Scraper (Task)","worker_id":"coreclaw~google-maps-scraper"}'

响应示例

{
  "code": 0,
  "data": {
    "slug": "demo-task"
  },
  "message": "success",
  "request_id": "req-123"
}

注意事项

API v2 同时支持 Bearer token、旧版 api-key 请求头和 query token；新集成建议优先使用 Bearer token。
worker_id 接受 Worker slug，也支持把 owner/name 写成 owner~name。
应先读取 Worker 输入 schema 再构造 input，表单字段放在 input.parameters.custom 下；可用 GET /api/v2/workers/{workerId}/input-schema 读取 schema。
不启用调度时可省略全部 schedule 字段。
API 服务本身不执行定时任务；调度到点触发依赖 console 调度器正常启动。
API 生成的调度 cron 为 console 兼容格式：带秒字段且带 CRON_TZ 前缀（例如 CRON_TZ=Asia/Shanghai 0 30 9 * * *）。console 调度器只注册这种格式的调度。
在新调度字段引入之前创建的任务可能仍是 5 段 cron 或缺少新字段；需要重新保存定时配置或执行迁移，才能转换为当前格式。
调度的时区、夏令时、月末边界、错过执行与重叠运行等具体行为由平台管理，不属于公开 API 契约；如需依赖精确调度语义，请先咨询 Console 或支持。

HTTP 响应

HTTP 状态	应用代码	含义
`200`	`0`	请求成功。
`400`	`11000`	请求参数不合法。
`401`	`12001`	认证缺失或无效。
`404`	`11004`	目标资源不存在。
`422`	`11000`	请求语义或字段校验未通过。
`429`	`13000`	请求过于频繁。
`500`	`10000`	服务端内部错误。