Skip to content

Commit 883b72d

Browse files
kael-odinkael-odin
committed
docs: remove page_index/page_size from scraper/run, correct custom source, clarify callback_url requirements per endpoint
1 parent 999be45 commit 883b72d

6 files changed

Lines changed: 61 additions & 49 deletions

File tree

‎src/content/docs/api/worker/run.md‎

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,7 @@ Every Worker has its own `scraper_slug`. You can get it from the Worker page, or
4545
}
4646
},
4747
"callback_url": "https://your-callback.example.com/webhook",
48-
"is_async": true,
49-
"page_index": 1,
50-
"page_size": 10
48+
"is_async": true
5149
}
5250
```
5351

@@ -59,9 +57,7 @@ Every Worker has its own `scraper_slug`. You can get it from the Worker page, or
5957
| version | Yes | string | Worker version |
6058
| input | Yes | object | Input parameters |
6159
| is_async | Yes | boolean | `true`: async execution (default), `false`: sync execution (waits for completion) |
62-
| page_index | Yes | number | Result page number, default `1` |
63-
| page_size | Yes | number | Results per page, default `10`, max `1000` |
64-
| callback_url | Conditional | string | Callback URL for receiving run results. **Required** when `is_async=true`, optional when `is_async=false`. |
60+
| callback_url | No | string | Callback URL for receiving run results |
6561

6662
#### `system` Parameters
6763

@@ -76,17 +72,19 @@ Every Worker has its own `scraper_slug`. You can get it from the Worker page, or
7672

7773
#### `custom` Parameters
7874

79-
Build `input.parameters.custom` from the Worker's `input_schema.json`.
75+
`input.parameters.custom` is not a fixed schema — it varies per Worker. Use one of these approaches to find the exact fields:
8076

81-
- Use each `properties[].name` as the key in `custom`
82-
- Match the declared `type`, nested structure, and array shape
83-
- Provide all fields whose schema sets `required: true`
84-
- An empty or schema-mismatched `custom` object returns `400 Bad Request`
85-
86-
To find the exact `custom` fields for a specific Worker, open the Worker in the [CoreClaw Console](https://console.coreclaw.com), go to the **Input** tab, click the **API** button in the top-right corner, and select **API clients** to view ready-to-use code snippets.
77+
- **API**: Call `GET /api/scraper?slug=<scraper_slug>` and read `data.parameters.custom` from the response. Each entry in `properties[]` maps to a field in `input.parameters.custom`.
78+
- **Console**: Open the Worker in the [CoreClaw Console](https://console.coreclaw.com), go to the **Input** tab, click the **API** button in the top-right corner, and select **API clients** to view ready-to-use code snippets.
8779

8880
![API clients button in Worker Input tab](@/assets/docs/74.png)
8981

82+
When building `custom`:
83+
- Use each `properties[].name` as the key
84+
- Match the declared `type`, nested structure, and array shape
85+
- Provide all fields where `required: true`
86+
- An empty or schema-mismatched `custom` object returns `400 Bad Request`
87+
9088
### How to get `version`
9189

9290
You can get the Worker version from:
@@ -97,9 +95,9 @@ You can get the Worker version from:
9795

9896
## Validation behavior
9997

100-
- **`callback_url` and `is_async`**: When `is_async=true` (default), `callback_url` is **required**. When `is_async=false` (sync mode), `callback_url` is optional.
98+
- `callback_url` is optional for this endpoint. It is **required** for [`/api/v1/task/run`](/api/task/run/) and [`/api/v1/rerun`](/api/run/rerun/).
10199
- Passing a `run_slug` or `task_slug` to `scraper_slug` causes request validation failure.
102-
- Providing only generic `system` parameters is not enough if the Worker requires `custom` fields defined by its schema.
100+
- Providing only generic `system` parameters is not enough if the Worker requires `custom` fields defined by its descriptor.
103101

104102
## Response Example
105103

‎src/content/docs/developer-guide/worker-definition/platform-features/captcha-handling.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,12 +85,16 @@ if (result.status) {
8585

8686
| CAPTCHA Type | solverType |
8787
|--------------|------------|
88-
| Cloudflare Turnstile | cloudflare |
88+
| Cloudflare Click CAPTCHA | cloudflare |
89+
| DataDome Slider CAPTCHA | datadome |
8990
| Google reCAPTCHA v2 | google-v2 |
9091
| Google reCAPTCHA v3 | google-v3 |
91-
| DataDome Slider CAPTCHA | datadome |
92+
| OOCL Slider CAPTCHA | oocl_slide |
93+
| PerimeterX Press-and-Hold CAPTCHA | perimeterx |
94+
| SHEIN Image Recognition Click CAPTCHA | shein_same_object_click |
9295
| Temu (all CAPTCHA types) | temu_auto |
9396
| TikTok Slider CAPTCHA | tiktok_slide_simple |
97+
| TikTok Double-Spiral Slider CAPTCHA | tiktok_slide_auto |
9498

9599
:::note[Usage]
96100
When `status = true`, the CAPTCHA has been successfully handled. You can directly proceed with login, data collection, form submission, or other business logic.

‎src/content/docs/user-guide/run-worker/api-calls.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -70,19 +70,23 @@ POST /api/v1/scraper/run
7070
}
7171
```
7272

73-
`is_async` controls whether the run executes asynchronously. When `is_async=true` (default), `callback_url` is **required**. When `is_async=false` (sync mode), `callback_url` is optional.
73+
`is_async` controls whether the run executes asynchronously: `true` (default) for async, `false` to wait for completion. Provide `callback_url` when you need webhook delivery of results.
7474

75-
`custom` is not a free-form string and not the old `custom_params` JSON string field. Its structure must match the Worker's `input_schema.json`.
75+
`custom` is not a free-form string and not the old `custom_params` JSON string field. Its structure varies per Worker — it is not a fixed static schema.
7676

77-
- Use each `properties[].name` value from the Worker's `input_schema.json` as a key in `custom`
78-
- Follow the declared `type`, nested structure, and array shape
79-
- Provide every field whose schema sets `required: true`
80-
- If `custom` is empty or does not match the Worker's schema, the API returns `400 Bad Request`
77+
To find the exact fields for a specific Worker:
8178

82-
To find the exact `custom` fields for a specific Worker, open the Worker in the [CoreClaw Console](https://console.coreclaw.com), go to the **Input** tab, click the **API** button in the top-right corner, and select **API clients** to view ready-to-use code snippets.
79+
- **API**: Call `GET /api/scraper?slug=<scraper_slug>` and read `data.parameters.custom` from the response. Each entry in `properties[]` maps to a field in `input.parameters.custom`.
80+
- **Console**: Open the Worker in the [CoreClaw Console](https://console.coreclaw.com), go to the **Input** tab, click the **API** button in the top-right corner, and select **API clients** to view ready-to-use code snippets.
8381

8482
![API clients button in Worker Input tab](@/assets/docs/74.png)
8583

84+
When building `custom`:
85+
- Use each `properties[].name` as the key
86+
- Follow the declared `type`, nested structure, and array shape
87+
- Provide every field where `required: true`
88+
- If `custom` is empty or does not match, the API returns `400 Bad Request`
89+
8690
### How to get `version`
8791

8892
Use one of the following sources:

‎src/content/docs/zh-cn/api/worker/run.md‎

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,7 @@ sidebar:
4545
}
4646
},
4747
"callback_url": "https://your-callback.example.com/webhook",
48-
"is_async": true,
49-
"page_index": 1,
50-
"page_size": 10
48+
"is_async": true
5149
}
5250
```
5351

@@ -59,9 +57,7 @@ sidebar:
5957
| version | 是 | string | Worker 版本 |
6058
| input | 是 | object | 输入参数 |
6159
| is_async | 是 | boolean | `true`：异步执行（默认），`false`：同步执行（等待完成） |
62-
| page_index | 是 | number | 结果页码，默认 `1` |
63-
| page_size | 是 | number | 每页条数，默认 `10`，最大 `1000` |
64-
| callback_url | 条件 | string | 用于接收运行结果的回调地址。`is_async=true` 时**必填**，`is_async=false` 时可选。 |
60+
| callback_url | 否 | string | 用于接收运行结果的回调地址 |
6561

6662
#### `system` 参数
6763

@@ -76,17 +72,19 @@ sidebar:
7672

7773
#### `custom` 参数
7874

79-
`input.parameters.custom` 必须根据该 Worker 的 `input_schema.json` 构造。
75+
`input.parameters.custom` 不是固定结构——每个 Worker 各不相同。以下两种方式可查看具体字段：
8076

81-
- 使用 `properties[].name` 作为 `custom` 中的字段名
82-
- 严格匹配 schema 声明的 `type`、嵌套结构和数组形状
83-
- 对于 schema 中 `required: true` 的字段，必须显式提供
84-
- 如果 `custom` 为空，或结构与 Worker schema 不匹配，接口会返回 `400 Bad Request`
85-
86-
要查看具体 Worker 的 `custom` 字段，请在 [CoreClaw Console](https://console.coreclaw.com) 中打开该 Worker，进入 **Input** 选项卡，点击右上角的 **API** 按钮，选择 **API clients** 即可查看可直接使用的代码片段。
77+
- **API**：调用 `GET /api/scraper?slug=<scraper_slug>`，从响应的 `data.parameters.custom` 获取。`properties[]` 中每一项对应 `input.parameters.custom` 的一个字段。
78+
- **Console**：在 [CoreClaw Console](https://console.coreclaw.com) 中打开该 Worker，进入 **Input** 选项卡，点击右上角的 **API** 按钮，选择 **API clients** 即可查看可直接使用的代码片段。
8779

8880
![Worker Input 选项卡中的 API clients 按钮](@/assets/docs/74.png)
8981

82+
构造 `custom` 时：
83+
- 使用 `properties[].name` 作为字段名
84+
- 严格匹配声明的 `type`、嵌套结构和数组形状
85+
- 对于 `required: true` 的字段，必须显式提供
86+
- 如果 `custom` 为空，或结构不匹配，接口会返回 `400 Bad Request`
87+
9088
### 如何获取 `version`
9189

9290
可以从以下位置获得 Worker 版本：
@@ -97,9 +95,9 @@ sidebar:
9795

9896
## 校验行为
9997

100-
- **`callback_url` 与 `is_async`**：当 `is_async=true`（默认）时，`callback_url` **必填**。当 `is_async=false`（同步模式）时，`callback_url` 可选。
98+
- `callback_url` 在此端点可选。在 [`/api/v1/task/run`](/zh-cn/api/task/run/) 和 [`/api/v1/rerun`](/zh-cn/api/run/rerun/) 中**必填**。
10199
- 如果把 `run_slug` 或 `task_slug` 误传到 `scraper_slug` 字段，请求会在参数校验阶段失败。
102-
- 如果只提供通用 `system` 参数，但缺少该 Worker schema 要求的 `custom` 字段，请求仍会失败。
100+
- 如果只提供通用 `system` 参数，但缺少该 Worker 描述符要求的 `custom` 字段，请求仍会失败。
103101

104102
## 响应示例
105103

‎src/content/docs/zh-cn/developer-guide/worker-definition/platform-features/captcha-handling.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,12 +85,16 @@ if (result.status) {
8585

8686
| 验证码类型 | solverType |
8787
| ---------- | ---------- |
88-
| Cloudflare Turnstile | cloudflare |
88+
| Cloudflare 点击验证码 | cloudflare |
89+
| DataDome 滑块验证码 | datadome |
8990
| Google reCAPTCHA v2 | google-v2 |
9091
| Google reCAPTCHA v3 | google-v3 |
91-
| DataDome 滑块验证码 | datadome |
92+
| OOCL 滑块验证码 | oocl_slide |
93+
| PerimeterX 按压验证码 | perimeterx |
94+
| SHEIN 图像识别点击验证码 | shein_same_object_click |
9295
| Temu（所有验证码类型） | temu_auto |
93-
| TikTok 滑块验证码 | tiktok_slide_simple |
96+
| TikTok 缺口滑块验证码 | tiktok_slide_simple |
97+
| TikTok 双螺旋滑块验证码 | tiktok_slide_auto |
9498

9599
:::note[使用说明]
96100
当 `status = true` 时，验证码已成功处理。您可以直接继续登录、数据采集、表单提交或其他业务逻辑。

‎src/content/docs/zh-cn/user-guide/run-worker/api-calls.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -70,19 +70,23 @@ POST /api/v1/scraper/run
7070
}
7171
```
7272

73-
`is_async` 控制是否异步执行。`is_async=true`（默认）时，`callback_url` **必填**。`is_async=false`（同步模式）时，`callback_url` 可选。
73+
`is_async` 控制是否异步执行：`true`（默认）为异步，`false` 为同步等待结果。如需 Webhook 推送结果，请提供 `callback_url`。
7474

75-
`custom` 不是随意拼接的字符串，也不是旧版的 `custom_params` JSON 字符串字段。它的结构必须与该 Worker 的 `input_schema.json` 一致。
75+
`custom` 不是随意拼接的字符串，也不是旧版的 `custom_params` JSON 字符串字段。其结构因 Worker 而异，并非固定静态 schema。
7676

77-
- 使用该 Worker `input_schema.json` 中每个 `properties[].name` 作为 `custom` 的字段名
78-
- 严格遵守 schema 声明的 `type`、嵌套结构与数组形状
79-
- 对于 schema 中 `required: true` 的字段，必须显式提供
80-
- 如果 `custom` 为空，或结构与 Worker schema 不匹配，接口会返回 `400 Bad Request`
77+
要查看具体 Worker 的字段：
8178

82-
要查看具体 Worker 的 `custom` 字段，请在 [CoreClaw Console](https://console.coreclaw.com) 中打开该 Worker，进入 **Input** 选项卡，点击右上角的 **API** 按钮，选择 **API clients** 即可查看可直接使用的代码片段。
79+
- **API**：调用 `GET /api/scraper?slug=<scraper_slug>`，从响应的 `data.parameters.custom` 获取。`properties[]` 中每一项对应 `input.parameters.custom` 的一个字段。
80+
- **Console**：在 [CoreClaw Console](https://console.coreclaw.com) 中打开该 Worker，进入 **Input** 选项卡，点击右上角的 **API** 按钮，选择 **API clients** 即可查看可直接使用的代码片段。
8381

8482
![Worker Input 选项卡中的 API clients 按钮](@/assets/docs/74.png)
8583

84+
构造 `custom` 时：
85+
- 使用 `properties[].name` 作为字段名
86+
- 严格遵守声明的 `type`、嵌套结构与数组形状
87+
- 对于 `required: true` 的字段，必须显式提供
88+
- 如果 `custom` 为空，或结构不匹配，接口会返回 `400 Bad Request`
89+
8690
### 如何获取 `version`
8791

8892
可以从以下位置获得：

0 commit comments

Comments
 (0)