Create Worker Task

Method: POST

Endpoint: /api/v2/worker-tasks

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

Try it

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)

When to use this endpoint

Use this endpoint to create a new Worker task template that stores the Worker identifier, input parameters, and an optional schedule.

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.
`input`	Yes	`any`	Worker input payload. Worker form fields usually belong under `input.parameters.custom`; read the Worker input schema first and build this object from that schema.
`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`	Yes	`string`	Task template title, used for display and search.
`version`	No	`string`	Optional Worker version. Omit it unless you have confirmed a concrete available version for this Worker; not every Worker accepts `latest` as an explicit version value.
`worker_id`	Yes	`string`	Worker identifier. Accepts a Worker slug, or an `owner/name` path encoded as `owner~name`.

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.",
  "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"
}

Run every 5 minutes:

{
  "worker_id": "demo-worker",
  "title": "Every 5 minutes task",
  "input": {
    "parameters": {
      "custom": {
        "keyword": "coffee"
      }
    }
  },
  "schedule_enabled": 1,
  "schedule_type": 6,
  "schedule_minute_interval": 5,
  "schedule_timezone": "Asia/Shanghai"
}

Run every 2 hours:

{
  "worker_id": "demo-worker",
  "title": "Every 2 hours task",
  "schedule_enabled": 1,
  "schedule_type": 5,
  "schedule_hour_interval": 2,
  "schedule_timezone": "Asia/Shanghai"
}

Request Example

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"}'

Response Example

{
  "code": 0,
  "data": {
    "slug": "demo-task"
  },
  "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.
worker_id accepts a Worker slug, or an owner/name path encoded as owner~name.
Read the Worker input schema before building input; form fields belong under input.parameters.custom. Use GET /api/v2/workers/{workerId}/input-schema to read the schema.
Omit all schedule fields when scheduling is not needed.
The API service does not execute scheduled tasks itself; the Console scheduler must be running for schedules to fire.
Schedules generated by the API use a Console-compatible cron with a seconds field and a CRON_TZ prefix (for example CRON_TZ=Asia/Shanghai 0 30 9 * * *). The Console scheduler only registers schedules in this format.
Tasks created before the new schedule fields were introduced may still hold a 5-field cron without CRON_TZ; re-save the schedule configuration (or run the backend migration) to convert them to the current format.
Timezone, DST, month-end edges, missed-run, and overlapping-run behavior for schedules are platform-managed and not part of the public API contract; consult the Console or support before relying on exact schedule semantics.

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