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
eventofresponse.created,response.analyzed(after Usertick’s analysis),response.urgentormetric.threshold, an alarm that starts when a number of the survey crosses a line (alertholds its settings).surveyIdsnames the workflow’s one survey, and a survey the credential can’t read returns404withAPK-006-005.conditionsandmatchdecide which events start a run. - Each of the steps has an
id, akind(action,branchorwait) and a place (x,y). An action names itsactionkey, itsconnectionIdand itsparams, a branch names itsconditions, and a wait names itswaitSeconds. - Each of the wires leads from a step’s port (
out, oryesandnofrom a branch) to the next step, and the trigger’s wire comes fromtrigger.
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
400withPUB-001-004, naming the step, such asdraft.steps[2].action. - A
connectionIdthat isn’t a connection of the action’s tool the organization can send with returns400withPUB-016-002. - An action whose tool the plan leaves out returns
403withPLN-002-001, and more steps that send to another tool than the plan allows in one workflow return403withPLN-001-021. - A step’s text longer than its tool accepts returns
400withWFL-003-010, and a malformed draft returnsWFL-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
409withPUB-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
409withPUB-016-003. - You can edit a published workflow too. What runs doesn’t change until a person publishes, and the answer says
hasUnpublishedChanges: truewhile 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.