usertasksDocs
Sign in

Getting started

Concepts

The building blocks of UserTasks — workflows, runs, tasks, integrations, rules, data — and how they fit together.

UserTasks is a headless workflow engine: it runs your processes and exposes everything through a REST API, an MCP server and a CLI, so your own applications and AI clients can drive it. It also ships a complete web app (designer, task list, settings) for the people who build and operate those processes.

Workspaces

Everything belongs to a workspace (a tenant). Data is isolated per workspace by Postgres row-level security and server-side checks. People are members of one or more workspaces with roles that grant permissions.

Workflows and runs

A workflow is a graph of nodes: one trigger, then logic, operations and actions joined by edges. You edit a draft and publish it; each publish creates an immutable version. A run is one execution of the published version. Runs carry variables, write a step-by-step log, and can wait: for a person (User Task), for a time (delay, pause until), or for an external event. Waiting runs are resumed from a durable queue.

Tasks

A task is work for a person. User Task nodes create tasks with typed fields and outcomes; completing the task (in the app, through the API, MCP or CLI) resumes the run on the outcome's path. Tasks have assignees or teams, due dates, SLAs, reminders and escalation.

Reusable assets

AssetWhat it isUsed from
IntegrationA connection to an external system (base URL + authentication)References
ReferenceOne saved operation on an integration (REST, OData or a database query)Call API / Reference nodes, agents, reports, MCP
ConnectorA pre-built integration for a known serviceIntegrations
Decision tableOrdered business rules: inputs in, outputs outDecision Table node, API, MCP
Data tableA typed table inside UserTasksData node, triggers, reports, OData
Email templateSubject and HTML with variablesSend Email node, task notifications
Custom workflow stepYour own code as a typed nodeCustom Activity node
AI agentA model with instructions, tools and an output schemaRun Agent node, API, MCP
ReportA saved query and chart over tasks, runs or dataApp, API, MCP

Surfaces

Every operation is available four ways, and they enforce the same permissions:

  • the web app for designers, approvers and admins;
  • the REST API at /api/v1 (API), described by an OpenAPI 3.1 document;
  • the MCP server at /api/mcp (MCP) for AI assistants;
  • the CLI usertasks (CLI) and the TypeScript SDK.

Configuration moves between workspaces as files: config as code and GitHub sync. Everything that happens is recorded in an event stream you can tail or ship to your log platform.

Common use cases

Worked examples with an architecture sketch, the features involved and a snippet (all use cases):