Skip to main content
POST
Create a task

Authorizations

Authorization
string
header
required

An organization-scoped API key, minted in control under Settings → API keys. Every failure to authenticate answers one identical 401: "Provide a valid organization-scoped API key or an active session." Each operation names the one scope it is filed under, <resource>:<read|write>, where the resource is the first path segment after /api/v1/; a key minted today carries all 22 of them. Scopes are RECORDED — on the key and on every audit row — and are not yet enforced: no request is refused for want of one.

Headers

Idempotency-Key
string

Any unique string.

Body

application/json
workerId
string
required

The Worker that holds the task, or runs the job. Resolved under your organization.

title
string
required

What the task or job is called. 1–200 characters.

description
string

Opening a task: what the work is. 1–8000 characters.

dueAt
string

Opening a task: an ISO instant it is expected done by. Context only — nothing fires when it passes.

prompt
string

Scheduling a job: the text the agent is given when it fires. 1–8000 characters. Required with scheduleKind.

tier
enum<string>

Scheduling a job: which tier's ework runs it. Required with scheduleKind.

Available options:
core,
client
clientId
string

Scheduling a job: required on the client tier. Resolved under your organization.

scheduleKind
enum<string>

Present: schedule a job — a one-off instant, or a repeating expression. Absent: open a task held by workerId.

Available options:
once,
cron
runAt
string

ISO instant. Required when scheduleKind is once.

cronExpr
string

Five-field cron expression. Required when scheduleKind is cron.

timezone
string

IANA zone the expression is read in. A zone this system does not recognize is refused rather than replaced with a default.

targetChannel
string

Where the run posts, when it is not the channel it was scheduled from.

Response

Success.

data
object
required