openapi: 3.1.0
info:
title: Process Street Public Attachments Form Field Values 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: Form Field Values
description: 'A form field value is the data entered into a form field within a workflow
run. Use these endpoints to read and update form field values for a specific
workflow run.'
externalDocs:
url: https://www.process.st/help/docs/form-fields/
description: Process Street help article
paths:
/workflow-runs/{workflowRunId}/tasks/{taskId}/form-fields:
get:
tags:
- Form Field Values
summary: List all form field values in a task
description: 'Gets a page of form field values for a task of a workflow run.
Form field values are paged, meaning the links section in the
response must be used to get the next/previous batch of form field values.'
operationId: listFormFieldValuesByTask
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
- name: taskId
in: path
description: The ID of the Task
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/ListFormFieldValuesResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflow-runs/{workflowRunId}/form-fields:
get:
tags:
- Form Field Values
summary: List all form field values
description: 'Gets a page of form field values for a workflow run.
Form field values are paged, meaning the links section in the
response must be used to get the next/previous batch of form field values.'
operationId: listFormFieldValues
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/ListFormFieldValuesResponse'
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
post:
tags:
- Form Field Values
summary: Batch update form field values
description: 'Updates multiple form field values (i.e the values for the form fields present in a workflow run).
A value may consist of a simple string, may accept multiple values as an array, or it may accept multiple
properties.<br>
<br>
See the examples for a complete reference on setting form field values.<br>
<br>
Note: File Upload form fields cannot be updated using this endpoint. Use the upload endpoint instead.'
operationId: batchUpdateFormFieldValues
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
requestBody:
description: 'List of form fields to set a new value for within a workflow run.
Form field IDs included in the request will have their values created or updated.
Form field IDs not included in the request will be left unchanged.'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMultipleFormFieldValuesRequest'
examples:
updatingSimpleFields:
summary: 'Updating a simple field: Short Text, Long Text, Email, Website, Members (User) and Dropdown fields'
description: "Requires specifying only a 'value' key with a String associated.\n This structure must be used for the following fields: Short Text, Long Text, Email, Website, Members (User) and Dropdown."
value:
fields:
- id: lNOlDxX_bxK1A9JudBJFdQ
value: It's over Anakin, I have the high ground
updatingMultiValueFields:
summary: 'Updating a field that accepts multiple values: Members, Multi Select (Subtasks) and Multi Choice fields'
description: "Requires specifying only a 'values' key with a list of Strings associated.\n This structure must be used for the following fields: Multi Select and Multi Choice."
value:
fields:
- id: iGue0sTNaJ46FuE1aXNCOw
values:
- It's over Anakin
- I have the high ground
dataSetConnectedDropdown:
summary: Updating a Data Set Linked Dropdown field
description: Requires specifying a 'value' or a 'dataSetRowId' key with a Muid associated.
value:
fields:
- id: kvgfJO0K9G9TKPr9l1tLZw
value: saBkTR8rkXUjkgV5GX1M7A
updatingDateFields:
summary: Updating the Date field
description: "Requires specifying only a 'value' key, but may optionally add a 'timeHidden' key.\n This structure must be used for the Date field."
value:
fields:
- id: m7PvAKYLSRmyCXcBwuNIlw
value: '2026-07-20T14:53:23.057Z'
timeHidden: true
updatingTableFields:
summary: Updating the Table field
description: Requires specifying only a 'value' key with a CSV associated.
value:
fields:
- id: tpeuaFbAGzGrQrgEmu5FYQ
value: 'Alice,Bob
Jon,Natalie'
updatingMultipleFields:
summary: Updating multiple fields at the same time
description: Updating multiple fields at the same time
value:
fields:
- id: gUYeGTkY2dZbRgk1N_RPpA
value: '2026-07-20T14:53:23.055Z'
timeHidden: true
- id: tyOVIl1EYShtAh9ylPtK7Q
values:
- It's over Anakin
- I have the high ground
- id: tkWa_nFK1j4LgIa0w8pAYw
value: https://www.process.st
- id: jpaaqhkoAyeeOFUSFVJDtA
value: 'Alice,Bob
Jon,Natalie'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMultipleFormFieldValuesResponse'
'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}/form-fields/{formFieldId}/upload:
post:
tags:
- Form Field Values
summary: Upload a form field value
description: 'Uploads one or more files to a File or MultiFile form field in a workflow run.
Note:<br>
This endpoint supports both single-file and multi-file form fields.<br>
File fields can accept exactly one file and it will replace the current file.<br>
MultiFile fields can accept multiple files per request, up to 10 files total, subject to the field''s configuration.
These files will be appended to the field.<br>
The maximum file size supported by this endpoint is 20 MB per file for multipart uploads and 10 MB per file for Base64 uploads.
Alternatively, send JSON `{ "fileUploadId": "..." }` to attach a file you uploaded with the `createFileUpload` endpoint. The `fileUploadId` is single-use.'
operationId: uploadFormFieldValue
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
- name: formFieldId
in: path
description: Form Field ID
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/UploadFormFieldValueRequest'
application/json:
schema:
$ref: '#/components/schemas/UploadFormFieldValueRequest'
required: true
responses:
'204':
description: ''
'400':
description: Invalid value
content:
text/plain:
schema:
type: string
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
delete:
tags:
- Form Field Values
summary: Delete all files from a form field
description: Deletes all files from a File or MultiFile form field in a workflow run.
operationId: deleteFormFieldAllFiles
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
- name: formFieldId
in: path
description: Form Field ID
required: true
schema:
type: string
responses:
'204':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
/workflow-runs/{workflowRunId}/form-fields/{formFieldId}/upload/{fileId}:
delete:
tags:
- Form Field Values
summary: Delete a specific file from a form field
description: 'Deletes a specific file from a File or MultiFile form field in a workflow run.
For File fields, the `fileId` parameter is ignored since there is only one file.
For MultiFile fields, the specified file is removed. If it was the last file, the field value is deleted entirely.'
operationId: deleteFormFieldFileById
parameters:
- name: workflowRunId
in: path
description: The ID of the Workflow Run
required: true
schema:
type: string
- name: formFieldId
in: path
description: Form Field ID
required: true
schema:
type: string
- name: fileId
in: path
description: File ID
required: true
schema:
type: string
responses:
'204':
description: ''
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
security:
- apiKeyAuth: []
- httpAuth: []
components:
schemas:
UpdateMultipleFormFieldValuesResponse:
title: UpdateMultipleFormFieldValuesResponse
type: object
properties:
fields:
description: Form field definitions or column definitions, depending on context.
type: array
items:
title: SimplifiedFormFieldValue
type: object
required:
- id
- workflowRunId
- taskId
- key
- data
- fieldType
properties:
id:
title: EntityID
description: The resource's ID.
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
workflowRunId:
title: EntityID
description: The ID of the Workflow Run.
type: string
taskId:
title: EntityID
description: The ID of the Task.
type: string
key:
description: Unique key based on the label. This is used when referencing the form field as a [variable](https://www.process.st/help/docs/variables/)
type: string
label:
description: User defined label
type: string
data:
description: The form field's value, encoded as JSON. Shape depends on `fieldType` — e.g. a string for `Text`, a number for `Number`, an array of selected option keys for `MultiChoice`.
fieldType:
description: "Form-field subtype discriminator (only relevant when widget `type` is `FormField`).\n\n- `Text` — short text input (≤255 characters).\n- `Textarea` — long-form text.\n- `Email` — email address.\n- `Url` — website / URL.\n- `Number` — numeric input with optional unit and constraints.\n- `Date` — date or date+time picker.\n- `Select` — dropdown; user picks one option.\n- `MultiChoice` — checkboxes; user picks one or more options.\n- `MultiSelect` — Subtasks: a checklist of sub-items inside the task.\n- `Members` — assignee picker (selects organization users).\n- `File` — single file upload.\n- `MultiFile` — multi-file upload (in-app \"File Upload\").\n- `Document` — document approval field; links the task to a document review.\n- `Table` — rows × columns of cells; users fill cell values.\n- `SendRichEmail` — pre-written email embedded in the task; sent manually by the user or\n automatically when the task is completed.\n- `Hidden` — only visible when editing the workflow; populated by integrations or default values.\n- `Snippet` — only visible when editing; passes static text or merge tags into automations.\n"
type: string
enum:
- Date
- Document
- Email
- File
- Hidden
- Members
- MultiChoice
- MultiFile
- MultiSelect
- Number
- Select
- SendRichEmail
- Snippet
- Table
- Text
- Textarea
- Url
dataSetLinked:
description: When `true`, this field is bound to a data set row; its value is synchronised from the linked record.
type: boolean
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
UploadFormFieldValueRequest:
title: UploadFormFieldValueRequest
type: object
properties:
file:
description: Uploaded file reference. Use the upload endpoint to attach content.
type: array
items:
type: string
format: binary
fileBase64:
type: array
items:
title: FileBase64
type: object
required:
- content
- filename
properties:
content:
description: Rich text content. May contain merge tags.
type: string
filename:
type: string
fileUploadId:
type: string
UpdateMultipleFormFieldValuesRequest:
title: UpdateMultipleFormFieldValuesRequest
type: object
properties:
fields:
description: Form field definitions or column definitions, depending on context.
type: array
items:
type: object
required:
- id
properties:
id:
title: EntityID
description: The resource's ID.
type: string
value:
description: The form field value (e.g. text, date as ISO string, URL or user email for Users field)
type: string
values:
description: List of form field values
type: array
items:
type: string
timeHidden:
description: Whether to hide the time portion and display the date only for Date form fields.
type: boolean
dataSetRowId:
title: EntityID
type: string
ListFormFieldValuesResponse:
title: ListFormFieldValuesResponse
type: object
properties:
fields:
description: Form field definitions or column definitions, depending on context.
type: array
items:
title: SimplifiedFormFieldValue
type: object
required:
- id
- workflowRunId
- taskId
- key
- data
- fieldType
properties:
id:
title: EntityID
description: The resource's ID.
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
workflowRunId:
title: EntityID
description: The ID of the Workflow Run.
type: string
taskId:
title: EntityID
description: The ID of the Task.
type: string
key:
description: Unique key based on the label. This is used when referencing the form field as a [variable](https://www.process.st/help/docs/variables/)
type: string
label:
description: User defined label
type: string
data:
description: The form field's value, encoded as JSON. Shape depends on `fieldType` — e.g. a string for `Text`, a number for `Number`, an array of selected option keys for `MultiChoice`.
fieldType:
description: "Form-field subtype discriminator (only relevant when widget `type` is `FormField`).\n\n- `Text` — short text input (≤255 characters).\n- `Textarea` — long-form text.\n- `Email` — email address.\n- `Url` — website / URL.\n- `Number` — numeric input with optional unit and constraints.\n- `Date` — date or date+time picker.\n- `Select` — dropdown; user picks one option.\n- `MultiChoice` — checkboxes; user picks one or more options.\n- `MultiSelect` — Subtasks: a checklist of sub-items inside the task.\n- `Members` — assignee picker (selects organization users).\n- `File` — single file upload.\n- `MultiFile` — multi-file upload (in-app \"File Upload\").\n- `Document` — document approval field; links the task to a document review.\n- `Table` — rows × columns of cells; users fill cell values.\n- `SendRichEmail` — pre-written email embedded in the task; sent manually by the user or\n automatically when the task is completed.\n- `Hidden` — only visible when editing the workflow; populated by integrations or default values.\n- `Snippet` — only visible when editing; passes static text or merge tags into automations.\n"
type: string
enum:
- Date
- Document
- Email
- File
- Hidden
- Members
- MultiChoice
- MultiFile
- MultiSelect
- Number
- Select
- SendRichEmail
- Snippet
- Table
- Text
- Textarea
- Url
dataSetLinked:
description: When `true`, this field is bound to a data set row; its value is synchronised from the linked record.
type: boolean
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
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:
- A
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/process-street/refs/heads/main/openapi/process-street-form-field-values-api-openapi.yml