Process Street Workflow Widgets API

openapi: 3.1.0
info:
  title: Process Street Public Attachments Workflow Widgets 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 Widgets
  description: 'A workflow widget is a form field or content element on a task within a workflow revision.

    Use these endpoints to create and manage widgets on draft revisions.'
  externalDocs:
    url: https://www.process.st/help/docs/form-fields/
    description: Process Street help article
paths:
  /workflows/{workflowId}/revisions/{revisionId}/tasks/{taskId}/widgets:
    get:
      tags:
      - Workflow Widgets
      summary: List widgets
      description: Returns widgets for a task on a workflow revision, ordered by position.
      operationId: listWorkflowRevisionTaskWidgets
      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: taskId
        in: path
        description: The ID of the Task
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Filter by widget type.
        required: false
        schema:
          $ref: '#/components/schemas/Type'
          description: 'Widget kind discriminator.


            - `FormField` — collects user input (Text, Number, Date, etc.).

            - `Text` — rich text content displayed on the task.

            - `Image` — image content displayed on the task.

            - `File` — downloadable file attached to the task.

            - `Video` — video content (uploaded or linked from a hosting service).

            - `Embed` — embedded external content via URL.

            - `CrossLink` — link to another workflow or page.

            '
      - 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/PublicApiWidgetListResponse'
        '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: []
    post:
      tags:
      - Workflow Widgets
      summary: Create a widget
      description: 'Creates a widget on a task within a draft workflow revision.

        Text content can include merge tag variables (e.g. `{{workflow.name}}`).

        Use the listWorkflowRevisionVariables endpoint to discover available variables.'
      operationId: createWorkflowRevisionTaskWidget
      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: taskId
        in: path
        description: The ID of the Task
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowWidgetRequest'
            examples:
              Text form field:
                summary: Create a Text form field widget
                value:
                  label: Customer Name
                  config:
                    placeholder: Enter name...
                  constraints:
                    min: 1
                    max: 100
                  fieldType: Text
                  type: FormField
              Textarea form field:
                summary: Create a Textarea form field widget
                value:
                  label: Description
                  fieldType: Textarea
                  type: FormField
              Email form field:
                summary: Create a Email form field widget
                value:
                  label: Contact Email
                  fieldType: Email
                  type: FormField
              Number form field:
                summary: Create a Number form field widget
                value:
                  label: Quantity
                  fieldType: Number
                  type: FormField
              URL form field:
                summary: Create a URL form field widget
                value:
                  label: Website
                  fieldType: Url
                  type: FormField
              Hidden form field:
                summary: Create a Hidden form field widget
                value:
                  hiddenByDefault: true
                  label: Internal ID
                  fieldType: Hidden
                  type: FormField
              MultiFile form field:
                summary: Create a MultiFile form field widget
                value:
                  label: Attachments
                  fieldType: MultiFile
                  type: FormField
              Select form field:
                summary: Create a Select form field widget
                value:
                  label: Status
                  fieldType: Select
                  type: FormField
              MultiChoice form field:
                summary: Create a MultiChoice form field widget
                value:
                  label: Options
                  fieldType: MultiChoice
                  type: FormField
              MultiSelect form field:
                summary: Create a MultiSelect form field widget
                value:
                  label: Subtasks
                  fieldType: MultiSelect
                  type: FormField
              Date form field:
                summary: Create a Date form field widget
                value:
                  label: Due Date
                  fieldType: Date
                  type: FormField
              Members form field:
                summary: Create a Members form field widget
                value:
                  label: Assignee
                  fieldType: Members
                  type: FormField
              Document form field:
                summary: Create a Document form field widget
                value:
                  label: Contract
                  fieldType: Document
                  type: FormField
              Table form field:
                summary: Create a Table form field widget
                value:
                  label: Inventory
                  fieldType: Table
                  type: FormField
              Snippet form field:
                summary: Create a Snippet form field widget
                value:
                  label: Reusable Snippet
                  fieldType: Snippet
                  type: FormField
              SendRichEmail form field:
                summary: Create a SendRichEmail form field widget
                value:
                  label: Notification Email
                  fieldType: SendRichEmail
                  type: FormField
              Text content widget:
                summary: Create a text content widget
                value:
                  hiddenByDefault: false
                  content: '## Heading


                    Some text content.'
                  type: Text
              Image widget:
                summary: Create an image widget. The file is uploaded via a separate endpoint.
                value:
                  hiddenByDefault: false
                  caption: Architecture diagram
                  type: Image
              File widget:
                summary: Create a file widget. The file is uploaded via a separate endpoint.
                value:
                  hiddenByDefault: false
                  description: Project report
                  type: File
              Video content widget:
                summary: Create a video content widget with a YouTube embed
                value:
                  hiddenByDefault: false
                  description: Product demo
                  url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
                  type: Video
              Video content widget (empty, for upload):
                summary: Create an empty video content widget. Upload the video file via the widget upload endpoint.
                value:
                  hiddenByDefault: false
                  description: Training recording
                  type: Video
              Embed widget:
                summary: Create an embed widget that renders a URL in an iframe
                value:
                  hiddenByDefault: false
                  url: https://www.google.com/maps/embed?pb=example
                  type: Embed
              CrossLink widget:
                summary: Create a cross-link widget that links to another workflow or page
                value:
                  hiddenByDefault: false
                  type: CrossLink
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiWidgetResponse'
        '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}/revisions/{revisionId}/tasks/{taskId}/widgets/{widgetId}:
    get:
      tags:
      - Workflow Widgets
      summary: Get a widget
      description: Returns a widget by its ID within a workflow revision task.
      operationId: getWorkflowRevisionTaskWidget
      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: taskId
        in: path
        description: The ID of the Task
        required: true
        schema:
          type: string
      - name: widgetId
        in: path
        description: The ID of the Widget
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiWidgetResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    put:
      tags:
      - Workflow Widgets
      summary: Update a widget
      description: 'Updates a widget on a task within a draft workflow revision. PUT semantics: all mutable fields must be provided.

        Each field type has different config and constraints — refer to the request examples for the specific shape per type.

        Text content can include merge tag variables (e.g. `{{workflow.name}}`).

        Use the listWorkflowRevisionVariables endpoint to discover available variables.

        Returns the updated widget.'
      operationId: updateWorkflowRevisionTaskWidget
      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: taskId
        in: path
        description: The ID of the Task
        required: true
        schema:
          type: string
      - name: widgetId
        in: path
        description: The ID of the Widget
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWidgetRequest'
            examples:
              Text form field:
                summary: Update a text form field widget
                value:
                  hiddenByDefault: false
                  position:
                    type: After
                    widgetId: hwV40w88jSbyWPo87IFO5Q
                  label: Customer Name
                  required: true
                  config:
                    placeholder: Enter name...
                    defaultValue: John
                  constraints:
                    min: 1
                    max: 100
                  fieldType: Text
                  type: FormField
              Textarea form field:
                summary: Update a textarea form field widget
                value:
                  hiddenByDefault: false
                  label: Description
                  required: false
                  config:
                    placeholder: Enter description...
                    defaultValue: ''
                    format: RichText
                  constraints:
                    min: 1
                    max: 500
                  fieldType: Textarea
                  type: FormField
              Email form field:
                summary: Update an email form field widget
                value:
                  hiddenByDefault: false
                  label: Contact Email
                  required: true
                  config:
                    placeholder: Enter email...
                    defaultValue: ''
                  constraints:
                    domains:
                    - company.com
                    restriction: Allow
                  fieldType: Email
                  type: FormField
              Number form field:
                summary: Update a number form field widget
                value:
                  hiddenByDefault: false
                  label: Quantity
                  required: true
                  config:
                    placeholder: Enter number...
                    defaultValue: '0'
                    unit: kg
                    unitLocation: suffix
                  constraints:
                    minDigits: 1
                    maxDigits: 5
                    minValue: 0
                    maxValue: 1000
                    decimalPlaces: 2
                    allowNegative: false
                  fieldType: Number
                  type: FormField
              URL form field:
                summary: Update a URL form field widget
                value:
                  hiddenByDefault: false
                  label: Website
                  required: false
                  config:
                    defaultValue: https://example.com
                  fieldType: Url
                  type: FormField
              Hidden form field:
                summary: Update a hidden form field widget
                value:
                  hiddenByDefault: true
                  label: Internal ID
                  required: false
                  config:
                    defaultValue: default-value
                  fieldType: Hidden
                  type: FormField
              File form field:
                summary: Update a (legacy) file form field widget
                value:
                  hiddenByDefault: false
                  label: Attachment
                  required: true
                  config:
                    placeholder: Upload a file...
                    extractTextContent: false
                  constraints:
                    extensions:
                    - .pdf
                    - .docx
                  fieldType: File
                  type: FormField
              MultiFile form field:
                summary: Update a multi-file form field widget
                value:
                  hiddenByDefault: false
                  label: Attachments
                  required: true
                  config:
                    placeholder: Upload files...
                    extractTextContent: true
                  constraints:
                    extensions:
                    - .pdf
                    - .docx
                    mode: Multiple
                  fieldType: MultiFile
                  type: FormField
              Select form field:
                summary: Update a select (dropdown) form field widget
                value:
                  hiddenByDefault: false
                  label: Status
                  required: false
                  config:
                    items:
                    - id: v-eC-5Ohmm9_dQaQUeFCZg
                      name: Option 1
                    - id: pwJ2C6v-29NrgRQpglNGlw
                      name: Option 2
                    - id: okpc9e5dbx0YsjjP7YJPiQ
                      name: Option 3
                  fieldType: Select
                  type: FormField
              MultiChoice form field:
                summary: Update a multi-choice form field widget
                value:
                  hiddenByDefault: false
                  label: Options
                  required: false
                  config:
                    items:
                    - id: keH24HImyrQfOzXHpTpPDA
                      name: Choice A
                    - id: qgdUszvgKWt7W54op0ROvg
                      name: Choice B
                    - id: uNw5KAn2W1LEL6cABttK_A
                      name: Choice C
                  fieldType: MultiChoice
                  type: FormField
              MultiSelect form field:
                summary: Update a multi-select (subtasks) form field widget
                value:
                  hiddenByDefault: false
                  label: Subtasks
                  required: false
                  config:
                    items:
                    - id: iXAW3R3lcIfWxy1H2SxLfw
                      name: Task 1
                    - id: p4l1MsmbCXieR-HS3dFE6w
                      name: Task 2
                    - id: suzbbt2yOeQjJh095KtJlw
                      name: Task 3
                  fieldType: MultiSelect
                  type: FormField
              Date form field:
                summary: Update a date form field widget
                value:
                  hiddenByDefault: false
                  label: Due Date
                  required: false
                  config:
                    timeOption: Included
                  constraints: {}
                  fieldType: Date
                  type: FormField
              Members form field:
                summary: Update a members form field widget
                value:
                  hiddenByDefault: false
                  label: Assignee
                  required: false
                  config: {}
                  fieldType: Members
                  type: FormField
              Document form field:
                summary: Update a document form field widget
                value:
                  hiddenByDefault: false
                  label: Contract
                  required: false
                  config:
                    reviewRequest: true
                    defaultValue: '{{document_review.document.id}}'
                  fieldType: Document
                  type: FormField
              Table form field:
                summary: Update a table form field widget
                value:
                  hiddenByDefault: false
                  label: Inventory
                  required: false
                  config:
                    columnDefs:
                    - id: v7Yll4vKbL5Cd_6Whn1NUw
                      name: Name
                      columnType: Text
                    - id: q-cg4TjGqIc9mO-q7K5CTg
                      name: Quantity
                      columnType: Number
                  fieldType: Table
                  type: FormField
              Snippet form field:
                summary: Update a snippet form field widget
                value:
                  hiddenByDefault: false
                  label: Reusable Snippet
                  required: false
                  config:
                    value: This is reusable text content.
                  fieldType: Snippet
                  type: FormField
              SendRichEmail form field:
                summary: Update a send rich email form field widget
                value:
                  hiddenByDefault: false
                  label: Notification Email
                  required: false
                  config:
                    to:
                    - recipient@example.com
                    subject: Task completed
                    body: <p>The task has been completed.</p>
                    bodyEditor: RichText
                    editAllowed: true
                  fieldType: SendRichEmail
                  type: FormField
              Text content widget:
                summary: Update a text content widget
                value:
                  hiddenByDefault: false
                  content: '## Heading


                    Some text content.'
                  type: Text
              Image widget:
                summary: Update an image widget's caption and position
                value:
                  hiddenByDefault: false
                  caption: Architecture diagram
                  type: Image
              File widget:
                summary: Update a file widget's description and position
                value:
                  hiddenByDefault: false
                  description: Project report
                  type: File
              Video content widget:
                summary: Update a video content widget
                value:
                  hiddenByDefault: false
                  description: Product demo
                  url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
                  type: Video
              Embed widget:
                summary: Update an embed widget's URL
                value:
                  hiddenByDefault: false
                  url: https://www.google.com/maps/embed?pb=example
                  type: Embed
              CrossLink widget:
                summary: Update a cross-link widget
                value:
                  hiddenByDefault: false
                  type: CrossLink
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiWidgetResponse'
        '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 Widgets
      summary: Delete a widget
      description: Deletes a widget from a task within a draft workflow revision.
      operationId: deleteWorkflowRevisionTaskWidget
      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: taskId
        in: path
        description: The ID of the Task
        required: true
        schema:
          type: string
      - name: widgetId
        in: path
        description: The ID of the Widget
        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}/tasks/{taskId}/widgets/{widgetId}/upload:
    post:
      tags:
      - Workflow Widgets
      summary: Upload a file to a widget
      description: 'Uploads a file to an Image or File widget on a task within a draft workflow revision. Replaces the existing file, if any.


        Accepts multipart form data (field `file`) or JSON with base64-encoded content (field `fileBase64`).

        Maximum file size: 20 MB for multipart, 10 MB for base64.

        You can also send JSON `{ "fileUploadId": "..." }` to attach a file you uploaded with

        `createFileUpload`; the `fileUploadId` is single-use.

        For Image widgets, only image/* content types are accepted.'
      operationId: uploadWorkflowRevisionTaskWidgetFile
      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: taskId
        in: path
        description: The ID of the Task
        required: true
        schema:
          type: string
      - name: widgetId
        in: path
        description: The ID of the Widget
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadWidgetFileRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/UploadWidgetFileRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiWidgetResponse'
        '400':
          description: Invalid value
          content:
            text/plain:
              schema:
                type: string
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
components:
  schemas:
    Type:
      title: Type
      type: string
      enum:
      - CrossLink
      - Email
      - Embed
      - File
      - FormField
      - Image
      - Text
      - Video
    UploadWidgetFileRequest:
      title: UploadWidgetFileRequest
      type: object
      properties:
        file:
          description: Uploaded file reference. Use the upload endpoint to attach content.
          type: string
          format: binary
        fileBase64:
          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
    PublicApiWidgetResponse:
      title: PublicApiWidgetResponse
      type: object
      required:
      - data
      properties:
        data:
          title: PublicApiWidget
          oneOf:
          - title: PublicApiCrossLinkWidget
            type: object
            required:
            - hiddenByDefault
            - id
            - taskId
            - createdDate
            - createdBy
            - updatedDate
            - updatedBy
            - type
            properties:


# --- truncated at 32 KB (485 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/process-street/refs/heads/main/openapi/process-street-workflow-widgets-api-openapi.yml