hosting

POST `/v1/sites/{siteId}/scheduled-tasks`

Create a scheduled task on a site.

Authentication

Send an API key as a bearer token. The key must carry the sites.view permission; a key without it is refused with 403, not 404.

This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/sites/{siteId}/scheduled-tasks \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{  }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Adds a task and writes it to the site's server in the same request; if the server refuses, nothing is kept. Refused with a 422 naming the fix for: a schedule more often than every 5 minutes (checked across the whole day, including :55 to :00), a multi-line or over-long command, a PHP path outside the site folder, an address that is not http(s), a kind the site cannot run, 20 tasks on the site or 500 on the account, or a plan without scheduled tasks. A */N minute field is moved to a fixed offset inside its window (schedule in the answer is what runs). The old body (schedule + command only) still works and creates a command task. Audited as site.cron.created. Requires sites.view and sites.panel_access.

Parameters

Name	Type	Required	What it is
`siteId (path)`	`Uuid`	Yes	Site ID (UUIDv7).

Request body

Name	Type	Required	What it is
`name`	`string`	No	—
`kind`	`string<command, php, url, wpcron>`	No	—
`target`	`string`	No	The command (one line), the .php path inside the site folder, or the address.
`command`	`string`	No	The old field — the same as `target` for a `command` task.
`schedule`	`string`	No	Five fields `minute hour day-of-month month day-of-week`, UTC, or @hourly, @daily, @weekly, @monthly, @yearly. At most once every 5 minutes.
`email_output`	`string`	No	An address to mail each scheduled run's output to, or empty for none.
`enabled`	`boolean`	No	Switch the task on (default) or off.

Response

Name	Type	Required	What it is
`id`	`string`	Yes	A UUID for a managed task; a 16-character id for a crontab line.
`name`	`string`	Yes	The name the customer gave it (empty for a crontab line).
`kind`	`string<command, php, url, wpcron>`	Yes	`command` a shell command; `php` a .php file in the site folder run with the site's PHP version; `url` open an http(s) address; `wpcron` WordPress's due events.
`target`	`string`	Yes	The command, the script path or the address (empty for `wpcron`).
`schedule`	`string`	Yes	Five fields, UTC, as written to the crontab. A `*/N` minute field is moved to a fixed offset inside its window, so this can differ from what was sent.
`command`	`string`	Yes	The command line for a `command` task (the old field); empty otherwise.
`enabled`	`boolean`	Yes	Whether the customer has it switched on.
`email_output`	`string`	Yes	Where each scheduled run's output is mailed, or `""`.
`paused_reason`	`string`	Yes	`staff` when our team switched it off; `""` otherwise.
`source`	`string<panel, crontab>`	Yes	—
`site_id`	`string`	Yes	—
`site_domain`	`string`	Yes	Filled on the account-wide list.

Errors this endpoint can return

401 · 403 · 404 · 422 · 429 · 503

POST /v1/sites/{siteId}/scheduled-tasks