---
title: "Create a workflow task"
method: POST
path: "/workflows/{workflowId}/revisions/{revisionId}/tasks"
tags: ["Workflow Tasks"]
---

# Create a workflow task

`POST /workflows/{workflowId}/revisions/{revisionId}/tasks`

Creates a workflow task on a draft workflow revision. AI and Code tasks cannot have due date offsets or stop flags.
Task names can include merge tag variables (e.g. `{{workflow.name}}`).
Use the listWorkflowRevisionVariables endpoint to discover available variables.

> 💡 Notes for MCP clients:
> - Don't prefix task names with numbers (e.g. "1. ", "Task 1:"). The UI already shows a position number next to each task, and task order can change — hard-coded numbers go stale.
> - Consider adding content widgets to tasks with instructions, context, or guidance for the person running the workflow. Well-explained tasks make processes easier to follow.

## Path parameters

- `workflowId` string, required
- `revisionId` string, required

## Request body

- CreateWorkflowTaskRequest
  - `name` string — Display name.
  - `taskType` 'Standard' | 'Approval' | 'AI' | 'Code' — What the task does. - `Standard` — a regular task that a user manually checks off when done. - `Approval` — an approval task; a reviewer approves or rejects it, gating subsequent tasks. - `AI` — an automated task that runs an AI prompt to populate form field values. - `Code` — an automated task that runs a custom code snippet.
  - `stop` boolean
  - `hiddenByDefault` boolean — When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
  - `dueOffset` string
  - `position` union — Where to place this task in the workflow revision. `Top` — before all existing tasks. `Bottom` — after all existing tasks (default when `position` is omitted). `After` — immediately after the task identified by `taskId`.
    - object
      - `taskId` string, required — The ID of the Task.
      - `type` 'After', required — Discriminator value for this variant. See the parent oneOf for the full set of values.
    - object
      - `type` 'Bottom', required — Discriminator value for this variant. See the parent oneOf for the full set of values.
    - object
      - `type` 'Top', required — Discriminator value for this variant. See the parent oneOf for the full set of values.

## Response `201`

- PublicApiTaskTemplateResponse
  - `data` object, required
    - `id` string, required — The resource's ID.
    - `audit` object, required — Creation and last-modification metadata.
      - `createdDate` string, date-time, required — When the resource was first created. ISO-8601 UTC.
      - `createdBy` object, required — User who created the resource.
        - `id` string, required — The resource's ID.
        - `email` string, required — The user's email address (also their login identifier).
        - `username` string, required — The user's display name (e.g. `Jane Doe`).
      - `updatedDate` string, date-time, required — When the resource was last modified. ISO-8601 UTC.
      - `updatedBy` object, required — User who last modified the resource.
        - `id` string, required — The resource's ID.
        - `email` string, required — The user's email address (also their login identifier).
        - `username` string, required — The user's display name (e.g. `Jane Doe`).
    - `workflowId` string, required — The ID of the Workflow.
    - `name` string — Display name of the task template.
    - `orderTree` string, required — Opaque ordering token; task templates sort lexicographically by this value within a revision.
    - `stopTask` boolean, required — When `true`, this task acts as a stop — subsequent tasks within the revision are blocked until it's completed at runtime.
    - `hiddenByDefault` boolean, required — When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
    - `taskType` 'Standard' | 'Approval' | 'AI' | 'Code', required — What the task does. - `Standard` — a regular task that a user manually checks off when done. - `Approval` — an approval task; a reviewer approves or rejects it, gating subsequent tasks. - `AI` — an automated task that runs an AI prompt to populate form field values. - `Code` — an automated task that runs a custom code snippet.
    - `links` object[] — Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 link relation like `self`, `edit`, `related`), an `href` URL, and a `type` (`Api` for callable endpoints, `App` for browser-facing URLs). Prefer following these `href` values over constructing URLs by hand.
      - `name` string, required — Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
      - `href` string, required — URL of the linked resource.
      - `rel` 'Approval Task' | 'Approvals' | 'Assignees' | 'Comment' | 'Data Set Records' | 'Data Sets' | 'Form Field Values' | 'Subject Task' | 'Task' | 'Tasks' | 'Users' | 'Webhook' | 'Workflow' | 'Workflow Run' — Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
      - `type` 'Api' | 'App', required — Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
  - `links` object[] — Pagination links. When the result has more pages, look for an entry with `name: "next"` — its `href` is the URL to fetch the next page. Absence of `next` means there are no more pages. For single-resource responses this array is typically empty.
    - `name` string, required — Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
    - `href` string, required — URL of the linked resource.
    - `rel` 'Approval Task' | 'Approvals' | 'Assignees' | 'Comment' | 'Data Set Records' | 'Data Sets' | 'Form Field Values' | 'Subject Task' | 'Task' | 'Tasks' | 'Users' | 'Webhook' | 'Workflow' | 'Workflow Run' — Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
    - `type` 'Api' | 'App', required — Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.

## Other responses

- `400` — Invalid value for: body
- `default`

---

[API](https://skmtc.net/process/apis/process-street-public-api.md) · [All operations](https://skmtc.net/process/apis/process-street-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/process/process-street-public-api/revisions/6199a9464227/schema)