Process Street Workflow Task Assignment Rules API

openapi: 3.2.0
info:
  title: Process Street Public Workflow Task Assignment Rules API
  version: '1.1'
  description: The Process Street API is organized around REST.
servers:
- url: https://public-api.process.st/api/v1.1
tags:
- name: Workflow Task Assignment Rules
  description: 'A workflow task assignment rule assigns a task template on a draft workflow

    revision to a specific user (static) or derives assignees from a source such

    as the workflow run initiator, a Members form field, or the source document''s

    owner/author (dynamic). Use these endpoints to replace the full set of

    assignment rules on a task template.'
  externalDocs:
    url: https://www.process.st/help/docs/task-assignments/
    description: Process Street help article
paths:
  /workflows/{workflowId}/revisions/{revisionId}/tasks/{taskId}/assignment-rules:
    get:
      tags:
      - Workflow Task Assignment Rules
      summary: Get task assignment rules
      description: 'Returns the assignment rules for a task on a workflow revision. Each rule has a `type` discriminator: `Static` includes the assignee''s `email`; `Dynamic` includes a `sourceType` (one of `ChecklistInitiator`, `FormField`, `DocumentOwner`, `DocumentAuthor`), and when `sourceType` is `FormField`, also a `sourceWidgetId` pointing to a Members or Email form field widget in the same revision.'
      operationId: getWorkflowRevisionTaskAssignmentRules
      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
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiAssignmentRuleListResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    put:
      tags:
      - Workflow Task Assignment Rules
      summary: Update task assignment rules
      description: 'Replaces the assignment rules for a task on a draft workflow revision. PUT semantics: send the full list of desired rules to replace all existing ones; send an empty array to remove all assignments. Each rule has a `type` discriminator: `Static` requires an `email`; `Dynamic` requires a `sourceType` (one of `ChecklistInitiator`, `FormField`, `DocumentOwner`, `DocumentAuthor`), and when `sourceType` is `FormField`, also a `sourceWidgetId` pointing to a Members or Email form field widget in the same revision. Returns the resulting assignment rules.'
      operationId: updateWorkflowRevisionTaskAssignmentRules
      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:
              type: array
              items:
                $ref: '#/components/schemas/UpdateTaskAssignmentRuleRequest'
        required: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiAssignmentRuleListResponse'
        '400':
          description: 'Invalid value for: body'
          content:
            text/plain:
              schema:
                type: string
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
components:
  schemas:
    PublicApiAssignmentRuleListResponse:
      title: PublicApiAssignmentRuleListResponse
      type: object
      properties:
        data:
          description: The list of resources returned by this request.
          type: array
          items:
            title: PublicApiAssignmentRule
            description: 'An assignment rule. The `type` discriminator field selects the variant: `Static` — assigns a specific named user (requires `email`). `Dynamic` — derives the assignee at runtime from a source like the workflow run initiator or a form field (requires `sourceType`).'
            oneOf:
            - title: DynamicAssignmentRule
              type: object
              required:
              - sourceType
              - type
              properties:
                sourceType:
                  description: How assignees are derived. `ChecklistInitiator` assigns the user who started the workflow run; `FormField` pulls assignees from a Members or Email form field (requires `sourceWidgetId`); `DocumentOwner` and `DocumentAuthor` pull from the source document.
                  type: string
                  enum:
                  - ChecklistInitiator
                  - FormField
                  - DocumentOwner
                  - DocumentAuthor
                sourceWidgetId:
                  title: EntityID
                  description: 'For `sourceType=FormField`: the ID of the Members form field whose value drives the rule''s assignees at runtime. Absent for `sourceType=ChecklistInitiator`.'
                  type: string
                type:
                  description: Discriminator value for this variant. See the parent oneOf for the full set of values.
                  type: string
                  const: Dynamic
            - title: StaticAssignmentRule
              type: object
              required:
              - email
              - type
              properties:
                email:
                  description: Email address.
                  type: string
                type:
                  description: Discriminator value for this variant. See the parent oneOf for the full set of values.
                  type: string
                  const: Static
            discriminator:
              propertyName: type
              mapping:
                Dynamic: '#/components/schemas/DynamicAssignmentRule'
                Static: '#/components/schemas/StaticAssignmentRule'
        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
    UpdateTaskAssignmentRuleRequest:
      title: UpdateTaskAssignmentRuleRequest
      description: 'An assignment rule. The `type` discriminator field selects the variant: `Static` — assigns a specific named user (requires `email`). `Dynamic` — derives the assignee at runtime from a source like the workflow run initiator or a form field (requires `sourceType`).'
      oneOf:
      - title: DynamicAssignmentRuleRequest
        type: object
        required:
        - sourceType
        - type
        properties:
          sourceType:
            description: How assignees are derived. `ChecklistInitiator` assigns the user who started the workflow run; `FormField` pulls assignees from a Members or Email form field (requires `sourceWidgetId`); `DocumentOwner` and `DocumentAuthor` pull from the source document.
            type: string
            enum:
            - ChecklistInitiator
            - FormField
            - DocumentOwner
            - DocumentAuthor
          sourceWidgetId:
            title: EntityID
            description: 'For `sourceType=FormField`: the ID of the Members form field whose value drives the rule''s assignees at runtime. Absent for `sourceType=ChecklistInitiator`.'
            type: string
          type:
            description: Discriminator value for this variant. See the parent oneOf for the full set of values.
            type: string
            const: Dynamic
      - title: StaticAssignmentRuleRequest
        type: object
        required:
        - email
        - type
        properties:
          email:
            description: Email address.
            type: string
          type:
            description: Discriminator value for this variant. See the parent oneOf for the full set of values.
            type: string
            const: Static
      discriminator:
        propertyName: type
        mapping:
          Dynamic: '#/components/schemas/DynamicAssignmentRuleRequest'
          Static: '#/components/schemas/StaticAssignmentRuleRequest'
    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
  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