Operational Workflows

An Operational Workflow is a recipe Ragtime runs for your organization. It starts when something happens, moves data through connected steps, and records what happened at each stage.

Unlike an action or a conversation stage, a workflow does not live inside one chat session. It runs on the server and can continue after the conversation ends, wait safely, retry external work, and resume without repeating completed steps.

Workflows are configured in Dashboard -> Workflows.

A workflow in plain language

Every workflow answers three questions:

1. When should this start? This is the trigger.
2. What should happen next? These are the connected steps.
3. What counts as done or failed? These are the final outcomes.

For example:

1. Start when a Ragtime conversation ends.
2. Ask a published assistant snapshot to produce a structured support summary.
3. Check whether the summary needs follow-up.
4. Add a public reply to a support ticket and set its status to pending.
5. Finish and store the output, or follow an error path if the ticket update fails.

Each time the recipe starts, Ragtime creates a run. The run records its status, current step, output, errors, and event history.

Ways to start a workflow

A trigger can start a run:

• manually or through the workflow run API;
• from a signed webhook sent by another system;
• when a supported Ragtime event occurs, such as a session ending or an action completing;
• on a five-field cron schedule in a chosen timezone;
• from an event reported by a configured connector.

Use idempotency keys when an external caller may send the same event more than once. This prevents duplicate requests from creating duplicate work.

Building blocks

After its trigger, a workflow can use these node types:

Map prepares or reshapes values for later steps.

Condition chooses a true or false path from the current data.

AI task sends focused instructions and structured input to a pinned, published assistant snapshot. Its output follows the schema you define.

Connector operation performs a supported action through an organization integration, such as posting to Slack or updating a Zendesk ticket.

HTTP request calls an endpoint that your organization has configured and approved. Methods, timeouts, and retry behavior are explicit.

Wait pauses for seconds, minutes, hours, or days. Ragtime stores a checkpoint and resumes from the next node rather than replaying earlier effects.

Complete returns the run’s output. Fail ends it with an intentional error. Fallible operations expose success and error paths so failure handling is part of the graph rather than an afterthought.

Drafts, publishing, and runs

Editing changes the draft only. Publishing validates the graph and creates an immutable version with pinned resources, so a live run cannot silently change halfway through because someone edited an assistant, endpoint, or connection.

Enable the workflow when its published version is ready to receive automatic triggers. Use the run history to inspect queued, running, waiting, completed, failed, or cancelled runs.

Build workflows through the API

Workflow drafts can be built from code, or by an AI tool through the MCP server (list_workflows, get_workflow, save_workflow, delete_workflow). A draft never runs: publishing and enabling stay in the dashboard.

Method	Path	Scope	What it does
GET	/api/v1/projects/{projectId}/workflows	workflows:read	The workflows, plus what a draft may refer to: HTTP endpoints, connections and their operations, actions, and published assistant versions.
POST	/api/v1/projects/{projectId}/workflows	workflows:write	Create a draft, optionally with its definition.
GET	/api/v1/projects/{projectId}/workflows/{workflowId}	workflows:read	The draft, its draftRevision, and problems: what publishing it would refuse.
PATCH	/api/v1/projects/{projectId}/workflows/{workflowId}	workflows:write	Change the draft. Send expectedDraftRevision; a draft changed since you read it is refused with 409, not overwritten.
DELETE	/api/v1/projects/{projectId}/workflows/{workflowId}	workflows:write	Remove it. It stops running; its runs and versions stay on record.

A definition is the editor’s own: nodes with an id, type, name and config, joined by edges. A step’s position may be left out and is laid out for you. Drafts are saved as sent, incomplete or not, as the editor saves them, and every answer lists what publishing would still refuse. A draft holds no secrets: HTTP steps name a registered endpoint and connector steps an existing connection. Each change is written to the audit log with the key’s id.

Run a workflow via the API

Start a live run of a workflow’s published version from your own system. You need an API key with the workflows:execute scope, and the workflow must be enabled and published.

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/workflows/{workflowId}/runs \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-48213-escalation" \
  -d '{ "input": { "ticketId": "48213", "priority": "high" } }'

The Idempotency-Key header is required, at most 255 characters. Send one unique key per logical run. A retry with the same key for the same workflow returns the original run instead of starting a new one.

The body is a JSON object with an optional input object (default {}). Any other field is rejected.

// 202 Accepted: a new run was started
{
  "run": {
    "id": "run-uuid-...",
    "workflowId": "workflow-uuid-...",
    "workflowVersionId": "version-uuid-...",
    "status": "queued",
    "mode": "live"
  },
  "created": true,
  "statusUrl": "/api/v1/projects/{projectId}/workflows/{workflowId}/runs/run-uuid-..."
}

A replay with an existing Idempotency-Key returns 200 with the same body and "created": false. Both responses set a Location header to statusUrl.

Check a run

Poll the run with the same scope:

curl https://your-ragtime-instance.com/api/v1/projects/{projectId}/workflows/{workflowId}/runs/{runId} \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

{
  "run": {
    "id": "run-uuid-...",
    "workflowId": "workflow-uuid-...",
    "workflowVersionId": "version-uuid-...",
    "mode": "live",
    "status": "completed",
    "output": { "summary": "Escalated to tier 2." },
    "errorCode": null,
    "startedAt": "2026-10-09T10:00:01Z",
    "completedAt": "2026-10-09T10:00:04Z",
    "cancelledAt": null,
    "createdAt": "2026-10-09T10:00:00Z",
    "expiresAt": null
  }
}

status is one of queued, running, waiting, completed, failed or cancelled.

Errors

Status	Code	Meaning
400	invalid_request	Missing or too long Idempotency-Key, or an invalid body.
404	not_found	Workflow (or run) not found in this project.
409	conflict	The workflow is disabled, or has no published version.

Authentication, scope, project and rate-limit refusals work the same on every endpoint; see Errors and Rate limits.

What makes a workflow durable?

Ragtime stores workflow state in PostgreSQL rather than treating the queue as the source of truth. Timed waits have persisted continuation checkpoints. Running jobs renew an execution lease, and an abandoned run can be recovered after that lease expires. A stale worker cannot finish a run after another worker has taken ownership.

In practical terms, a worker restart should delay work rather than erase it or repeat steps that already changed another system.

When to use something else

Use an Action for anything that happens inside the chat: a tool the model calls, questions for the visitor, or an event sent to your page.

Use conversation stages for conversational phases, instructions, and action scoping.

Use n8n when automation should be owned by your external n8n environment or needs connectors that are not available natively.