> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Usertick runs surveys on websites, by link, by QR code and by email, and collects every response in one inbox with reports, dashboards and workflows. The REST API lives at https://app.usertick.com/api/public/v1 and uses Bearer API keys or OAuth access tokens; the JavaScript SDK is the @usertick/snippet package on npm.

# Workflow drafts

> Read workflows and their runs, and create and edit workflows as drafts. A person publishes a workflow in Usertick, which also turns it on.

The workflow endpoints read the workflows in **Workflows** and their runs, and write their drafts. A workflow the API creates starts switched off, and an edit changes only its draft, so nothing runs until a person publishes the workflow in Usertick, which also turns it on. The API never publishes, turns on or off, duplicates or deletes a workflow, and never retries or resumes a run.

| Endpoint | Scopes | Does |
| - | - | - |
| [`GET /workflows/capabilities`](https://docs.usertick.com/developers/api/reference/get-workflow-capabilities) | `workflows:draft` | Lists the triggers, conditions, step kinds, actions, connected tools and limits |
| [`GET /workflows`](https://docs.usertick.com/developers/api/reference/list-workflows) | `workflows:read` | Lists the organization's workflows |
| [`GET /workflows/{workflowId}`](https://docs.usertick.com/developers/api/reference/get-workflow) | `workflows:read` | Returns a workflow with its draft and what runs |
| [`POST /workflows`](https://docs.usertick.com/developers/api/reference/create-workflow) | `workflows:draft`, `workflows:read` | Creates a workflow switched off |
| [`PATCH /workflows/{workflowId}/draft`](https://docs.usertick.com/developers/api/reference/edit-workflow-draft) | `workflows:draft`, `workflows:read` | Replaces a workflow's draft or renames it |
| [`GET /workflows/{workflowId}/runs`](https://docs.usertick.com/developers/api/reference/list-workflow-runs) | `workflows:read` | Lists a workflow's runs, newest first |
| [`GET /workflows/runs/{runId}`](https://docs.usertick.com/developers/api/reference/get-workflow-run) | `workflows:read`, `responses:read` | Returns one run with its steps |

For an app or an AI assistant, every endpoint requires the **Manage workflows** permission, just as the **Workflows** page does. Because a run holds the response that started it, reading one also requires `responses:read`, and an app or assistant acting for a person whose role reaches only selected surveys can't read runs and gets `403` with `AUTHZ-007-001`. Every draft written through the API appears in the activity log as made through the credential and uses no AI credits.

## The workflow

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "name": "Bugs to Slack",
  "status": "draft",
  "hasUnpublishedChanges": false,
  "draftVersion": 1,
  "draft": {
    "trigger": { "event": "response.analyzed", "surveyIds": ["11111111-1111-4111-8111-111111111111"], "match": "all",
                 "conditions": [{ "field": "ai.type", "op": "in", "value": ["bug"] }], "x": 0, "y": 0 },
    "steps": [{ "id": "s1", "kind": "action", "x": 0, "y": 140, "action": "slack.post_message", "connectionId": null,
                "params": { "text": "New bug report" }, "match": "all", "conditions": [], "waitSeconds": null }],
    "wires": [{ "from": "trigger", "port": "out", "to": "s1" }]
  },
  "published": null,
  "publishIssues": [{ "code": "action_connection", "stepId": "s1", "field": null }],
  "warnings": [],
  "editorUrl": "https://app.usertick.com/workflows/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb?org=3c9e4e1a-5b7d-4f20-9a61-0c2d8e4f6a10"
}
```

| Field | Meaning |
| - | - |
| `status` | `draft` until a person first publishes the workflow, then `active`, `disabled` or `paused`. |
| `draft` | The workflow as the editor holds it: the `trigger`, the `steps` and the `wires` between them. |
| `published` | What runs now; `null` while the workflow was never published. |
| `hasUnpublishedChanges` | The draft holds changes that don't run yet. |
| `publishIssues` | What a person must finish before publishing, each on its step (`null` for the trigger or the whole flow), such as a step without its connection. |
| `editorUrl` | Opens the workflow editor in Usertick, where a person publishes it. |

## The draft

* The **trigger** has an `event` of `response.created`, `response.analyzed` (after Usertick's analysis), `response.urgent` or `metric.threshold`, an alarm that starts when a number of the survey crosses a line (`alert` holds its settings). `surveyIds` names the workflow's one survey, and a survey the credential can't read returns `404` with `APK-006-005`. `conditions` and `match` decide which events start a run.
* Each of the **steps** has an `id`, a `kind` (`action`, `branch` or `wait`) and a place (`x`, `y`). An action names its `action` key, its `connectionId` and its `params`, a branch names its `conditions`, and a wait names its `waitSeconds`.
* Each of the **wires** leads from a step's port (`out`, or `yes` and `no` from a branch) to the next step, and the trigger's wire comes from `trigger`.

A step can leave its connection and settings for a person to finish, and `publishIssues` names what is missing. When neither the trigger nor any step names a place, Usertick arranges the flow the way the editor's **Tidy up** does. [`GET /workflows/capabilities`](https://docs.usertick.com/developers/api/reference/get-workflow-capabilities) lists the condition fields with their operators, the actions with their inputs, which actions the plan includes, and the organization's connected tools with their default connection.

Usertick checks the draft when it is written:

* An action key the catalog doesn't have returns `400` with `PUB-001-004`, naming the step, such as `draft.steps[2].action`.
* A `connectionId` that isn't a connection of the action's tool the organization can send with returns `400` with `PUB-016-002`.
* An action whose tool the plan leaves out returns `403` with `PLN-002-001`, and more steps that send to another tool than the plan allows in one workflow return `403` with `PLN-001-021`.
* A step's text longer than its tool accepts returns `400` with `WFL-003-010`, and a malformed draft returns `WFL-003-001`. A draft holds at most 200 steps, 600 wires and 512 KB.

## Create and edit a workflow

`POST /workflows` takes a `name` (1 to 200 characters) and a `draft`, and without a draft the workflow starts with a bare trigger. On a plan without workflows the call returns `403` with `PLN-002-001`, and for a survey that already has as many workflows as the plan allows it returns `403` with `PLN-001-011`. A successful call returns `201` with the workflow; give the person `editorUrl` so they can finish and publish it.

`PATCH /workflows/{workflowId}/draft` takes `expectedDraftVersion`, and a new `name`, a whole new `draft`, or both. The draft you send replaces the stored one, so read the workflow first and send the whole draft with your change in it.

* If the draft changed since you read it, the edit returns `409` with `PUB-016-004`, and you need to read the workflow again and redo the edit.
* While the workflow is open in the workflow editor in Usertick, the edit returns `409` with `PUB-016-003`.
* You can edit a published workflow too. What runs doesn't change until a person publishes, and the answer says `hasUnpublishedChanges: true` while the draft differs from the published workflow.

## Read runs

`GET /workflows/{workflowId}/runs` lists a workflow's runs, newest first, and its `status` parameter keeps one kind: `succeeded`, `failed`, `running` (queued, running and retrying), `skipped` or `held`. `GET /workflows/runs/{runId}` returns one run with each step's input, output and error, and `event`, the response as the run read it. An unknown run returns `404` with `PUB-016-005`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.