openapi: 3.1.0
info:
title: Process Street Public Attachments Workflow Revisions 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 Revisions
description: 'A workflow revision is a versioned snapshot of a workflow''s structure.
Use these endpoints to list, inspect, and manage revisions.'
externalDocs:
url: https://www.process.st/help/docs/workflow-revisions/
description: Process Street help article
paths:
/workflows/{workflowId}/revisions:
get:
tags:
- Workflow Revisions
summary: List workflow revisions
description: Returns a paginated list of revisions for a workflow, optionally filtered by status.
operationId: listWorkflowRevisions
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
- name: status
in: query
description: 'Filter by status: Draft, Finished, or Revised.'
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/PublicApiWorkflowRevisionListResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
post:
tags:
- Workflow Revisions
summary: Create a workflow revision
description: Creates a new draft revision for a workflow from its current finished revision. Only one draft can exist at a time.
operationId: createWorkflowRevision
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowRevisionResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflows/{workflowId}/revisions/{revisionId}:
get:
tags:
- Workflow Revisions
summary: Get a workflow revision
description: Returns a workflow revision by its ID.
operationId: getWorkflowRevision
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowRevisionResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
put:
tags:
- Workflow Revisions
summary: Update a workflow revision
description: 'Updates a draft workflow revision. Only revisions in Draft status can be updated. PUT semantics: send all fields; optional fields omitted or set to null are cleared.
The checklist name template can include merge tag variables (e.g. `{{workflow.name}}`).
Use the listWorkflowRevisionVariables endpoint to discover available variables.
Returns the updated revision.'
operationId: updateWorkflowRevision
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWorkflowRevisionRequest'
examples:
Update all fields:
summary: Sets the change type, explanation, and default run name of a draft revision
value:
changeType: Material
changeExplanation: Added new approval step
defaultChecklistName: Onboarding - {{date}}
Clear nullable fields:
summary: Sets the change type and clears the explanation and default run name
value:
changeType: NonMaterial
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowRevisionResponse'
'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 Revisions
summary: Delete a workflow revision
description: Deletes a draft workflow revision. Only revisions in Draft status can be deleted.
operationId: deleteWorkflowRevision
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
required: true
schema:
type: string
responses:
'204':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflows/{workflowId}/revisions/{revisionId}/publish:
post:
tags:
- Workflow Revisions
summary: Publish a workflow revision
description: Publishes a draft workflow revision, transitioning it to Finished status. The previously finished revision becomes Revised.
operationId: publishWorkflowRevision
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiWorkflowRevisionResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflows/{workflowId}/revisions/{revisionId}/variables:
get:
tags:
- Workflow Revisions
summary: List workflow revision variables
description: Returns merge tag variables available in a workflow revision, filtered by type. Variables are returned in alphabetical order by label.
operationId: listWorkflowRevisionVariables
parameters:
- name: workflowId
in: path
description: The ID of the Workflow
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
required: true
schema:
type: string
- name: type
in: query
description: 'Filter by variable type: Standard, FormField, DataSet, EmailTrigger, or DocumentReview.'
required: true
schema:
$ref: '#/components/schemas/VariableType'
- 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/PublicApiWorkflowRevisionVariableListResponse'
'400':
description: 'Invalid value for: query parameter type'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
components:
schemas:
VariableType:
title: VariableType
description: 'The kind of merge tag variable this is.
- `Standard` — built-in variable like `{{workflow.name}}` or `{{run.startedDate}}`.
- `FormField` — resolves to a form field value on the workflow run.
- `DataSet` — resolves to a column from a linked data set row.
- `EmailTrigger` — populated from an inbound email that triggered the workflow run.
- `DocumentReview` — available on workflows using the Document Approvals feature.
'
type: string
enum:
- Standard
- FormField
- DataSet
- EmailTrigger
- DocumentReview
PublicApiWorkflowRevisionVariableListResponse:
title: PublicApiWorkflowRevisionVariableListResponse
type: object
properties:
data:
description: The list of resources returned by this request.
type: array
items:
title: PublicApiWorkflowRevisionVariable
type: object
required:
- key
- label
- variableType
properties:
key:
description: Unique key used to identify this row across imports — matches the data set column referenced by the webhook's `keyColumn`.
type: string
label:
description: Display label shown to the end user.
type: string
variableType:
title: VariableType
description: "The kind of merge tag variable this is.\n\n- `Standard` — built-in variable like `{{workflow.name}}` or `{{run.startedDate}}`.\n- `FormField` — resolves to a form field value on the workflow run.\n- `DataSet` — resolves to a column from a linked data set row.\n- `EmailTrigger` — populated from an inbound email that triggered the workflow run.\n- `DocumentReview` — available on workflows using the Document Approvals feature\n (see https://www.process.st/help/docs/document-approvals/).\n"
type: string
enum:
- Standard
- FormField
- DataSet
- EmailTrigger
- DocumentReview
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
UpdateWorkflowRevisionRequest:
title: UpdateWorkflowRevisionRequest
type: object
required:
- changeType
properties:
changeType:
title: ChangeType
description: Whether the changes in this revision are significant. `Material` — substantial changes; bumps the major version (e.g. `1.3` → `2.0`). `NonMaterial` — minor edits like wording or typo fixes; bumps the minor version (e.g. `1.3` → `1.4`).
type: string
enum:
- Material
- NonMaterial
changeExplanation:
description: Optional human-readable explanation of what changed in this revision; surfaced in revision history.
type: string
maxLength: 1000
defaultChecklistName:
description: Default name applied to new workflow runs created from this revision when the caller does not provide one. Supports merge tags (e.g. `{{form.customer_name}}`).
type: string
maxLength: 500
PublicApiWorkflowRevisionListResponse:
title: PublicApiWorkflowRevisionListResponse
type: object
properties:
data:
description: The list of resources returned by this request.
type: array
items:
title: PublicApiWorkflowRevision
type: object
required:
- id
- createdDate
- createdBy
- updatedDate
- updatedBy
- workflowId
- version
- status
properties:
id:
description: The ID of the Revision
examples:
- pg1gR1-tJg9JQfax8pRHvw
type: string
createdDate:
description: When the resource was first created. ISO-8601 UTC.
type: string
format: date-time
createdBy:
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:
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:
description: The ID of the Workflow
examples:
- pg1gR1-tJg9JQfax8pRHvw
type: string
version:
description: Revision version number; monotonically increasing per template.
type: string
status:
description: Status of this revision. `Draft` — being edited; not yet published. `Finished` — currently published version (only one Finished revision per workflow/page at a time). `Revised` — was previously the published version but has been replaced by a newer Finished revision.
type: string
enum:
- Draft
- Finished
- Revised
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
ErrorInfo:
title: ErrorInfo
type: object
required:
- error
properties:
error:
description: 'Human-readable error message. Suitable for logs or for surfacing to end users; do not parse it
programmatically — use `errorCode` for that.'
type: string
details:
description: 'Optional structured context. Shape depends on the error: for `Validation` errors the keys are field
paths; for `PaymentRequired` the keys describe the limit that was hit.'
type: object
additionalProperties:
type: string
errorCode:
title: ErrorCode
description: 'Machine-parsable classification of the error. Always set on responses generated by the global
exception handler. Branch your own error handling on this (not the message text).'
type: string
enum:
- BadRequest
- Unauthorized
- PaymentRequired
- Forbidden
- NotFound
- MethodNotAllowed
- Conflict
- PayloadTooLarge
- Validation
- RateLimited
- InternalError
requestId:
description: Per-request correlation ID. Include this when contacting support so we can find the request in our logs.
type: string
PublicApiWorkflowRevisionResponse:
title: PublicApiWorkflowRevisionResponse
type: object
required:
- data
properties:
data:
title: PublicApiWorkflowRevision
type: object
required:
- id
- createdDate
- createdBy
- updatedDate
- updatedBy
- workflowId
- version
- status
properties:
id:
description: The ID of the Revision
examples:
- pg1gR1-tJg9JQfax8pRHvw
type: string
createdDate:
description: When the resource was first created. ISO-8601 UTC.
type: string
format: date-time
createdBy:
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:
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:
description: The ID of the Workflow
examples:
- pg1gR1-tJg9JQfax8pRHvw
type: string
version:
description: Revision version number; monotonically increasing per template.
type: string
status:
description: Status of this revision. `Draft` — being edited; not yet published. `Finished` — currently published version (only one Finished revision per workflow/page at a time). `Revised` — was previously the published version but has been replaced by a newer Finished revision.
type: string
enum:
- Draft
- Finished
- Revised
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
securitySchemes:
apiKeyAuth:
type: apiKey
name: X-API-Key
in: header
httpAuth:
type: http
description: Bearer token (beta)
scheme: bearer
x-tagGroups:
- name: Workflows
tags:
- Workflows
- Workflow Revisions
- Form Fields
- Workflow Logic Rules
- Workflow Tasks
- Workflow Task Assignment Rules
- Workflow Widgets
- Workflow Due Date Rules
- Workflow Task Due Date Rules
- Workflow Incoming Webhooks
- Scheduled Workflows
- name: Workflow Runs
tags:
- Workflow Runs
- Tasks
- Form Field Values
- Comments
- Attachments
- name: Pages
tags:
- Pages
- Page Revisions
- Page Widgets
- name: Data Sets
tags:
- Data Sets
- Data Set Incoming Webhooks
- name: Other
tags:
- Folders
- One-Off Tasks
- Users
- Webhooks
- File Uploads
- Utilities
- My Work