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

Authorization: Bearerapi-key headerQuery token

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.

schedule_dayintegerOptionalDay of month for monthly schedule (1-31). Constraints: range 1-31.

schedule_enabledenum: 0, 1OptionalSchedule switch. 0=disabled, 1=enabled. Constraints: allowed values: `0`, `1`.

schedule_once_datestringOptionalOnce schedule date in YYYY-MM-DD.

schedule_timestringOptionalSchedule time in HH:mm.

schedule_typeenum: 1, 2, 3, 4OptionalSchedule type. 1=daily, 2=weekly, 3=monthly, 4=once. Constraints: allowed values: `1`, `2`, `3`, `4`.

schedule_weekdayenum: 1, 2, 3, 4, 5, 6, 7OptionalWeekday for weekly schedule. 1=Monday ... 7=Sunday. Constraints: range 1-7; allowed values: `1`, `2`, `3`, `4`, `5`, `6`, `7`.

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)Reset to example

{ "description": "Scrape Google Maps business records on a schedule.", "input": { "parameters": { "custom": { "keywords": [ { "keyword": "HVAC Contractors" } ], "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" }

Send Request Clear all

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.
schedule_day	No	integer	Day of month for monthly schedules (1-31).
schedule_enabled	No	enum: 0, 1	Schedule switch: 1 enabled, 0 disabled.
schedule_once_date	No	string	Date for one-time schedules, YYYY-MM-DD.
schedule_time	No	string	Schedule time of day, HH:mm.
schedule_type	No	enum: 1, 2, 3, 4	Schedule type: 1=daily, 2=weekly, 3=monthly, 4=once.
schedule_weekday	No	enum: 1, 2, 3, 4, 5, 6, 7	Day of week for weekly schedules (1=Monday … 7=Sunday).
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.

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

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.
• Schedule fields: schedule_enabled 1 enabled / 0 disabled; schedule_type 1=daily, 2=weekly, 3=monthly, 4=once; schedule_time is HH:mm; schedule_once_date is YYYY-MM-DD. Omit all schedule fields when scheduling is not needed.
• 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