Skip to main content
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. 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

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 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.
Last modified on November 15, 2026