openapi: 3.1.0
info:
title: Process Street Public Attachments Workflows API
version: '1.1'
description: "The Process Street API is organized around REST. Our API has predictable resource-oriented URLs,\naccepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response\ncodes, authentication, and verbs.\n\nAn [MCP server](https://www.process.st/help/docs/mcp-server/) is also available for integrating with AI agents and tools.\n\n## Core concepts\n\n**Workflow vs Workflow Run.** A **Workflow** (sometimes called a \"playbook\" or template) is the reusable\ndefinition — tasks, form fields, logic, automations. A **Workflow Run** (sometimes called a \"checklist\")\nis one *instance* of running a Workflow. You list available templates via `listWorkflows`; you start one\nvia `createWorkflowRun` (or by scheduling); and you read or update the live state of an in-progress run\nvia the Workflow Runs / Tasks / Form Field Values endpoints. The two are easy to confuse — when in doubt,\n\"Workflow\" is the *blueprint*, \"Workflow Run\" is *one execution*.\n\n**Pages** are similar but standalone: a Page is a content document (no tasks/form fields). A\n**Page Revision** is a versioned snapshot of its content.\n\n## IDs\n\nAll resource IDs are opaque 22-character URL-safe strings (Muids — a base64-encoded UUID). Treat them\nas opaque tokens. Do not parse them, attempt to sort by them, or assume any internal structure. You can\ncompare two IDs for equality with a plain string comparison.\n\n## Dates and times\n\nAll timestamps in requests and responses are ISO-8601, UTC, with millisecond precision\n(e.g. `2024-09-15T14:32:00.000Z`). For date-only fields (typically due dates), use a calendar date\n(`2024-09-15`).\n\n## Pagination\n\nList endpoints page through results using an opaque cursor named `_` (yes, just an underscore).\nThe flow:\n\n1. Call the list endpoint without `_` to get the first page.\n2. Each response includes a `links[]` array. If there are more pages, you'll find an entry with\n `name: \"next\"` whose `href` is a fully-formed URL you can `GET` directly.\n3. Keep following `next.href` until the `next` link is absent — that's the end.\n\nYou can also reuse the `_` value from one response by passing it as the `_` query parameter on the\nnext request, but **following the `href` is simpler and forward-compatible**.\n\n## Authentication\n\nEvery request must include an API key as `X-API-KEY: <your-key>`. Generate keys from your\norganization settings in the Process Street app. Each key carries the permissions of the user that\ncreated it.\n\n## Idempotency and retries\n\n- `GET` requests are safe to retry on any error.\n- `PUT` requests are idempotent — calling them twice with the same body is equivalent to calling once.\n Safe to retry on `5xx`.\n- `DELETE` is idempotent (deleting an already-deleted resource returns `404`, which is fine to ignore).\n- `POST` is generally **not** safe to blindly retry. For workflow runs, attach a `referenceId`\n on create — calling `createWorkflowRun` twice with the same `referenceId` will return the existing\n run instead of creating a duplicate.\n\n## Errors\n\nErrors are returned as a JSON object with this shape:\n\n```json\n{\n \"error\": \"human-readable message\",\n \"errorCode\": \"NotFound\",\n \"requestId\": \"abc123…\",\n \"details\": { \"fieldPath\": \"what went wrong\" }\n}\n```\n\n**When present**, branch on `errorCode` rather than regex'ing `error` (we may rewrite the wording). Include\n`requestId` if you contact support so we can find the request in our logs.\n\n`errorCode` and `requestId` are populated on responses generated by the public API exception handler, which\ncovers the great majority of errors. A few low-level failures (e.g. JSON parse failures caught before the\nhandler runs, framework-level routing errors) may return an `ErrorInfo` without these fields. In that case,\nfall back to the HTTP status code (`400`/`401`/`403`/`404`/`409`/`422`/`429`/`5xx`) — its semantics match\nthe corresponding `errorCode` value.\n\n## Rate limits\n\nAll requests are subject to rate limits. If you receive a `429` response, wait for the duration\nspecified in the `Retry-After` header before retrying.\n"
servers:
- url: https://public-api.process.st/api/v1.1
tags:
- name: Workflows
description: 'A workflow is a reusable process template that defines the structure, tasks,
and form fields for a repeatable process. Use these endpoints to browse and
inspect your organization''s workflows.'
externalDocs:
url: https://www.process.st/help/docs/workflows/
description: Process Street help article
paths:
/workflows:
get:
tags:
- Workflows
summary: List all workflows
description: 'Returns a list of active workflows.
The workflows are returned 20 at a time, sorted by name.
You must use the links section to get the next 20 results.'
operationId: listWorkflows
parameters:
- name: name
in: query
description: The partial name of the Workflow to search for (will match any part of the name in a case-insensitive manner)
required: false
schema:
type: string
- name: _
in: query
description: 'Opaque pagination cursor. Take this value from the previous response''s `links[]` entry whose `name`
is `"next"` (typically just follow that link''s `href` instead of reading this value).
Omit on the first page. If the previous response had no `next` link, there are no more pages.'
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListWorkflowsResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
post:
tags:
- Workflows
summary: Create a workflow
description: 'Creates a new workflow with the specified properties. Only name and folderId are required.
> 💡 Notes for MCP clients:
> - Don''t default `shareLevel` to `Overview`/`View`/`Run` or `runLinkShareLevel` to `Public`. Only set them when the user explicitly asks for a shareable or public link.'
operationId: createWorkflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWorkflowRequest'
examples:
Create a workflow:
summary: Creates a new workflow with all properties specified
value:
name: Employee Onboarding
description: Standard onboarding workflow for new hires
folderId: iVqFVvR5lDLy1WVfdHFOYw
shareLevel: View
runLinkShareLevel: Organization
allowComments: true
sharedRunsByDefault: false
referenceId: ONB
Minimal workflow:
summary: Creates a workflow with only the required fields; optional fields use defaults
value:
name: Vendor Approval
folderId: qPIAxw6OI3bqZFdFdulIFA
shareLevel: None
runLinkShareLevel: Organization
allowComments: true
sharedRunsByDefault: false
required: true
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowResponse'
'400':
description: 'Invalid value for: body'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflows/{workflowId}:
get:
tags:
- Workflows
summary: Get a workflow
description: Returns a workflow by its ID.
operationId: getWorkflow
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
put:
tags:
- Workflows
summary: Update a workflow
description: 'Updates all properties of a workflow. All fields are required (PUT semantics).
> 💡 Notes for MCP clients:
> - Don''t default `shareLevel` to `Overview`/`View`/`Run` or `runLinkShareLevel` to `Public`. Only set them when the user explicitly asks for a shareable or public link.
Returns the updated workflow.'
operationId: updateWorkflow
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWorkflowRequest'
examples:
Update all fields:
summary: Sets all properties of a workflow including description and reference ID
value:
name: Employee Onboarding
description: Standard onboarding workflow for new hires
folderId: ku93urChWK42KKiwsN5AVQ
shareLevel: View
runLinkShareLevel: Organization
allowComments: true
sharedRunsByDefault: false
referenceId: ONB
Clear nullable fields:
summary: Sets all properties and clears the description and reference ID
value:
name: Employee Onboarding
folderId: srvv-fNHBFdyLcB3FOpPsw
shareLevel: View
runLinkShareLevel: Organization
allowComments: true
sharedRunsByDefault: false
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowResponse'
'400':
description: 'Invalid value for: body'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
delete:
tags:
- Workflows
summary: Delete a workflow
description: Soft deletes a workflow by its ID.
operationId: deleteWorkflow
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
responses:
'204':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflows/{workflowId}/tasks:
get:
tags:
- Workflows
summary: List all tasks in a workflow
description: 'Returns a list of tasks for a workflow.
The task templates are returned 20 at a time, sorted in order.
You must use the links section to get the next 20 results.'
operationId: listWorkflowTasks
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
- name: _
in: query
description: 'Opaque pagination cursor. Take this value from the previous response''s `links[]` entry whose `name`
is `"next"` (typically just follow that link''s `href` instead of reading this value).
Omit on the first page. If the previous response had no `next` link, there are no more pages.'
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListTaskTemplatesResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflows/{workflowId}/duplicate:
post:
tags:
- Workflows
summary: Duplicate a workflow
description: Creates a new workflow as a copy of the source workflow at a given revision. All body fields are optional — send `{}` to use defaults. `revisionId` defaults to the source workflow's latest published revision; `name` defaults to `"Copy of <original>"`; `folderId` defaults to the source workflow's folder.
operationId: duplicateWorkflow
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DuplicateWorkflowRequest'
examples:
Custom name and destination:
summary: Duplicates the source workflow's latest published revision into the given folder with a custom name
value:
name: Compliance review (template)
folderId: gCQXcBu54g1RNvLTrlhIdw
Defaults:
summary: Duplicates the source workflow's latest published revision into the source's folder, named "Copy of <original>"
value: {}
Specific revision:
summary: Duplicates a specific revision of the source workflow
value:
revisionId: n5XJjy-1PadXKi5nKplH0Q
required: true
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowResponse'
'400':
description: 'Invalid value for: body'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflows/{workflowId}/permissions:
get:
tags:
- Workflows
summary: Get permissions for a workflow
description: Returns the complete list of permissions on a workflow, one entry per user or group. `accessLevel` is `Custom` when the atom combination does not match a predefined level. Groups appear with synthetic `group-<id>@process.st` emails.
operationId: getWorkflowPermissions
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowPermissionListResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
put:
tags:
- Workflows
summary: Set permissions for a workflow
description: 'Replaces the full set of permissions for a workflow. PUT semantics: send the complete list to replace all existing permissions. Send an empty array to remove all user-addressable permissions. Accepts both user emails and group emails (groups appear in other endpoints with synthetic `group-<id>@process.st` emails). Note: the AllFreeMembers system group is managed automatically by the AllMembers system group and cannot be modified directly. Returns the resulting permissions.'
operationId: updateWorkflowPermissions
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WorkflowPermissionEntry'
examples:
Replace all permissions:
summary: Grant Jane edit access and John run access
value:
- email: jane@example.com
accessLevel: Edit
- email: john@example.com
accessLevel: Run
Clear all user permissions:
summary: Remove all user-addressable permissions (system-managed permits are preserved)
value: []
required: false
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowPermissionListResponse'
'400':
description: 'Invalid value for: body'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
components:
schemas:
DuplicateWorkflowRequest:
title: DuplicateWorkflowRequest
type: object
properties:
revisionId:
title: EntityID
type: string
name:
description: Display name.
type: string
maxLength: 255
folderId:
title: EntityID
description: The ID of the Folder.
type: string
ListWorkflowsResponse:
title: ListWorkflowsResponse
type: object
properties:
workflows:
type: array
items:
title: PublicApiWorkflow
type: object
required:
- id
- audit
- name
properties:
id:
title: EntityID
description: The resource's ID.
type: string
audit:
title: PublicApiAudit
description: Creation and last-modification metadata.
type: object
required:
- createdDate
- createdBy
- updatedDate
- updatedBy
properties:
createdDate:
description: When the resource was first created. ISO-8601 UTC.
type: string
format: date-time
createdBy:
title: PublicApiUser
description: User who created the resource.
examples:
- id: iAaSNCU5lWLYGAi663hO8Q
email: jane.doe@example.com
username: Jane Doe
type: object
required:
- id
- email
- username
properties:
id:
title: EntityID
description: The resource's ID.
type: string
email:
description: The user's email address (also their login identifier).
type: string
username:
description: The user's display name (e.g. `Jane Doe`).
type: string
updatedDate:
description: When the resource was last modified. ISO-8601 UTC.
type: string
format: date-time
updatedBy:
title: PublicApiUser
description: User who last modified the resource.
examples:
- id: iAaSNCU5lWLYGAi663hO8Q
email: jane.doe@example.com
username: Jane Doe
type: object
required:
- id
- email
- username
properties:
id:
title: EntityID
description: The resource's ID.
type: string
email:
description: The user's email address (also their login identifier).
type: string
username:
description: The user's display name (e.g. `Jane Doe`).
type: string
name:
description: The workflow's name.
type: string
description:
description: Optional long-form description of the workflow.
type: string
links:
description: 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.
type: array
items:
title: Link
description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
type: object
required:
- name
- href
- type
properties:
name:
description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
type: string
href:
title: Uri
description: URL of the linked resource.
examples:
- https://api.process.st/api/v1.1/resource/XXX
type: string
rel:
description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
type: string
enum:
- Approval Task
- Approvals
- Assignees
- Comment
- Data Set Records
- Data Sets
- Form Field Values
- Subject Task
- Task
- Tasks
- Users
- Webhook
- Workflow
- Workflow Run
type:
description: 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.
type: string
enum:
- Api
- App
links:
description: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 relation), an `href` URL, and a `type` (`Api` or `App`).
type: array
items:
title: Link
description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
type: object
required:
- name
- href
- type
properties:
name:
description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
type: string
href:
title: Uri
description: URL of the linked resource.
examples:
- https://api.process.st/api/v1.1/resource/XXX
type: string
rel:
description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
type: string
enum:
- Approval Task
- Approvals
- Assignees
- Comment
- Data Set Records
- Data Sets
- Form Field Values
- Subject Task
- Task
- Tasks
- Users
- Webhook
- Workflow
- Workflow Run
type:
description: 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.
type: string
enum:
- Api
- App
CreateWorkflowRequest:
title: CreateWorkflowRequest
type: object
required:
- name
- folderId
- shareLevel
- runLinkShareLevel
- allowComments
- sharedRunsByDefault
properties:
name:
description: Display name.
type: string
maxLength: 255
minLength: 1
description:
description: Optional free-form description of the workflow.
type: string
maxLength: 255
folderId:
description: The ID of the Folder
examples:
- ryhpzuZLct_nxa6wt2tABg
type: string
shareLevel:
description: Controls who can access this workflow. `None` — only organization members can view and run this workflow (when permitted). `Overview` — used only for Forms; viewers see the form name and background image but not the content. `View` — anyone with the link can view this workflow. `Run` — anyone with the link can view and run this workflow. Setting this to any value other than `None` may return `403 Forbidden` ("too new") — anti-spam protection blocks organizations without an eligible paid subscription outright, and blocks startup-plan organizations younger than 7 days.
type: string
enum:
- None
- Overview
- View
- Run
runLinkShareLevel:
description: Controls who can run this workflow via a run link. `Organization` — only authenticated organization members with run permission can use the run link. `Public` — anyone with the link can run the workflow without a Process Street account; all runs created from a public link are automatically shared. Setting this to `Public` may return `403 Forbidden` ("too new") — anti-spam protection blocks organizations without an eligible paid subscription outright, and blocks startup-plan organizations younger than 7 days.
type: string
enum:
- Organization
- Public
allowComments:
description: When `true`, comments are enabled on workflow runs created from this workflow.
type: boolean
sharedRunsByDefault:
description: When `true`, new workflow runs created from this workflow have their share link enabled by default. Recipients of the share link can fill in form fields and complete tasks without a Process Street account.
type: boolean
referenceId:
description: Version prefix used when version control is enabled on this workflow. Combined with the version number to form the full version identifier.
type: string
maxLength: 100
ListTaskTemplatesResponse:
title: ListTaskTemplatesResponse
type: object
properties:
tasks:
type: array
items:
title: PublicApiTaskTemplate
type: object
required:
- id
- audit
- workflowId
- orderTree
- stopTask
- hiddenByDefault
- taskType
properties:
id:
title: EntityID
description: The resource's ID.
type: string
audit:
title: PublicApiAudit
description: Creation and last-modification metadata.
type: object
required:
- createdDate
- createdBy
- updatedDate
- updatedBy
properties:
createdDate:
description: When the resource was first created. ISO-8601 UTC.
type: string
format: date-time
createdBy:
title: PublicApiUser
description: User who created the resource.
examples:
- id: iAaSNCU5lWLYGAi663hO8Q
email: jane.doe@example.com
username: Jane Doe
type: object
required:
- id
- email
- username
properties:
id:
title: EntityID
description: The resource's ID.
type: string
email:
description: The user's email address (also their login identifier).
type: string
username:
description: The user's display name (e.g. `Jane Doe`).
type: string
updatedDate:
description: When the resource was last modified. ISO-8601 UTC.
type: string
format: date-time
updatedBy:
title: PublicApiUser
description: User who last modified the resource.
examples:
- id: iAaSNCU5lWLYGAi663hO8Q
email: jane.doe@example.com
username: Jane Doe
type: object
required:
- id
- email
- username
properties:
id:
title: EntityID
description: The resource's ID.
type: string
email:
description: The user's email address (also their login identifier).
type: string
username:
description: The user's display name (e.g. `Jane Doe`).
type: string
workflowId:
title: EntityID
description: The ID of the Workflow.
type: string
name:
description: Display name of the task template.
type: string
orderTree:
description: Opaque ordering token; task templates sort lexicographically by this value within a revision.
type: string
stopTask:
description: When `t
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/process-street/refs/heads/main/openapi/process-street-workflows-api-openapi.yml