跳转到内容
CoreClaw Logo CoreClaw

运行 Worker

方法: POST

端点: /api/v2/workers/{workerId}/runs

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

在线试用

Section titled “在线试用”
POST/api/v2/workers/{workerId}/runsRun worker
AuthenticationRequired

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

Parameters
path · stringRequired

Worker slug or path. You may paste `owner/name`; the playground sends it as `owner~name` for path values.

Request BodyRequiredapplication/json
FieldTypeRequiredDescription
callback_urlstringOptionalCallback URL. When provided, CoreClaw sends a POST request after the run status changes or finishes.
inputanyOptionalWorker 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.
is_asyncbooleanOptional`true` submits asynchronously and does not wait for execution results; `false` waits for the run to finish. Defaults to `true`.
limitintegerOptionalResult limit for synchronous run. Constraints: default `20`; range 1-100.
offsetintegerOptionalResult offset for synchronous run. Constraints: default `0`; minimum 0.
versionstringOptionalOptional Worker version. Omit it unless you have confirmed a concrete available version for this Worker; not every Worker accepts `latest`.
Request body (JSON)

什么时候使用这个接口

Section titled “什么时候使用这个接口”

用于按新的输入参数直接启动 Worker 运行，而不是运行已保存任务。

标识符说明

Section titled “标识符说明”
  • workerId / worker_id 支持 Worker slug，也支持把路径 owner/name 写成 owner~name。

路径参数

Section titled “路径参数”
参数必填类型说明
workerId是stringWorker slug 或 path；如果使用 owner/name 路径，请写成 owner~name。

请求体

Section titled “请求体”

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

字段必填类型说明
callback_url否string回调地址。传入后，CoreClaw 会在运行状态变化或结束时向该地址发送 POST 请求。
input否anyWorker 输入参数。Worker 表单字段通常放在 input.parameters.custom 下；应先读取该 Worker 的 input schema，再按 schema 构造。
is_async否booleantrue 表示异步提交，不等待执行结果；false 表示等待执行结果，直到运行完成。默认 true。
limit否integer同步运行或重跑时返回的结果窗口大小；仅影响同步响应中附带的结果数量，不影响完整结果集。 约束：默认 20；范围 1-100。
offset否integer同步运行或重跑时返回结果窗口的起始偏移；从 0 开始。 约束：默认 0；最小 0。
version否string可选 Worker 版本。除非已经确认该 Worker 存在某个具体可用版本，否则建议省略；并非所有 Worker 都接受 latest 作为显式版本值。

JSON 示例

Section titled “JSON 示例”
{
  "input": {
    "parameters": {
      "custom": {
        "keywords": [
          "coffee"
        ],
        "base_location": "New York,USA",
        "max_results": 1
      }
    }
  },
  "is_async": true,
  "limit": 20,
  "offset": 0
}

运行模式

Section titled “运行模式”
  • is_async: true 表示异步提交运行，不等待执行结果。响应会返回 data.run_slug，随后用运行详情、日志和结果接口轮询。
  • is_async: false 表示等待执行结果，等价于等待运行执行完成的 run-and-wait；可配合 offset / limit 直接获取同步运行返回的数据窗口。

请求示例

Section titled “请求示例”
Terminal window
curl -X POST "https://openapi.coreclaw.com/api/v2/workers/YOUR_WORKER_ID/runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"input":{"parameters":{"custom":{"keywords":["coffee"],"base_location":"New York,USA","max_results":1}}},"is_async":true,"limit":20,"offset":0}'

响应示例

Section titled “响应示例”
{
  "code": 0,
  "data": {
    "run_slug": "01KKDXV2G26BT7NH4ZQR2R4NPZ"
  },
  "message": "success",
  "request_id": "req-123"
}

注意事项

Section titled “注意事项”
  • API v2 同时支持 Bearer token、旧版 api-key 请求头和 query token；新集成建议优先使用 Bearer token。
  • 应先读取 Worker 输入 schema，再构造 input；不同 Worker 的输入字段不一定相同。
  • offset 和 limit 只控制同步返回的结果窗口，不改变 Worker 实际产生的完整结果集。
  • version 是可选字段；除非已经确认具体版本可用，否则建议省略。并非所有 Worker 都接受 latest 作为显式版本值。
  • 传入 callback_url 后，CoreClaw 会在运行状态变化或结束时发送回调通知。详见回调通知。

HTTP 响应

Section titled “HTTP 响应”
HTTP 状态应用代码含义
2000请求成功。
40011000请求参数不合法。
40112001认证缺失或无效。
40411004目标资源不存在。
42211000请求语义或字段校验未通过。
42913000请求过于频繁。
50010000服务端内部错误。