Update Worker Task

Method: PUT

Endpoint: /api/v2/worker-tasks/{workerTaskId}

Authentication: Supports Authorization: Bearer <YOUR_API_KEY>, api-key: <YOUR_API_KEY>, and ?token=<YOUR_API_KEY>. Prefer Bearer token.

Try it

PUT/api/v2/worker-tasks/{workerTaskId}Update worker task

AuthenticationRequired

Auth mode

Authorization: Bearerapi-key headerQuery token

API token

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

Parameters

workerTaskIdpath · stringRequired

Saved Worker task template slug. Get it from the `data.list[].slug` field of `GET /api/v2/worker-tasks`. The playground prefills a sample slug; replace it with your own.

Request BodyRequiredapplication/json

FieldTypeRequiredDescription

descriptionstringOptionalTask description. Omit to keep current description.

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). Omit to keep current. 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. Omit to keep current. 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.

titlestringOptionalTask title. Omit to keep current title.

Request body (JSON)Reset to example

{ "description": "Scrape Google Maps business records on a schedule.", "recipient_email": "YOUR_RECIPIENT_EMAIL", "schedule_date": "YOUR_SCHEDULE_DATE", "schedule_day": 1, "schedule_day_interval": 1, "schedule_days": "YOUR_SCHEDULE_DAYS", "schedule_enabled": 0, "schedule_hour_interval": 1, "schedule_minute_interval": 1, "schedule_once_date": "2026-08-01", "schedule_time": "09:00", "schedule_timezone": "YOUR_SCHEDULE_TIMEZONE", "schedule_type": 1, "schedule_weekday": 1, "schedule_weekdays": "YOUR_SCHEDULE_WEEKDAYS", "task_template_id": 0, "title": "Google Maps Scraper (Task)" }

Send Request Clear all

When to use this endpoint

Use this endpoint to update the title, description, or schedule of a task template. Omitted fields keep their current values.

Identifier Notes

• workerTaskId is the saved task template slug.

Path Parameters

Parameter	Required	Type	Description
workerTaskId	Yes	string	Saved Worker task template slug. Get it from the data.list[].slug field of GET /api/v2/worker-tasks.

Request Body

Send the request body with Content-Type: application/json. Required/Optional describes each field; the Try it Request Body badge shows whether the body itself is required.

Field	Required	Type	Description
description	No	string	Task template description. Optional.
recipient_email	No	string	Email address notified when the task finishes.
schedule_day	No	integer	Day of month for monthly schedules (1-31). Single-day compatibility field; prefer schedule_days.
schedule_day_interval	No	integer	Repeat every N days for daily schedules. Default 1.
schedule_days	No	string	Days of month for monthly schedules, comma-separated (e.g. 1,15,31).
schedule_enabled	No	enum: 0, 1	Schedule switch: 1 enabled, 0 disabled.
schedule_hour_interval	No	integer	Repeat every N hours for schedule_type=5. Required when type 5. Range 1-23.
schedule_minute_interval	No	integer	Repeat every N minutes for schedule_type=6. Required when type 6. Range 1-59.
schedule_once_date	No	string	Date for one-time schedules, YYYY-MM-DD.
schedule_time	No	string	Schedule time of day, HH:mm.
schedule_timezone	No	string	IANA timezone for the schedule, default Asia/Shanghai (e.g. UTC, America/New_York).
schedule_type	No	enum: 1, 2, 3, 4, 5, 6	Schedule type: 1=daily, 2=weekly, 3=monthly, 4=once, 5=every N hours, 6=every N minutes.
schedule_weekday	No	enum: 1, 2, 3, 4, 5, 6, 7	Day of week for weekly schedules (1=Monday … 7=Sunday). Single-day compatibility field; prefer schedule_weekdays.
schedule_weekdays	No	string	Days of week for weekly schedules, comma-separated (e.g. 1,3,5).
task_template_id	No	integer	Associated task template ID.
title	No	string	Task template title, used for display and search.

Scheduling

Set schedule_enabled: 1 together with schedule_type and the fields required for that type:

schedule_type	Meaning	Companion fields
1	Every day	schedule_time; optional schedule_day_interval (every N days, default 1).
2	Every week	schedule_time; schedule_weekdays (e.g. 1,3,5) or schedule_weekday.
3	Every month	schedule_time; schedule_days (e.g. 1,15,31) or schedule_day.
4	Once	schedule_once_date (YYYY-MM-DD) and schedule_time.
5	Every N hours	schedule_hour_interval (1-23).
6	Every N minutes	schedule_minute_interval (1-59).

Schedules are interpreted in schedule_timezone (default Asia/Shanghai). The API generates a Console-compatible cron with a seconds field and CRON_TZ prefix, for example CRON_TZ=Asia/Shanghai 0 30 9 * * *. The Console scheduler only registers schedules in this format.

JSON Example

{
  "description": "Scrape Google Maps business records on a schedule.",
  "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)"
}

Request Example

curl -X PUT "https://openapi.coreclaw.com/api/v2/worker-tasks/YOUR_WORKER_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"description":"Scrape Google Maps business records on a schedule.","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)"}'

Response Example

{
  "code": 0,
  "message": "success",
  "request_id": "req-123"
}

Notes

• API v2 supports Bearer token, the legacy api-key header, and query token. Prefer Bearer token for new integrations.
• PUT is a partial update: omitted fields keep their current values; you do not need to resend the whole task object.
• To update the task input parameters themselves (not the title or schedule), use PUT /api/v2/worker-tasks/{workerTaskId}/input.
• The API service does not execute scheduled tasks itself; the Console scheduler must be running for schedules to fire. Re-saving the schedule configuration regenerates the Console-compatible cron (with seconds field and CRON_TZ prefix) that the scheduler registers.

HTTP Responses

HTTP Status	Application Code	Meaning
200	0	OK
400	11000	Bad Request
401	12001	Unauthorized
404	11004	Not Found
422	11000	Unprocessable Entity
429	13000	Too Many Requests
500	10000	Internal Server Error