Skip to main content
POST
Start background jobs
Give items, 1 to 6 things to run. Each is kind: skill with skill (its id or slug) or kind: workflow with workflow_id, plus optional inputs, max_results (skills, 1–500), and a short label. Two or more items start a batch; label at the top names it. The answer comes at once (202): jobs holds each job that started, and batch the batch when there are two or more. Nothing calls you back: poll Get a background job for each job, or for the batch, which ends when they all have. An item that cannot start (no such skill, inputs that do not fit, not enough credits) is listed in refused with the reason, and the others still start. Research helpers start only from a chat in the app, not here. Starting twice runs twice, so send an Idempotency-Key to make a retry safe. See Idempotency. MCP tool: start_jobs.

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

Body

application/json
items
StartItem · object[]
required

1 to 6 things to run. Two or more start a batch.

Required array length: 1 - 6 elements
label
string | null

Two or more items: the batch's name.

Maximum string length: 200

Response

Successful Response

jobs
Job · object[]
required

The jobs that started, each running on its own.

batch
Job · object | null

The batch grouping them, when two or more were started: it ends when they all have.

refused
string[]

Each item that could not start, and why.