Process Street My Work API

openapi: 3.2.0
info:
  title: Process Street Public My Work 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: My Work
  description: 'My Work is your personal task inbox — a consolidated view of all tasks and checklist items

    assigned to you across all workflows. Use these endpoints to list, search, and manage

    your assigned work items.'
  externalDocs:
    url: https://www.process.st/help/docs/my-work/
    description: Process Street help article
paths:
  /work/items:
    get:
      tags:
      - My Work
      summary: List My Work items
      description: 'Returns a paginated list of work items assigned to the authenticated user.

        Use `assigneeEmail` to filter by a specific user, or omit to default to the authenticated user.'
      operationId: listMyWorkItems
      parameters:
      - name: assigneeEmail
        in: query
        description: Filter by assignee email. Defaults to the authenticated user.
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: 'Filter by item type.


          - `Checklist` — a workflow run assigned to the user.

          - `StandardTask` — a regular task within a workflow run.

          - `ApprovalTask` — an approval task awaiting the user''s review.

          - `OneOffTask` — a standalone one-off task.

          - `Acknowledgment` — a revision-acknowledgment request after a workflow update.

          '
        required: false
        schema:
          $ref: '#/components/schemas/InboxItemType'
      - name: workflowId
        in: query
        description: Filter to a specific workflow. If the workflow does not exist or is inaccessible, the response is an empty page rather than an error.
        required: false
        schema:
          type: string
      - name: dueDateFrom
        in: query
        description: Due date range start (ISO-8601, e.g. 2024-01-15).
        required: false
        schema:
          type: string
      - name: dueDateTo
        in: query
        description: Due date range end (ISO-8601, e.g. 2024-01-31).
        required: false
        schema:
          type: string
      - name: snoozeStatus
        in: query
        description: 'Filter by snooze status.


          - `Active` — non-snoozed items only.

          - `Snoozed` — items currently snoozed.


          Omit this filter to include both.

          '
        required: false
        schema:
          $ref: '#/components/schemas/SnoozeStatus'
      - name: includeCompleted
        in: query
        description: Include completed items. Defaults to false.
        required: false
        schema:
          type: boolean
      - 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/PublicApiMyWorkItemListResponse'
        '400':
          description: 'Invalid value for: query parameter type, Invalid value for: query parameter snoozeStatus, Invalid value for: query parameter includeCompleted'
          content:
            text/plain:
              schema:
                type: string
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
  /work/items/search:
    post:
      tags:
      - My Work
      summary: Search My Work items
      description: 'Searches work items with complex filtering.

        Supports multi-value filters for assignees, types, and workflows, plus free-text search and sorting.'
      operationId: searchMyWorkItems
      parameters:
      - 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchMyWorkItemsRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiMyWorkItemListResponse'
        '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: []
  /work/items/{itemId}/snooze:
    post:
      tags:
      - My Work
      summary: Snooze a My Work item
      description: Snoozes the My Work item until the specified date. If already snoozed, updates the snooze date.
      operationId: snoozeMyWorkItem
      parameters:
      - name: itemId
        in: path
        description: The ID of the My Work item to snooze.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnoozeMyWorkItemRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiSnoozedAssignmentResponse'
        '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:
      - My Work
      summary: Unsnooze a My Work item
      description: Removes the snooze from the My Work item.
      operationId: unsnoozeMyWorkItem
      parameters:
      - name: itemId
        in: path
        description: The ID of the My Work item to unsnooze.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
  /work/stats:
    get:
      tags:
      - My Work
      summary: Get My Work stats
      description: 'Returns total, upcoming, and overdue counts of work items assigned to the authenticated user.

        Use `assigneeEmail` to filter by a specific user, or omit to default to the authenticated user.'
      operationId: getMyWorkStats
      parameters:
      - name: assigneeEmail
        in: query
        description: Filter by assignee email. Defaults to the authenticated user.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiMyWorkStatsResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
components:
  schemas:
    PublicApiMyWorkStatsResponse:
      title: PublicApiMyWorkStatsResponse
      type: object
      required:
      - data
      properties:
        data:
          title: PublicApiMyWorkStats
          description: The resource returned by this request.
          type: object
          required:
          - total
          - upcoming
          - overdue
          properties:
            total:
              description: Total number of active (non-completed) items assigned to the user.
              type: integer
              format: int64
            upcoming:
              description: Number of items with a due date in the future.
              type: integer
              format: int64
            overdue:
              description: Number of items with a due date in the past.
              type: integer
              format: int64
        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
    PublicApiMyWorkItemListResponse:
      title: PublicApiMyWorkItemListResponse
      type: object
      properties:
        data:
          description: The list of resources returned by this request.
          type: array
          items:
            title: PublicApiMyWorkItem
            type: object
            required:
            - id
            - type
            - name
            - workflowId
            properties:
              id:
                description: The ID of the My Work item assignment.
                examples:
                - u1E54jvskr9llzkgxXJFrg
                type: string
              type:
                title: InboxItemType
                description: 'Kind of My Work item.


                  - `Checklist` — a workflow run assigned to the user.

                  - `StandardTask` — a regular task within a workflow run.

                  - `ApprovalTask` — an approval task awaiting the user''s review.

                  - `OneOffTask` — a standalone one-off task.

                  - `Acknowledgment` — a revision-acknowledgment request after a workflow update.

                  '
                type: string
                enum:
                - Checklist
                - StandardTask
                - ApprovalTask
                - OneOffTask
                - Acknowledgment
              name:
                description: Display name of the assigned item (task name, run name, or one-off task name).
                type: string
              workflowId:
                description: The ID of the Workflow
                examples:
                - u1E54jvskr9llzkgxXJFrg
                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
              dueDate:
                description: Optional due date of the underlying item. ISO-8601 UTC.
                type: string
                format: date-time
              snoozedUntil:
                description: If the item is currently snoozed, the date it un-snoozes. Absent if not snoozed.
                type: string
                format: date-time
              assignees:
                description: Users assigned to this item.
                type: array
                items:
                  title: PublicApiUser
                  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
              links:
                description: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 link relation like `self`, `edit`, `related`), an `href` URL, and a `type` (`Api` for callable endpoints, `App` for browser-facing URLs). Prefer following these `href` values over constructing URLs by hand.
                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: '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
    SearchMyWorkItemsRequest:
      title: SearchMyWorkItemsRequest
      type: object
      properties:
        assigneeEmails:
          description: Filter results to items assigned to one or more user emails. Unknown emails are silently ignored (the search returns whatever the known assignees have). Defaults to the authenticated user if empty.
          type: array
          items:
            type: string
        types:
          type: array
          items:
            title: InboxItemType
            description: 'Kind of My Work item.


              - `Checklist` — a workflow run assigned to the user.

              - `StandardTask` — a regular task within a workflow run.

              - `ApprovalTask` — an approval task awaiting the user''s review.

              - `OneOffTask` — a standalone one-off task.

              - `Acknowledgment` — a revision-acknowledgment request after a workflow update.

              '
            type: string
            enum:
            - Checklist
            - StandardTask
            - ApprovalTask
            - OneOffTask
            - Acknowledgment
        workflowIds:
          description: Filter to specific workflows. Unknown/inaccessible workflow IDs are silently ignored.
          type: array
          items:
            title: EntityID
            type: string
        dueDateFrom:
          description: Due date range start (ISO-8601, e.g. 2024-01-15).
          type: string
          format: date-time
        dueDateTo:
          description: Due date range end (ISO-8601, e.g. 2024-01-31).
          type: string
          format: date-time
        snoozeStatus:
          title: SnoozeStatus
          description: 'Snooze filter for the search.


            - `Active` — non-snoozed items only.

            - `Snoozed` — items currently snoozed.

            '
          type: string
          enum:
          - Active
          - Snoozed
        includeCompleted:
          description: Include completed items. Defaults to false.
          type: boolean
        searchTerm:
          description: Free-text search term applied to task and workflow names.
          type: string
        sortBy:
          title: MyWorkSortBy
          description: 'Sort key.


            - `DueDate` — sort by assignment due date.

            - `Name` — sort by task name (falls back to workflow run name if the task has no name).

            '
          type: string
          enum:
          - DueDate
          - Name
        sortOrder:
          title: MyWorkSortOrder
          description: 'Sort direction.


            - `Asc` — ascending.

            - `Desc` — descending.

            '
          type: string
          enum:
          - Asc
          - Desc
    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
    SnoozeStatus:
      title: SnoozeStatus
      type: string
      enum:
      - Active
      - Snoozed
    InboxItemType:
      title: InboxItemType
      type: string
      enum:
      - Checklist
      - StandardTask
      - ApprovalTask
      - OneOffTask
      - Acknowledgment
    SnoozeMyWorkItemRequest:
      title: SnoozeMyWorkItemRequest
      type: object
      required:
      - until
      properties:
        until:
          description: Snooze until this date (ISO-8601, e.g. 2024-06-01). Must be in the future.
          type: string
          format: date-time
    PublicApiSnoozedAssignmentResponse:
      title: PublicApiSnoozedAssignmentResponse
      type: object
      required:
      - data
      properties:
        data:
          title: PublicApiSnoozedAssignment
          description: The resource returned by this request.
          type: object
          required:
          - id
          - itemId
          - until
          properties:
            id:
              title: EntityID
              description: The resource's ID.
              type: string
            itemId:
              title: EntityID
              type: string
            until:
              description: The date until which the item is snoozed (ISO-8601).
              type: string
              format: date-time
        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