Process Street Workflow Task Due Date Rules API

openapi: 3.2.0
info:
  title: Process Street Public Attachments Workflow Task Due Date Rules 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 Task Due Date Rules
  description: 'A task due date rule defines how an individual task''s due date is calculated

    within a workflow run — relative to the run''s start/due date, a form field

    value, or another task. Use these endpoints to set or clear the due date rule

    on a task within a draft workflow revision.'
  externalDocs:
    url: https://www.process.st/help/docs/dynamic-due-dates/
    description: Process Street help article
paths:
  /workflows/{workflowId}/revisions/{revisionId}/tasks/{taskId}/due-date-rule:
    get:
      tags:
      - Workflow Task Due Date Rules
      summary: Get the task due date rule
      description: Returns the due date rule for a task on a workflow revision. The `rule` field is `null` when no rule is set.
      operationId: getTaskDueDateRule
      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/GetTaskDueDateRuleResponseResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    put:
      tags:
      - Workflow Task Due Date Rules
      summary: Set the task due date rule
      description: 'Sets the single due date rule for a task on a draft workflow revision, replacing any existing rule. Send `rule: null` (or omit the field) to clear the existing rule. Due date rules cannot be **set** on headings, AI tasks, or Code tasks — but clearing is always permitted so stale rules left over from prior task edits can be removed. `sourceWidgetId` is required when `sourceType` is `FormFieldValue` and must reference a Date form field widget in the same revision. `sourceTaskId` is required when `sourceType` is `TaskCompletedDate` or `TaskDueDate`; it must reference a task earlier than the target task in the same revision and cannot be the target task itself. Returns the resulting rule.'
      operationId: setTaskDueDateRule
      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/UpdateTaskDueDateRuleRequest'
            examples:
              Offset from workflow run start:
                summary: Task is due 3 days after the workflow run starts.
                value:
                  rule:
                    sourceType: ChecklistStartDate
                    offsetDirection: After
                    dueOffset: P3D
                    businessDaysHandlingMode: AllDays
              Offset from previous task:
                summary: Task is due 1 day after the previous task is completed.
                value:
                  rule:
                    sourceType: PreviousTaskCompletedDate
                    offsetDirection: After
                    dueOffset: P1D
                    businessDaysHandlingMode: ShiftToNextBusinessDay
              Offset from another task:
                summary: Task is due 2 days after the source task is completed. `sourceTaskId` must reference a task that appears before the target task in the same revision.
                value:
                  rule:
                    sourceType: TaskCompletedDate
                    sourceTaskId: hj7ZYe6lUQ6Yq0N8tFVFEg
                    offsetDirection: After
                    dueOffset: P2D
                    businessDaysHandlingMode: AllDays
              Offset from a date form field value:
                summary: Task is due 1 business day before a Date form field value.
                value:
                  rule:
                    sourceType: FormFieldValue
                    sourceWidgetId: m95jXOJKAQpfno2TnYVFQw
                    offsetDirection: Before
                    dueOffset: P1D
                    businessDaysHandlingMode: BusinessDaysOnly
              Clear the rule:
                summary: Removes the existing task due date rule.
                value: {}
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTaskDueDateRuleResponseResponse'
        '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:
    UpdateTaskDueDateRuleRequest:
      title: UpdateTaskDueDateRuleRequest
      type: object
      properties:
        rule:
          title: TaskDueDateRuleBody
          description: The rule to set; omit or send `null` to clear the existing rule.
          type: object
          required:
          - sourceType
          - offsetDirection
          - dueOffset
          - businessDaysHandlingMode
          properties:
            sourceType:
              description: How the task's due date is derived. `ChecklistStartDate` / `ChecklistDueDate` — relative to the workflow run's start or due date. `TaskCompletedDate` / `TaskDueDate` — relative to a specific source task (requires `sourceTaskId`). `PreviousTaskCompletedDate` — relative to the task immediately before this one. `FormFieldValue` — relative to a Date form field value (requires `sourceWidgetId`).
              type: string
              enum:
              - FormFieldValue
              - TaskCompletedDate
              - PreviousTaskCompletedDate
              - TaskDueDate
              - ChecklistStartDate
              - ChecklistDueDate
            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
            sourceTaskId:
              title: EntityID
              type: string
            offsetDirection:
              description: Whether the offset applies before or after the source date.
              type: string
              enum:
              - Before
              - After
            dueOffset:
              description: ISO-8601 duration (e.g. `P7D`, `PT4H30M`).
              type: string
            businessDaysHandlingMode:
              title: BusinessDaysHandlingMode
              description: How non-business days are handled when calculating the due date. `AllDays` counts every day. `BusinessDaysOnly` counts only Monday–Friday. `ShiftToNextBusinessDay` calculates using all days then moves a Saturday/Sunday result to the next Monday.
              type: string
              enum:
              - AllDays
              - BusinessDaysOnly
              - ShiftToNextBusinessDay
    GetTaskDueDateRuleResponseResponse:
      title: GetTaskDueDateRuleResponseResponse
      type: object
      required:
      - data
      properties:
        data:
          title: GetTaskDueDateRuleResponse
          description: The resource returned by this request.
          type: object
          properties:
            rule:
              title: PublicApiTaskDueDateRule
              description: The task's due date rule, or `null` if none is set.
              type: object
              required:
              - sourceType
              - offsetDirection
              - dueOffset
              - businessDaysHandlingMode
              properties:
                sourceType:
                  description: How the task's due date is derived. `ChecklistStartDate` / `ChecklistDueDate` — relative to the workflow run's start or due date. `TaskCompletedDate` / `TaskDueDate` — relative to a specific source task (requires `sourceTaskId`). `PreviousTaskCompletedDate` — relative to the task immediately before this one. `FormFieldValue` — relative to a Date form field value (requires `sourceWidgetId`).
                  type: string
                  enum:
                  - FormFieldValue
                  - TaskCompletedDate
                  - PreviousTaskCompletedDate
                  - TaskDueDate
                  - ChecklistStartDate
                  - ChecklistDueDate
                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
                sourceTaskId:
                  title: EntityID
                  type: string
                offsetDirection:
                  description: Whether the offset applies before or after the source date.
                  type: string
                  enum:
                  - Before
                  - After
                dueOffset:
                  description: ISO-8601 duration (e.g. `P7D`, `PT4H30M`).
                  type: string
                businessDaysHandlingMode:
                  title: BusinessDaysHandlingMode
                  description: How non-business days are handled when calculating the due date. `AllDays` counts every day. `BusinessDaysOnly` counts only Monday–Friday. `ShiftToNextBusinessDay` calculates using all days then moves a Saturday/Sunday result to the next Monday.
                  type: string
                  enum:
                  - AllDays
                  - BusinessDaysOnly
                  - ShiftToNextBusinessDay
        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
  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