openapi: 3.1.0
info:
title: Process Street Public Attachments Workflow Runs 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: Workflow Runs
description: 'A workflow run is an active instance of a workflow. Each run tracks its own
progress, assignees, and form field values as it moves through the process.
Use these endpoints to create, update, and manage workflow runs.'
externalDocs:
url: https://www.process.st/help/docs/workflow-runs/
description: Process Street help article
paths:
/workflow-runs/{workflowRunId}/assignees/{email}:
post:
tags:
- Workflow Runs
summary: Assign a user to a workflow run
description: Assigns a user to a workflow run. If the user does not exist in your organization they will be invited as a Guest (Internal).
operationId: assignWorkflowRun
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
- name: email
in: path
description: Email
required: true
schema:
type: string
responses:
'204':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
delete:
tags:
- Workflow Runs
summary: Unassign a user from a workflow run
description: Unassigns a user from a workflow run.
operationId: unassignWorkflowRun
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
- name: email
in: path
description: Email
required: true
schema:
type: string
responses:
'204':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflow-runs/{workflowRunId}/assignees:
get:
tags:
- Workflow Runs
summary: List all assignees in a workflow run
description: '
Returns a list of workflow run assignees for the given workflow run.
The results are returned 20 at a time.
You must use the links section to get the next 20 results.
'
operationId: listWorkflowRunAssignees
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
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/ListChecklistAssigneesResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflow-runs:
get:
tags:
- Workflow Runs
summary: Search workflow runs
description: Returns the latest 200 workflow runs of a workflow, showing the most recently updated first.
operationId: searchWorkflowRuns
parameters:
- name: workflowId
in: query
description: The ID of the Workflow (can be copied from the Workflow URL in the web app)
required: false
schema:
type: string
- name: name
in: query
description: The partial name of the Workflow Run to search for (will match any part of the name in a case-insensitive manner)
required: false
schema:
type: string
- name: status
in: query
description: '
The status (or statuses) to filter by (Active, Completed or Archived).
If no status is provided, it will default to Active.
Multiple statuses can be provided as a comma-separated list.
'
required: false
schema:
type: string
- name: fields
in: query
description: '
The partial values of form field values to search for.
It will match any part of the value in a case-insensitive manner.
If there are multiple form field values, then Workflow Runs that match any of them will be returned.<br>
<br>
Example (before being URL-encoded):
<code>?fields[lD7FTF9R63xNCLn8w_xMdw]=value_1&fields[lD7FTF9R63xNCLn8w_xMab]=value_2</code>
'
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListWorkflowRunsResponse'
'400':
description: 'Invalid value for: query parameters'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
post:
tags:
- Workflow Runs
summary: Create a workflow run
description: Creates a new workflow run for the specified workflow.
operationId: createWorkflowRun
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWorkflowRunRequest'
examples:
Without a due date:
value:
workflowId: s3edbqqh3Frt6omN6hRJRg
name: Project Kickoff
With a due date:
value:
workflowId: lRYk9UlPHHr3MjgmZ8VEXQ
name: Q1 Inventory Audit
dueDate: '2026-04-01T14:53:24.897Z'
Shared:
value:
workflowId: rp_WIc5CiwCWFRCQDMBBLQ
name: Q1 Inventory Audit
shared: true
required: true
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWorkflowRunResponse'
'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: []
/workflow-runs/{workflowRunId}:
get:
tags:
- Workflow Runs
summary: Get a workflow run
description: Returns a workflow run by its ID.
operationId: getWorkflowRun
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetWorkflowRunResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
put:
tags:
- Workflow Runs
summary: Update a workflow run
description: 'A PUT request replaces all values, so all fields must be supplied in each request.
To remove a due date, you may send a null value or omit the field. See the examples for more.'
operationId: updateWorkflowRun
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWorkflowRunRequest'
examples:
Update name only:
value:
name: New Name
status: Active
shared: false
dueDate: '2026-07-20T00:00:00.000Z'
Removing the due date:
value:
name: Existing Name
status: Active
shared: false
Update status only:
value:
name: Existing Name
status: Completed
shared: false
dueDate: '2026-07-20T00:00:00.000Z'
Update shared status only:
value:
name: Existing Name
status: Active
shared: true
dueDate: '2026-07-20T00:00:00.000Z'
Update all fields:
value:
name: New Name
status: Active
shared: false
dueDate: '2026-08-03T00:00:00.000Z'
required: true
responses:
'204':
description: ''
'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:
- Workflow Runs
summary: Delete a workflow run
description: Deletes a workflow run by its ID.
operationId: deleteWorkflowRun
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
responses:
'200':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflow-runs/list:
get:
tags:
- Workflow Runs
summary: List all workflow runs
description: Returns a paginated list of workflow runs accessible to the calling user, sorted by creation date (newest first). Soft-deleted runs are excluded; only runs of workflow-type templates are returned (runs of page-type templates are out of scope).
operationId: listWorkflowRuns
parameters:
- name: workflowId
in: query
description: Filter results to runs of a specific workflow. If the workflow does not exist or is inaccessible, the response is an empty page rather than an error.
required: false
schema:
type: string
- name: status
in: query
description: 'Filter results by workflow run status.
- `Active` — the run is in progress.
- `Completed` — all tasks were completed and the run was finalised.
- `Archived` — the run was archived from the active list.
The internal `Deleted` status is hidden from the public API surface and rejected here.
Omit this filter to include all non-deleted runs.
'
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/PublicApiWorkflowRunListResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflow-runs/{workflowRunId}/undelete:
post:
tags:
- Workflow Runs
summary: Undelete a workflow run
description: Restores a previously deleted workflow run by its ID.
operationId: undeleteWorkflowRun
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
responses:
'200':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
components:
schemas:
ListWorkflowRunsResponse:
title: ListWorkflowRunsResponse
type: object
properties:
workflowRuns:
type: array
items:
title: PublicApiWorkflowRun
type: object
required:
- id
- audit
- status
- workflowId
- shared
- migrationStatus
properties:
id:
description: The ID of the Workflow Run
examples:
- uSjrFBxdhISklxIBfjlJpQ
type: string
audit:
title: AuditInfo
description: Creation and last-modification metadata.
type: object
required:
- createdDate
- createdById
- updatedDate
- updatedById
properties:
createdDate:
description: When the resource was first created. ISO-8601 UTC.
type: string
format: date-time
createdById:
title: EntityID
description: ID of the user who created the resource.
type: string
updatedDate:
description: When the resource was last modified. ISO-8601 UTC.
type: string
format: date-time
updatedById:
title: EntityID
description: ID of the user who last modified the resource.
type: string
name:
description: Display name of the workflow run (often interpolated from a name template).
type: string
status:
description: 'Lifecycle status of a workflow run.
- `Active` — the run is in progress.
- `Completed` — all tasks were completed and the run was finalised.
- `Archived` — the run was archived from the active list (no further task progress is recorded but the run stays queryable).
- `Deleted` — the run was soft-deleted.
List endpoints return only `Active` runs unless otherwise indicated.
'
type: string
enum:
- Active
- Completed
- Archived
- Deleted
workflowId:
description: The ID of the Workflow
examples:
- uSjrFBxdhISklxIBfjlJpQ
type: string
shared:
description: When `true`, this run is visible via its share link.
type: boolean
dueDate:
description: Optional workflow-level due date. ISO-8601 UTC.
type: string
format: date-time
migrationStatus:
description: 'Whether this run is currently being migrated to a newer workflow revision.
- `Inactive` — not in a migration; this is the normal state.
- `Scheduled` — a migration to a newer revision has been requested and is queued.
- `Migrating` — migration is in progress; some fields may change shortly.
'
type: string
enum:
- Inactive
- Scheduled
- Migrating
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
PublicApiWorkflowRunListResponse:
title: PublicApiWorkflowRunListResponse
type: object
properties:
data:
description: The list of resources returned by this request.
type: array
items:
title: PublicApiWorkflowRun
type: object
required:
- id
- audit
- status
- workflowId
- shared
- migrationStatus
properties:
id:
description: The ID of the Workflow Run
examples:
- uSjrFBxdhISklxIBfjlJpQ
type: string
audit:
title: AuditInfo
description: Creation and last-modification metadata.
type: object
required:
- createdDate
- createdById
- updatedDate
- updatedById
properties:
createdDate:
description: When the resource was first created. ISO-8601 UTC.
type: string
format: date-time
createdById:
title: EntityID
description: ID of the user who created the resource.
type: string
updatedDate:
description: When the resource was last modified. ISO-8601 UTC.
type: string
format: date-time
updatedById:
title: EntityID
description: ID of the user who last modified the resource.
type: string
name:
description: Display name of the workflow run (often interpolated from a name template).
type: string
status:
description: 'Lifecycle status of a workflow run.
- `Active` — the run is in progress.
- `Completed` — all tasks were completed and the run was finalised.
- `Archived` — the run was archived from the active list (no further task progress is recorded but the run stays queryable).
- `Deleted` — the run was soft-deleted.
List endpoints return only `Active` runs unless otherwise indicated.
'
type: string
enum:
- Active
- Completed
- Archived
- Deleted
workflowId:
description: The ID of the Workflow
examples:
- uSjrFBxdhISklxIBfjlJpQ
type: string
shared:
description: When `true`, this run is visible via its share link.
type: boolean
dueDate:
description: Optional workflow-level due date. ISO-8601 UTC.
type: string
format: date-time
migrationStatus:
description: 'Whether this run is currently being migrated to a newer workflow revision.
- `Inactive` — not in a migration; this is the normal state.
- `Scheduled` — a migration to a newer revision has been requested and is queued.
- `Migrating` — migration is in progress; some fields may change shortly.
'
type: string
enum:
- Inactive
- Scheduled
- Migrating
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: '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.'
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
GetWorkflowRunResponse:
title: GetWorkflowRunResponse
type: object
required:
- id
- audit
- status
- workflowId
- shared
- migrationStatus
properties:
id:
description: The ID of the Workflow Run
examples:
- v4dqILFV0FgvbS1myYlIew
type: string
audit:
title: AuditInfo
description: Creation and last-modification metadata.
type: object
required:
- createdDate
- createdById
- updatedDate
- updatedById
properties:
createdDate:
description: When the resource was first created. ISO-8601 UTC.
type: string
format: date-time
createdById:
title: EntityID
description: ID of the user who created the resource.
type: string
updatedDate:
description: When the resource was last modified. ISO-8601 UTC.
type: string
format: date-
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/process-street/refs/heads/main/openapi/process-street-workflow-runs-api-openapi.yml