openapi: 3.1.0
info:
title: Process Street Public Attachments My Work 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: 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:
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
SnoozeStatus:
title: SnoozeStatus
type: string
enum:
- Active
- Snoozed
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
InboxItemType:
title: InboxItemType
type: string
enum:
- Checklist
- StandardTask
- ApprovalTask
- OneOffTask
- Acknowledgment
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
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
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
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