Create a task
Saves an instruction with a trigger and turns it on. A schedule task runs at its next time, and a mail task from the next message that arrives.
Runs the real call on your workspace.
POST /tasks
Saves an instruction with a trigger and turns it on. A schedule task runs at its next time, and a mail task from the next message that arrives.
Example
Needs tasks:write, threads:read, threads:write, emails:read, emails:send and labels:write, and the scopes of each toolkit in toolkits.
curl -X POST "$OE/tasks" -H "$AUTH" -H 'content-type: application/json' -d '{ "name": "Morning summary", "instruction": "Go through the mail that arrived since yesterday. Tell me which conversations need a reply from me, most urgent first, and draft a short reply for each.", "trigger": { "kind": "schedule", "schedule": { "cadence": "daily", "hour": 8, "minute": 0, "weekdays": [1, 2, 3, 4, 5], "timezone": "Europe/London" } }, "autonomy": "organize"}'{ "object": "task", "id": "tsk_4b9e2c7a1f3d86e05a9c2b7d", "name": "Morning summary", "instruction": "Go through the mail that arrived since yesterday. Tell me which conversations need a reply from me, most urgent first, and draft a short reply for each.", "status": "active", "pausedReason": null, "trigger": { "kind": "schedule", "schedule": { "cadence": "daily", "everyHours": 1, "hour": 8, "minute": 0, "weekdays": [1, 2, 3, 4, 5], "monthDay": 1, "timezone": "Europe/London" }, "mail": null }, "autonomy": "organize", "toolkits": ["notes", "drafts", "knowledge"], "model": "standard", "notify": "attention", "maxRunsPerDay": 50, "maxSteps": 20, "nextRunAt": "2026-10-14T07:00:00.000Z", "heldUntil": null, "lastRunAt": "2026-10-13T07:00:04.112Z", "lastRunStatus": "done", "runCount": 12, "pendingApprovals": 0, "createdAt": "2026-10-01T09:12:44.000Z", "updatedAt": "2026-10-13T07:01:10.530Z"}Only name, instruction and trigger are required. autonomy defaults to organize, model to standard, notify to attention, maxRunsPerDay to 50 and maxSteps to 20.
Left out, toolkits is drafts, notes and knowledge, so the request also needs drafts:read, drafts:write, knowledge:read and knowledge:write. Send "toolkits": [] for a task that only reads and organises mail.
"paused": true saves the task without turning it on, which also keeps it out of the plan’s count of active tasks.
A schedule without a timezone runs on UTC. The parts a cadence does not use are filled in and ignored.
A mail task with no mail filter runs for every message that reaches an inbox, so narrow it with addresses, fromContains or subjectContains where you can.
notify says when the owner and whoever made the task hear about a run: attention when it waits for approval or fails, always also when it finishes, never not at all.
A value that does not fit is refused with 422 invalid_task, and param names the field.