Skip to main content
POST
Schedule a skill
Give exactly one of:
  • cron: a 5-field cron expression, for example 0 9 * * 1-5.
  • every: hourly, daily, daily 09:00, weekly mon 09:00, 30 minutes, 2h, or the app’s forms daily:09:00, weekly:mon:09:00, interval:30.
Also: timezone (an IANA name, default UTC), inputs for every run (checked now), max_results (rows per run, default 100, 0 for all), and enabled (default true). A skill has one schedule. If it already has one you get 409 with its id: change it with Update a schedule. Each scheduled run spends the owner’s credits. Owner or workspace editor. Needs skills:write. MCP tool: schedule_skill.

Authorizations

Authorization
string
header
required

API key with the vd_sk_ prefix, as Authorization: Bearer vd_sk_.... Create keys in Settings → API Keys.

Headers

Idempotency-Key
string

Any unique string (such as your order id). Resending the same request with the same key within 24 hours returns the first answer (with Idempotent-Replayed: true) and does nothing twice; the same key with a different request is a 422 idempotency_key_reused.

Required string length: 1 - 255

Path Parameters

slug
string
required

Body

application/json
cron
string | null

5-field cron, e.g. '0 9 * * 1-5'

every
string | null

'hourly', 'daily', 'daily 09:00', 'weekly mon 09:00', '30 minutes' / '2h', or daily:09:00 / weekly:mon:09:00 / interval:30

timezone
string
default:UTC

IANA name, e.g. 'Europe/London'

inputs
Inputs · object

Inputs each scheduled run uses

max_results
integer | null

Rows per run; 0 = all; default 100

Required range: 0 <= x <= 500
enabled
boolean
default:true

Response

The new schedule.

The same shape as a workflow's schedule (GET /v1/schedules lists both), plus max_results.

id
string
required

The schedule id: PATCH / DELETE /v1/schedules/{id}

skill_id
string
required
skill_slug
string
required
every
string
required

The cadence in words

frequency
string
required

The cadence as the app stores it

timezone
string
required
max_results
integer
required
enabled
boolean
required
kind
string
default:skill
Allowed value: "skill"
cron
string | null

The cadence as 5-field cron (null for '30 minutes')

inputs
Inputs · object
next_run_at
string<date-time> | null
last_run_at
string<date-time> | null