--- title: "Update task" method: PATCH path: "/tasks/{id}" tags: ["Tasks"] --- # Update task `PATCH /tasks/{id}` ## Request - Base URL: `https://api.crevio.co/v1` - URL: `https://api.crevio.co/v1/tasks/{id}` - Auth: API key in header `Authorization` Updates an existing AI task. ## Path parameters - `id` string, required ## Request body - AiTaskRequest - `name` string - `description` string, nullable - `kind` 'agent' | 'script': `agent` runs `prompt` as an agent turn. `script` runs `script` on the account's computer with no agent and no model credits, for runs that are the same deterministic steps every time; it takes no `prompt`. To switch kind, send the new `kind` with its field and `null` for the other. - `prompt` string, nullable: What the agent does on each run. Required for `kind: agent`, must be absent for `kind: script`. - `success_criteria` string, nullable: What done means for one run: the checkable outcomes a finished run must have produced (a post is live at its URL, the report reached #sales, every new order has a tracking number). Every run is shown them and must check its result against them before it reports. Outcomes, not steps; the steps belong in `prompt`. - `trigger_type` 'immediate' | 'cron' | 'interval' | 'once' | 'event' - `cron_expression` string, nullable - `interval_seconds` integer, nullable - `scheduled_at` string, date-time, nullable - `timezone` string - `model_id` string, nullable - `agent` 'business' | 'engineering': Which agent runs the task. Use `engineering` for pure code/build work on a site; defaults to `business`. - `condition_script` string, nullable: Cheap pre-run gate for recurring tasks (`cron`/`interval`). Plain JavaScript run in a sandboxed isolate against the same `crevioApi.*` connector as the execute tool, BEFORE each scheduled run — no LLM, no credits. The task only runs when the script's last expression (or explicit `return`) is truthy; it skips on `false`/`null`. **Default to setting this whenever the task is "act only when X"** (new/unfulfilled/failed records, a threshold crossed, an unread inbox, a metric at zero) — without it the agent wakes and spends credits on every tick even when there's nothing to do. Only omit it for tasks that genuinely should run every tick (e.g. a scheduled report the user always wants). End with a boolean, e.g. `const r = await crevioApi.listOrders({ status: 'succeeded' }); r.data.some(o => o.fulfillment_status !== 'fulfilled')`. Errors fail open (the task runs). Ignored for non-recurring triggers. - `pre_run_script` string, nullable - `script` string, nullable: JavaScript run on the account's computer on each run; its logs and return value become the run's summary. Required for `kind: script`, must be absent for `kind: agent`. - `approval_mode` 'autonomous' | 'supervised' | 'read_only' - `expires_at` string, date-time, nullable - `active` boolean - `visibility` 'account' | 'personal' - `max_runs_per_day` integer, nullable: Event tasks only: at most this many runs started by events per calendar day, in the account's time zone. Every further event that day is recorded as a skipped run (`skip_reason: rate_limited`) and starts nothing, webhook deliveries included. Test runs don't count. Set it whenever the user names a daily cap; `null` removes it. - `min_interval_seconds` integer, nullable: Event tasks only: cooldown after a run started by an event. An event within this many seconds of that run is recorded as a skipped run (`skip_reason: rate_limited`) and starts nothing. Set it whenever the user says "at most once every N minutes"; `null` removes it. - `delivery_methods` string[]: Where each run's result is delivered. Omit it to get the default, in-app notification plus email; set it only when the user asked for a specific channel. `[]` delivers nowhere. - `event_conditions` object, nullable: Event tasks only: what starts a run. `event_type` is one event from GET /v1/events. To run after another task finishes, use `{event_type: "task_run.completed", after_task_id: "task_..."}` (or `task_run.failed` to run when it fails): each real run of that task that finishes starts this one, and the run receives the finished run (id, summary, status) as `event.data.object`. Test runs start nothing. A chain that loops back on itself or runs longer than 5 tasks is refused. `email_message.*` events also take `inbox_id`; `external.slack.*` events take `channel_id`, `from_user_id`, `reaction` and `channel_type`; `external.discord.*` events (`message`, `mention`, `reaction_added`) take `channel_id`, `from_user_id`, `emoji` and `guild_id`. - `site_id` string: Site this task works on (`site_...`); its repo is mounted as the run's workspace. Defaults to the account's default working site. ## Response `200` Task updated - AiTask - `id` string, required - `object` string, required - `name` string, required - `description` string, nullable, required - `kind` 'agent' | 'script', required - `prompt` string, nullable, required - `success_criteria` string, nullable, required - `trigger_type` 'immediate' | 'cron' | 'interval' | 'once' | 'event', required - `cron_expression` string, nullable, required - `interval_seconds` integer, nullable, required - `scheduled_at` string, date-time, nullable, required - `event_conditions` object, nullable, required - `condition_script` string, nullable, required - `pre_run_script` string, nullable, required - `script` string, nullable, required - `timezone` string, required - `delivery_methods` string[], required - `approval_mode` 'autonomous' | 'supervised' | 'read_only', required - `model_id` string, nullable, required - `agent` 'business' | 'engineering', required - `visibility` 'account' | 'personal', required - `active` boolean, required - `expires_at` string, date-time, nullable, required - `next_run_at` string, date-time, nullable, required - `last_run_at` string, date-time, nullable, required - `total_runs_count` integer, required - `consecutive_failure_count` integer, required - `total_credits_consumed` integer, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `max_runs_per_day` integer, nullable, required: Event tasks: the most event-started runs per day (account time zone); later events are skipped as `rate_limited`. - `min_interval_seconds` integer, nullable, required: Event tasks: the cooldown after an event-started run; events inside it are skipped as `rate_limited`. - `site_id` string, nullable, required - `source` 'user' | 'agent' | 'system', required: How the task came to exist: `user` (a person made it in the dashboard), `agent` (the agent made it inside the chat `origin_chat_id`, whose person is `created_by_id`), or `system` (a built-in task). - `created_by_id` string, nullable, required: The person (`user_...`) who made the task or asked for it. Null for built-in tasks. - `created_by_name` string, nullable, required - `origin_chat_id` string, nullable, required: The chat (`aichat_...`) the task was set up in. A member's chat opens only for that member. - `recent_runs` AiTaskRunSummary[], required: The task's newest executed runs (at most 5, newest first; skipped and test runs excluded). - `id` string, required - `status` 'pending' | 'running' | 'completed' | 'failed' | 'needs_input' | 'timed_out' | 'unknown' | 'skipped', required - `created_at` string, date-time, required - `completed_at` string, date-time, nullable, required - `error_message` string, nullable, required - `chat_id` string, nullable, required ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Forbidden - `404`: Resource not found - `422`: Validation error - `429`: Rate limit exceeded — 600 requests per minute per credential. Retry after the number of seconds in `Retry-After`. - `500`: Internal server error --- [API](https://skmtc.dev/crevio/apis/crevio-api-v1.md) · [All operations](https://skmtc.dev/crevio/apis/crevio-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/crevio/apis/crevio-api-v1/revisions/2219f18ad651?raw)