Skip to content

Commit ed4899d

Browse files
kael-odinkael-odin
committed
Fix API playground: correct examples, pre-fill params, improve UX
- Updated openapi.json with correct scraper_slug, run_slug, task_slug examples - Updated examples.async_run version from v1.0.1 to v1.0.5 - Updated filter_keys from [] to meaningful values - Added search example value in /api/store parameters - Fixed ApiPlayground param value to include param.example fallback - Updated all doc pages (EN + zh-CN) with consistent slug values and- Added API key link to index pages pointing to Console settings - Fixed integration.md Amazon worker version to v1.0.1
1 parent 74e19b3 commit ed4899d

28 files changed

Lines changed: 385 additions & 150 deletions

‎public/openapi.json‎

Lines changed: 86 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,8 @@
5757
"required": true,
5858
"schema": {
5959
"type": "string"
60-
}
60+
},
61+
"example": "google"
6162
},
6263
{
6364
"name": "limit",
@@ -134,7 +135,7 @@
134135
"schema": {
135136
"type": "string"
136137
},
137-
"example": "01KJXYJ7KCHXM0PDZHQD5293XE"
138+
"example": "01KPD6M5YVHWCNQCRK32BD02TP"
138139
}
139140
],
140141
"responses": {
@@ -156,7 +157,7 @@
156157
"parameters": {
157158
"system": {
158159
"cpus": 0.125,
159-
"memory_bytes": 512,
160+
"memory": 512,
160161
"max_total_charge": 0,
161162
"max_total_traffic": 0,
162163
"execute_limit_time_seconds": 1800
@@ -210,7 +211,7 @@
210211
"Runs"
211212
],
212213
"summary": "Start scraper run",
213-
"description": "Start a new Worker run by `scraper_slug`. Verified runtime rule: `callback_url` is optional; include it when webhook orchestration is needed. `version` must come from `/api/scraper`. `input.parameters.custom` is dynamic and must be derived from `/api/scraper`. `input.parameters.system.memory` is measured in MB and corresponds to `memory_bytes` returned by `/api/scraper`.",
214+
"description": "Start a new Worker run by `scraper_slug`. Verified runtime rule: `callback_url` is optional; include it when webhook orchestration is needed. `version` must come from `/api/scraper`. `input.parameters.custom` is dynamic and must be derived from `/api/scraper`. `input.parameters.system.memory` is measured in MB and corresponds to `memory` returned by `/api/scraper`.",
214215
"requestBody": {
215216
"required": true,
216217
"content": {
@@ -222,8 +223,8 @@
222223
"async_run": {
223224
"summary": "Async run with callback",
224225
"value": {
225-
"scraper_slug": "01KGYERXPXTABWXMGQKFCE43M2",
226-
"version": "v1.0.1",
226+
"scraper_slug": "01KPD6M5YVHWCNQCRK32BD02TP",
227+
"version": "v1.0.5",
227228
"is_async": true,
228229
"input": {
229230
"parameters": {
@@ -236,9 +237,11 @@
236237
"proxy_region": "US"
237238
},
238239
"custom": {
239-
"startURLs": [
240+
"url": [
240241
{
241-
"url": "https://example.com"
242+
"lang": "en",
243+
"detail_url": "https://www.google.com/maps/place/Burger+King",
244+
"max_reviews_per_place": 20
242245
}
243246
]
244247
}
@@ -250,8 +253,8 @@
250253
"sync_run": {
251254
"summary": "Sync run without callback",
252255
"value": {
253-
"scraper_slug": "01KGYERXPXTABWXMGQKFCE43M2",
254-
"version": "v1.0.1",
256+
"scraper_slug": "01KPD6M5YVHWCNQCRK32BD02TP",
257+
"version": "v1.0.5",
255258
"is_async": false,
256259
"input": {
257260
"parameters": {
@@ -263,16 +266,45 @@
263266
"max_total_traffic": 0
264267
},
265268
"custom": {
266-
"startURLs": [
269+
"url": [
267270
{
268-
"url": "https://example.com"
271+
"lang": "en",
272+
"detail_url": "https://www.google.com/maps/place/Burger+King",
273+
"max_reviews_per_place": 20
269274
}
270275
]
271276
}
272277
}
273278
}
274279
}
275280
}
281+
},
282+
"example": {
283+
"scraper_slug": "01KPD6M5YVHWCNQCRK32BD02TP",
284+
"version": "v1.0.5",
285+
"is_async": true,
286+
"input": {
287+
"parameters": {
288+
"system": {
289+
"cpus": 0.125,
290+
"memory": 512,
291+
"execute_limit_time_seconds": 1800,
292+
"max_total_charge": 0,
293+
"max_total_traffic": 0,
294+
"proxy_region": "US"
295+
},
296+
"custom": {
297+
"url": [
298+
{
299+
"lang": "en",
300+
"detail_url": "https://www.google.com/maps/place/Burger+King",
301+
"max_reviews_per_place": 20
302+
}
303+
]
304+
}
305+
}
306+
},
307+
"callback_url": "https://your-callback.example.com/webhook"
276308
}
277309
}
278310
}
@@ -333,7 +365,7 @@
333365
"$ref": "#/components/schemas/TaskRunRequest"
334366
},
335367
"example": {
336-
"task_slug": "01KK0G4W9W4JYTWEA55KMG5QKP",
368+
"task_slug": "01KSFDXRNYGKT3NNE11EMR4W5X",
337369
"callback_url": "https://your-callback.example.com/webhook"
338370
}
339371
}
@@ -395,7 +427,7 @@
395427
"$ref": "#/components/schemas/RerunRequest"
396428
},
397429
"example": {
398-
"run_slug": "01KS2A1M515HG7PZX9STTB0KPH",
430+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9",
399431
"callback_url": "https://your-callback.example.com/webhook"
400432
}
401433
}
@@ -457,7 +489,7 @@
457489
"$ref": "#/components/schemas/RunSlugRequest"
458490
},
459491
"example": {
460-
"run_slug": "01KS2A1M515HG7PZX9STTB0KPH"
492+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9"
461493
}
462494
}
463495
}
@@ -531,9 +563,9 @@
531563
},
532564
"example": {
533565
"page_index": 1,
534-
"page_size": 20,
566+
"page_size": 10,
535567
"status": 0,
536-
"scraper_slug": ""
568+
"scraper_slug": "01KPD6M5YVHWCNQCRK32BD02TP"
537569
}
538570
}
539571
}
@@ -624,8 +656,8 @@
624656
},
625657
"example": {
626658
"page_index": 1,
627-
"page_size": 20,
628-
"run_slug": "01KS2A1M515HG7PZX9STTB0KPH"
659+
"page_size": 10,
660+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9"
629661
}
630662
}
631663
}
@@ -715,8 +747,11 @@
715747
"$ref": "#/components/schemas/RunResultExportRequest"
716748
},
717749
"example": {
718-
"run_slug": "01KS2A1M515HG7PZX9STTB0KPH",
719-
"filter_keys": [],
750+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9",
751+
"filter_keys": [
752+
"title",
753+
"address"
754+
],
720755
"format": "csv"
721756
}
722757
}
@@ -778,7 +813,7 @@
778813
"$ref": "#/components/schemas/RunSlugRequest"
779814
},
780815
"example": {
781-
"run_slug": "01KS2A1M515HG7PZX9STTB0KPH"
816+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9"
782817
}
783818
}
784819
}
@@ -854,7 +889,7 @@
854889
"$ref": "#/components/schemas/RunSlugRequest"
855890
},
856891
"example": {
857-
"run_slug": "01KJYA4S1QQ1PMDVVRP7XH72C51"
892+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9"
858893
}
859894
}
860895
}
@@ -990,7 +1025,8 @@
9901025
"properties": {
9911026
"run_slug": {
9921027
"type": "string",
993-
"description": "Unique run identifier returned by CoreClaw."
1028+
"description": "Unique run identifier returned by CoreClaw.",
1029+
"example": "01KSFDS8XWTJME33C08XMCR6B9"
9941030
}
9951031
},
9961032
"required": [
@@ -1007,7 +1043,7 @@
10071043
},
10081044
"memory": {
10091045
"type": "integer",
1010-
"description": "Memory allocation in MB. This corresponds to `memory_bytes` returned by `/api/scraper`.",
1046+
"description": "Memory allocation in MB. Corresponds to the memory value returned by /api/scraper.",
10111047
"enum": [
10121048
512,
10131049
1024,
@@ -1032,7 +1068,8 @@
10321068
"proxy_region": {
10331069
"type": "string",
10341070
"description": "ISO 3166-1 alpha-2 proxy region code. Defaults to `US` when omitted.",
1035-
"pattern": "^[A-Z]{2}$"
1071+
"pattern": "^[A-Z]{2}$",
1072+
"default": "US"
10361073
}
10371074
},
10381075
"required": [
@@ -1051,9 +1088,9 @@
10511088
"type": "number",
10521089
"description": "Default CPU allocation."
10531090
},
1054-
"memory_bytes": {
1091+
"memory": {
10551092
"type": "integer",
1056-
"description": "Default memory allocation in MB. Map this value to `input.parameters.system.memory` when calling `/api/v1/scraper/run`."
1093+
"description": "Default memory allocation in MB."
10571094
},
10581095
"max_total_charge": {
10591096
"type": "number",
@@ -1070,7 +1107,7 @@
10701107
},
10711108
"required": [
10721109
"cpus",
1073-
"memory_bytes",
1110+
"memory",
10741111
"max_total_charge",
10751112
"max_total_traffic",
10761113
"execute_limit_time_seconds"
@@ -1111,11 +1148,13 @@
11111148
"properties": {
11121149
"scraper_slug": {
11131150
"type": "string",
1114-
"description": "Unique scraper identifier."
1151+
"description": "Unique scraper identifier.",
1152+
"example": "01KPD6M5YVHWCNQCRK32BD02TP"
11151153
},
11161154
"version": {
11171155
"type": "string",
1118-
"description": "Scraper version. Must be copied from `/api/scraper` -> `data.version`."
1156+
"description": "Scraper version. Must be copied from `/api/scraper` -> `data.version`.",
1157+
"example": "v1.0.5"
11191158
},
11201159
"is_async": {
11211160
"type": "boolean",
@@ -1412,21 +1451,21 @@
14121451
"page_index": {
14131452
"type": "integer",
14141453
"description": "1-based page index.",
1415-
"minimum": 1
1454+
"minimum": 1,
1455+
"default": 1
14161456
},
14171457
"page_size": {
14181458
"type": "integer",
14191459
"description": "Page size.",
1420-
"minimum": 1
1460+
"minimum": 1,
1461+
"default": 10
14211462
},
14221463
"run_slug": {
14231464
"type": "string",
14241465
"description": "Run slug whose records should be listed."
14251466
}
14261467
},
14271468
"required": [
1428-
"page_index",
1429-
"page_size",
14301469
"run_slug"
14311470
]
14321471
},
@@ -1450,12 +1489,22 @@
14501489
"items": {
14511490
"$ref": "#/components/schemas/RunResultRecord"
14521491
}
1492+
},
1493+
"page_index": {
1494+
"type": "integer",
1495+
"description": "Current page number (1-based)."
1496+
},
1497+
"page_size": {
1498+
"type": "integer",
1499+
"description": "Number of records per page."
14531500
}
14541501
},
14551502
"required": [
14561503
"count",
14571504
"headers",
1458-
"list"
1505+
"list",
1506+
"page_index",
1507+
"page_size"
14591508
]
14601509
},
14611510
"RunResultListResponse": {
@@ -1503,6 +1552,7 @@
15031552
},
15041553
"required": [
15051554
"run_slug",
1555+
"filter_keys",
15061556
"format"
15071557
]
15081558
},

‎src/components/ApiPlayground.astro‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,7 @@ const id = `api-playground-${methodUp.toLowerCase()}-${opPath
226226
data-param-name={param.name}
227227
data-param-in={param.in}
228228
placeholder={param.example ?? param.schema?.default ?? param.description ?? ''}
229-
value={param.schema?.default ?? ''}
229+
value={param.schema?.default ?? param.example ?? ''}
230230
/>
231231
{param.description && <p class="ap-hint">{param.description}</p>}
232232
</div>

‎src/content/docs/api/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ https://openapi.coreclaw.com
1717

1818
| Parameter Name | Example Value | Type | Required | Description |
1919
| -------------- | ---------------- | ------ | -------- | ----------- |
20-
| api-key | <YOUR_API_KEY> | string | Yes | Your API key for authentication |
20+
| api-key | <YOUR_API_KEY> | string | Yes | Your API key. Get it from [Console Settings → API & Integrations](https://console.coreclaw.com/settings/integrations) |
2121
| content-type | application/json | string | Yes | Request content type |
2222

2323
> **Note:** `/api/scraper` and `/api/store` are public endpoints that do not require an API key.

‎src/content/docs/api/integration.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ curl -X POST "https://openapi.coreclaw.com/api/v1/scraper/run" \
147147
```json
148148
{
149149
"code": 0,
150-
"data": { "run_slug": "01KS2A1M515HG7PZX9STTB0KPH" }
150+
"data": { "run_slug": "01KSFDS8XWTJME33C08XMCR6B9" }
151151
}
152152
```
153153

@@ -159,7 +159,7 @@ Save the `run_slug` (**Run Record ID**) to track progress and retrieve results.
159159
curl -X POST "https://openapi.coreclaw.com/api/v1/run/detail" \
160160
-H "api-key: YOUR_API_KEY" \
161161
-H "content-type: application/json" \
162-
--data '{"run_slug": "01KS2A1M515HG7PZX9STTB0KPH"}'
162+
--data '{"run_slug": "01KSFDS8XWTJME33C08XMCR6B9"}'
163163
```
164164

165165
Status codes: `1` Ready, `2` Running, `3` Succeeded, `4` Failed, `5` Aborting.
@@ -171,7 +171,7 @@ curl -X POST "https://openapi.coreclaw.com/api/v1/run/result/list" \
171171
-H "api-key: YOUR_API_KEY" \
172172
-H "content-type: application/json" \
173173
--data '{
174-
"run_slug": "01KS2A1M515HG7PZX9STTB0KPH",
174+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9",
175175
"page_index": 1,
176176
"page_size": 20
177177
}'
@@ -190,7 +190,7 @@ In async mode, supply `callback_url` and CoreClaw will POST a notification to yo
190190

191191
```json
192192
{
193-
"run_slug": "01KS2A1M515HG7PZX9STTB0KPH",
193+
"run_slug": "01KSFDS8XWTJME33C08XMCR6B9",
194194
"status": 3,
195195
"results": 20,
196196
"usage": "0.06"

0 commit comments

Comments
 (0)