Tasks (your AI workforce)

A Task is a standing instruction you give Crevio’s AI: a prompt, an agent, a schedule, and an autonomy level — persisted on your account and run automatically. Where a single API call does one thing once, a Task does it on the trigger you choose (now, on an interval, on a cron schedule, once at a time, or whenever an event fires) and records every execution as a Task Run you can inspect, approve, or feed input into. This is how the agent becomes a workforce instead of a one-shot tool. Tasks have the prefix task_ (object type task); runs have the prefix trun_ (object type task_run).

Tasks consume credits. Every run is one or more AI operations (messages, media generation, web research, calls), all metered pay-per-call. The Task object tracks lifetime spend in total_credits_consumed; each run reports its own credits_consumed. Check your balance with GET /usage.

Anatomy of a Task

POST /v1/tasks accepts these fields (params are top-level — no task wrapper):

name

string

The task’s display name.

description

string

An optional human description.

prompt

string

required

What you want the agent to do — the instruction it runs every time.

trigger_type

enum

required

One of immediate, cron, interval, once, event. See below.

agent

enum

business (default) or engineering. Business operates your account through the API; engineering writes and ships code on a Site.

approval_mode

enum

autonomous, supervised, or read_only. Controls how much human oversight each run requires.

delivery_methods

array

Where results are delivered: any of notification, email, telegram, discord, slack.

event_conditions

object

For event triggers: filters that must match the incoming event for the task to fire. See Events.

site_id

string

The Site (site_...) the task works on. Its repo is mounted as the agent’s workspace. Defaults to your account’s default site. Most relevant for the engineering agent.

model_id

string

Override the model used for the run.

cron_expression

string

Cron schedule (for trigger_type: cron).

interval_seconds

integer

Seconds between runs (for trigger_type: interval).

scheduled_at

date-time

When to run (for trigger_type: once).

timezone

string

Timezone for cron/scheduled_at, e.g. America/New_York.

expires_at

date-time

After this time the task stops running.

active

boolean

Whether the task is enabled. Set false to pause without deleting.

A created Task also returns scheduling and accounting state: next_run_at, last_run_at, total_runs_count, consecutive_failure_count, and total_credits_consumed.

Choosing an agent

Agent	What it does	When to use it
`business` (default)	Operates your business through the API: products, checkouts, customers, email, socials, web research, calls.	Marketing, ops, sales, reporting, follow-ups.
`engineering`	Writes and ships code on a Site — the repo is mounted as its workspace; it can build and deploy. Scope it with `site_id`.	Website changes, bug fixes, new features, deploys.

Triggers

trigger_type decides when a task runs. There are five, each with its own scheduling field.

`immediate` — run once, right now

Fires a single run the moment you create the task. Good for kicking off ad-hoc work asynchronously.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Draft launch tweets",
    "prompt": "Write 5 launch tweets for my new pottery course and save them as social drafts.",
    "trigger_type": "immediate",
    "agent": "business",
    "approval_mode": "supervised",
    "delivery_methods": ["notification"]
  }'

`cron` — run on a cron schedule

Recurring, calendar-based. Pair cron_expression with a timezone.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monday sales digest",
    "prompt": "Summarize last week’s orders, revenue, refunds, and top 5 products. Email me the report.",
    "trigger_type": "cron",
    "cron_expression": "0 9 * * MON",
    "timezone": "America/New_York",
    "agent": "business",
    "approval_mode": "autonomous",
    "delivery_methods": ["email", "notification"]
  }'

`interval` — run every N seconds

Fixed cadence, independent of the wall clock. Set interval_seconds.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly inbox triage",
    "prompt": "Check new customer emails, label them, and draft replies to anything urgent.",
    "trigger_type": "interval",
    "interval_seconds": 3600,
    "agent": "business",
    "approval_mode": "supervised",
    "delivery_methods": ["slack"]
  }'

`once` — run a single time at a future moment

Schedule a one-off with scheduled_at.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday price drop",
    "prompt": "Apply the BLACKFRIDAY discount to all active courses and announce it on social.",
    "trigger_type": "once",
    "scheduled_at": "2026-11-27T13:00:00Z",
    "timezone": "America/New_York",
    "agent": "business",
    "approval_mode": "autonomous",
    "delivery_methods": ["notification"]
  }'

`event` — run when something happens

The task lies dormant until a matching event fires (e.g. order.paid). Constrain which events trigger it with event_conditions.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome new buyers",
    "prompt": "When an order is paid, send the buyer a personalized welcome email and add them to the onboarding sequence.",
    "trigger_type": "event",
    "event_conditions": { "event": "order.paid" },
    "agent": "business",
    "approval_mode": "autonomous",
    "delivery_methods": ["notification"]
  }'

See the Events guide for the full list of subscribable events and how event_conditions works.

Autonomy: `approval_mode`

approval_mode is the human-in-the-loop dial. It decides whether a run can act on its own, must pause for your approval, or can only observe.

Mode	Behavior
`autonomous`	The agent runs end-to-end and takes actions (writes, sends, deploys) without asking. Best for trusted, well-scoped tasks.
`supervised`	The agent pauses at decisions that require approval. The run enters a needs-input state and waits for you to approve, deny, or provide input before continuing.
`read_only`	The agent can read and analyze but cannot make changes. Best for reporting, audits, and research.

The supervised loop

A supervised run pauses instead of acting, which fires the task_run.needs_input webhook event (and notifies you via your delivery_methods). You review it in the Crevio dashboard — approving the pending action or giving the agent direction — and it resumes from where it stopped. The cycle:

Run starts and reaches a checkpoint

The agent does its work until it hits an action that needs approval (or it needs information from you).

Run pauses in needs_input

The Task Run status becomes needs_input; task_run.needs_input fires and you’re notified.

You review and respond in the dashboard

Approve the pending action or give the agent more direction from the Crevio dashboard or notification. (Over the API you can read run state and update its status/summary — see below.)

Run resumes

The agent continues from the checkpoint and completes (or pauses again at the next one).

Task Runs

Each execution of a Task is a Task Run (trun_, object type task_run). Runs are read-mostly: you list and get them to inspect what happened, and PATCH them to update their status/summary.

The run object

Field	Description
`task_id`	The parent task (`task_...`).
`status`	Lifecycle state (e.g. running, needs-input, completed, failed).
`summary`	The agent’s natural-language summary of what it did.
`error_message`	Populated when the run failed.
`input_tokens` / `output_tokens`	Token usage for the run.
`credits_consumed`	Credits this run cost.
`tool_calls_count`	How many API/tool calls the agent made.
`duration_ms`	Wall-clock duration.
`started_at` / `completed_at`	Timestamps.

List and get runs

cURL
MCP (agent)

# List recent runs (optionally filter by task)
curl https://api.crevio.co/v1/task_runs \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get one run
curl https://api.crevio.co/v1/task_runs/trun_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Inside code_execute
runs = get("/task_runs")["data"]
runs.select { |r| r["status"] == "needs_input" }
    .map { |r| { id: r["id"], summary: r["summary"] } }

List responses use the standard envelope: { "object": "list", "data": [...], "has_more": bool }.

Updating a run’s state

PATCH /v1/task_runs/{id} updates a run’s state. The body accepts:

status

enum

pending, running, completed, failed, or needs_input.

summary

string | null

The run’s summary text.

error_message

string | null

An error message for a failed run.

input_tokens

integer

Recorded input token count.

output_tokens

integer

Recorded output token count.

For a run paused in needs_input, you resume or close it out by PATCHing status (and optionally summary/error_message) — for example set status to running to release it, or to completed/failed to close it.

curl -X PATCH https://api.crevio.co/v1/task_runs/trun_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "summary": "Reviewed and approved — sent the broadcast to paid customers."
  }'

The API lets you read run state and update status/summary — there is no field for sending free-form instructions back to the agent. The interactive back-and-forth for a supervised run (approving a pending action or giving the agent more direction in plain English) happens in the Crevio dashboard and notifications, not over the API.

Don’t poll for paused runs — subscribe to the task_run.needs_input, task_run.completed, and task_run.failed webhook events and react as they arrive.

Managing tasks

# Pause a task without deleting it
curl -X PATCH https://api.crevio.co/v1/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

# Delete a task
curl -X DELETE https://api.crevio.co/v1/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

A delete returns { "id": "task_abc123", "object": "task", "deleted": true }.

Next steps

Events & Event Sources

Fire event-Tasks from internal events and third-party apps.

AI & Agents overview

How Tasks fit into Crevio’s broader agentic model.

Webhooks

Get notified when runs complete, fail, or need your input.

Usage & credits

See how task runs are metered and check your balance.

​Anatomy of a Task

​Choosing an agent

​Triggers

​immediate — run once, right now

​cron — run on a cron schedule

​interval — run every N seconds

​once — run a single time at a future moment

​event — run when something happens

​Autonomy: approval_mode

​The supervised loop

​Task Runs

​The run object

​List and get runs

​Updating a run’s state

​Managing tasks

​Next steps

Events & Event Sources

AI & Agents overview

Webhooks

Usage & credits

Anatomy of a Task

Choosing an agent

Triggers

`immediate` — run once, right now

`cron` — run on a cron schedule

`interval` — run every N seconds

`once` — run a single time at a future moment

`event` — run when something happens

Autonomy: `approval_mode`

The supervised loop

Task Runs

The run object

List and get runs

Updating a run’s state

Managing tasks

Next steps