Workflows and tasks

A workflow is a graph of steps that starts on a signal, on a schedule or on a person’s request. A run is one execution of a workflow. A task is a piece of work for a person or an agent. Every call uses the token of a member and shows only what that member may see.

Workflows

A member sees a workflow when it is shared with the workspace, when the member owns it, or when it is shared with the member or a department. A member who may edit every agent sees all of them. A call that changes a workflow returns 403 with You cannot change this workflow. when the role does not allow it.

Task	Call
List workflows. Add `?active=1` for the switched-on ones.	`GET /api/v1/workflows`
Read a page of workflows. Filters: `show` (`agents` or `apps`), `state` (`on` or `off`), `q`. Sorts: `name`, `state`, `updated`.	`GET /api/v1/workflows/table`
Create a workflow.	`POST /api/v1/workflows`
Read one, with its `problems`.	`GET /api/v1/workflows/{workflow_id}`
Change one.	`PATCH /api/v1/workflows/{workflow_id}`
Archive one. It is switched off and kept with its runs.	`DELETE /api/v1/workflows/{workflow_id}`
Read its saved versions, newest first.	`GET /api/v1/workflows/{workflow_id}/versions`
Check the graph.	`POST /api/v1/workflows/{workflow_id}/validate`
Run it now.	`POST /api/v1/workflows/{workflow_id}/run`
Read or change who sees it.	`GET`, `POST /api/v1/workflows/{workflow_id}/sharing`
Read the step types, signals and tools a graph can use. Add `?q=` to narrow it.	`GET /api/v1/workflows/palette`
Read the library of templates, one template, and make your own workflow from it.	`GET /api/v1/workflows/templates`, `GET /api/v1/workflows/templates/{slug}`, `POST /api/v1/workflows/templates/{slug}/use`

Create a workflow

curl -X POST https://api.impellabs.tech/api/v1/workflows \
  -H "Authorization: Bearer imp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome a new lead",
    "description": "Starts when a form comes in.",
    "graph": {
      "nodes": [
        {"id": "start", "type": "trigger", "data": {"on": "signal", "signal": "lead.submitted"}},
        {"id": "finish", "type": "end", "data": {"resolution": "welcomed"}}
      ],
      "edges": [{"source": "start", "target": "finish"}]
    }
  }'

The reply is the workflow, with status 201. It carries id, name, slug, description, graph, is_active, trigger_signal, version, summary, starts, steps, owner_id, can_edit, sharing, problems and the times. A new workflow is off.

name is required, up to 255 characters. graph is required on create.
A graph has nodes and edges. A node has id, type, data and an optional position. An edge has source, target and an optional sourceHandle.
The graph has one trigger step. Its on is signal, schedule or manual. The step types, the settings of each one and the signals you can start on come from GET /api/v1/workflows/palette. The signal names are the event types.
A changed graph is saved as the next numbered version. is_active must be true or false. A workflow with problems cannot be switched on. The call returns 400 with detail and a list of problems, each {node_id, message}.

Run a workflow

curl -X POST https://api.impellabs.tech/api/v1/workflows/WORKFLOW_ID/run \
  -H "Authorization: Bearer imp_..." \
  -H "Content-Type: application/json" \
  -d '{"input": {"note": "Started from my system"}, "test": false}'

The body takes input (an object), agent_id and test. A live run needs the workflow on: otherwise the call returns 409 with This workflow is switched off. A workflow with problems returns 400. The reply is the run, with status 201.

Runs

Task	Call
List runs. Filters: `workflow`, `status`, `agent`.	`GET /api/v1/workflows/executions`
Read one run, with its steps, context and transcript.	`GET /api/v1/workflows/executions/{execution_id}`
Stop a run.	`POST /api/v1/workflows/executions/{execution_id}/cancel`
Start the same run again on the workflow as it is now. The old run stops and stays.	`POST /api/v1/workflows/executions/{execution_id}/rerun`
Answer the approval card a run waits on. Body: `{"approved": true, "note": "..."}`.	`POST /api/v1/workflows/executions/{execution_id}/decide`

A run has id, workflow, workflow_name, version, agent_id, test, status, current_node_id, step_count, wake_at, wait_kind, resolution and last_error. A test run belongs to the person who started it. Stopping a run that already ended returns 409. decide returns 409 when the run does not wait for an approval, and only the person the card names can answer it.

Tasks

A task has a title, notes, an assignee (a person or an agent), a due time, a reminder, a priority, a status, a board stage, a list, labels, a checklist and links to a conversation, a contact or an app record.

curl -X POST https://api.impellabs.tech/api/v1/tasks \
  -H "Authorization: Bearer imp_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Call Sam about the offer", "due_at": "2026-11-03T17:00:00+04:00", "priority": "high"}'

{
  "id": "…",
  "title": "Call Sam about the offer",
  "notes": "",
  "kind": "",
  "assignee": {"type": "member", "id": "…", "name": "Alex"},
  "due_at": "2026-11-03T13:00:00+00:00",
  "remind_at": null,
  "priority": "high",
  "status": "open",
  "overdue": false,
  "stage": null,
  "position": 0,
  "list": null,
  "labels": [],
  "checklist": [],
  "repeat": "",
  "refs": {"case_id": null, "contact_id": null, "app": null, "entity": null, "record_id": null},
  "comment_count": 0,
  "can_edit": true
}

The reply has more keys: repeated_from, source, created_by, completed_at, created_at and updated_at. The request takes title, notes, assignee, due_at, remind_at, priority (low, normal or high), status, stage_id, list_id, labels, checklist, repeat (empty, daily, weekdays, weekly or monthly), case_id, contact_id and record ({app, entity, record_id}). assignee is me, a member id or agent:<id>. Without it, the task is yours. Times need an offset. A task status is open, in_progress, done or cancelled.

Task	Call
List tasks.	`GET /api/v1/tasks`
Read, change or archive one.	`GET`, `PATCH`, `DELETE /api/v1/tasks/{task_id}`
Complete or reopen one.	`POST /api/v1/tasks/{task_id}/complete`, `/reopen`
Move the reminder. Body: `{"until": "..."}` or `{"minutes": 30}`.	`POST /api/v1/tasks/{task_id}/snooze`
Read or add comments.	`GET`, `POST /api/v1/tasks/{task_id}/comments`
Archive a comment. Its writer, an owner or an admin can.	`DELETE /api/v1/tasks/{task_id}/comments/{comment_id}`
Change many tasks.	`POST /api/v1/tasks/bulk`
Read the labels in use, and counts of overdue and due tasks.	`GET /api/v1/tasks/labels`, `GET /api/v1/tasks/summary`
Read or change the board stages and the lists.	`/api/v1/tasks/stages`, `/api/v1/tasks/lists`
Read whether Tasks is on. An owner or an admin turns it on with `POST`.	`GET`, `POST /api/v1/tasks/area`

The task list takes these filters: assignee (me, none, all, a member id or agent:<id>), status (also active and all), due (today, overdue or week), case, contact, list, stage, label, priority, source (agents or people), record (app:entity:id), q and offset. The reply is {"results": [...], "enabled": true, "next_offset": 50}. Send next_offset as offset for the next page. A page holds 50 tasks. POST /api/v1/tasks/bulk takes {"ids": [...], "action": "...", "value": ...} with up to 200 ids. The action is complete, reopen, cancel, archive, assign, due, priority, stage, list, label_add or label_remove. The reply is {"updated": n, "results": [...]}. Stages and lists can be created, ordered and removed by owners and admins. A stage has a kind of todo, doing or done.

App records

An app keeps its own records in entities. These calls read and write them for any installed app.

Task	Call
Read a page of records. Keys: `q`, `filter`, `sort`, `order`, `page`, `page_size`, `archived`.	`GET /api/v1/apps/{slug}/{entity}/records`
Create a record. Body: `{"values": {...}, "draft"?: true, "key"?: "...", "test"?: true}`.	`POST /api/v1/apps/{slug}/{entity}/records`
Read one record and its history.	`GET /api/v1/apps/{slug}/{entity}/records/{record_id}`
Change values. Body: `values`.	`PATCH /api/v1/apps/{slug}/{entity}/records/{record_id}`
Archive a record. It is kept and can be restored.	`DELETE /api/v1/apps/{slug}/{entity}/records/{record_id}`
Set a status of the entity.	`POST /api/v1/apps/{slug}/{entity}/records/{record_id}/status`
Bring back an archived record. It must be archived less than 30 days ago.	`POST /api/v1/apps/{slug}/{entity}/records/{record_id}/restore`

The page reply is {results, count, page, page_size, pages}. The page size is 20 unless you ask for another from 1 to 100. Read the entities and fields of an app from GET /api/v1/apps/{slug}. A record that does not exist returns 404 with There is no such record. ImpelLabs raises record.created, record.updated and record.status_changed when records change. A workflow or a webhook can start on them. See event types.

Get started

Resources

Events

Build

API reference