Tasks

Create task

Creates a new AI task. Use trigger_type to schedule it: immediate runs once right away, cron runs on a cron expression, interval runs every N seconds, once runs at a specific scheduled_at, event runs in response to account events, including another task finishing: event_conditions: {event_type: "task_run.completed", after_task_id: "task_..."} runs it after each real run of that task completes, so a step that depends on another never needs a polling schedule. For recurring tasks (cron/interval), add an optional condition_script — a cheap JavaScript gate that runs before each fire (no LLM, no credits) and skips the run unless its last expression is truthy, so the agent only wakes when there's work to do.

post/tasks

Request

  • Base URL: https://api.crevio.co/v1
  • URL: https://api.crevio.co/v1/tasks
  • Auth: API key in header Authorization

Headers

Idempotency-Keystring

Makes this write safe to retry: a repeat with the same key replays the first response instead of creating a second resource. Scoped to the account, remembered for 24 hours; reusing a key with a different payload is an error.

Request body

namestring
descriptionstring 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.

promptstring nullable

What the agent does on each run. Required for kind: agent, must be absent for kind: script.

success_criteriastring 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_expressionstring nullable
interval_secondsinteger nullable
scheduled_atstring date-time nullable
timezonestring
model_idstring nullable
agent'business' | 'engineering'

Which agent runs the task. Use engineering for pure code/build work on a site; defaults to business.

condition_scriptstring 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_scriptstring nullable
scriptstring 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_atstring date-time nullable
activeboolean
visibility'account' | 'personal'
max_runs_per_dayinteger 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_secondsinteger 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_methodsstring[]

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_conditionsobject 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_idstring

Site this task works on (site_...); its repo is mounted as the run's workspace. Defaults to the account's default working site.

Response

Task created

idstring required
objectstring required
namestring required
descriptionstring nullable required
kind'agent' | 'script' required
promptstring nullable required
success_criteriastring nullable required
trigger_type'immediate' | 'cron' | 'interval' | 'once' | 'event' required
cron_expressionstring nullable required
interval_secondsinteger nullable required
scheduled_atstring date-time nullable required
event_conditionsobject nullable required
condition_scriptstring nullable required
pre_run_scriptstring nullable required
scriptstring nullable required
timezonestring required
delivery_methodsstring[] required
approval_mode'autonomous' | 'supervised' | 'read_only' required
model_idstring nullable required
agent'business' | 'engineering' required
visibility'account' | 'personal' required
activeboolean required
expires_atstring date-time nullable required
next_run_atstring date-time nullable required
last_run_atstring date-time nullable required
total_runs_countinteger required
consecutive_failure_countinteger required
total_credits_consumedinteger required
created_atstring date-time required
updated_atstring date-time required
max_runs_per_dayinteger nullable required

Event tasks: the most event-started runs per day (account time zone); later events are skipped as rate_limited.

min_interval_secondsinteger nullable required

Event tasks: the cooldown after an event-started run; events inside it are skipped as rate_limited.

site_idstring 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_idstring nullable required

The person (user_...) who made the task or asked for it. Null for built-in tasks.

created_by_namestring nullable required
origin_chat_idstring nullable required

The chat (aichat_...) the task was set up in. A member's chat opens only for that member.

Changes

No recorded changes to this operation across all 2 revisions of this API.