openapi: 3.1.0
info:
title: Process Street Public Attachments Page 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: Page Widgets
description: 'A page widget is a content element (text, image, video, file, embed, cross-link, or table)
on a page revision. Use these endpoints to create and manage widgets on draft revisions.'
externalDocs:
url: https://www.process.st/help/docs/pages/
description: Process Street help article
paths:
/pages/{pageId}/revisions/{revisionId}/widgets/{widgetId}:
get:
tags:
- Page Widgets
summary: Get a page widget
description: Returns a widget by its ID on a page revision.
operationId: getPageRevisionWidget
parameters:
- name: pageId
in: path
description: The ID of the Page
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
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:
- Page Widgets
summary: Update a page widget
description: 'Updates a widget on a draft page revision. PUT semantics: all mutable fields must be provided.
Returns the updated widget.'
operationId: updatePageRevisionWidget
parameters:
- name: pageId
in: path
description: The ID of the Page
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
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/UpdatePageWidgetRequest'
examples:
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:
- Page Widgets
summary: Delete a page widget
description: Deletes a widget from a draft page revision.
operationId: deletePageRevisionWidget
parameters:
- name: pageId
in: path
description: The ID of the Page
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
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: []
/pages/{pageId}/revisions/{revisionId}/widgets:
get:
tags:
- Page Widgets
summary: List page widgets
description: Returns widgets on a page revision, ordered by position.
operationId: listPageRevisionWidgets
parameters:
- name: pageId
in: path
description: The ID of the Page
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
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 (pages do not support FormField widgets).
- `Text` — rich text content.
- `Image` — image content.
- `File` — downloadable file.
- `Video` — video content (uploaded or linked).
- `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:
- Page Widgets
summary: Create a page widget
description: Creates a widget on a draft page revision.
operationId: createPageRevisionWidget
parameters:
- name: pageId
in: path
description: The ID of the Page
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePageWidgetRequest'
examples:
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 image 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: []
/pages/{pageId}/revisions/{revisionId}/widgets/{widgetId}/upload:
post:
tags:
- Page Widgets
summary: Upload a file to a page widget
description: 'Uploads a file to an Image or File widget on a draft page 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: uploadPageRevisionWidgetFile
parameters:
- name: pageId
in: path
description: The ID of the Page
required: true
schema:
type: string
- name: revisionId
in: path
description: The ID of the Revision
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
CreatePageWidgetRequest:
title: CreatePageWidgetRequest
description: A widget on a page. The `type` discriminator selects the widget kind — `Text`, `Image`, `File`, `Video`, `Embed`, or `CrossLink`. Pages do not support form-field widgets.
oneOf:
- title: CreatePageCrossLinkWidgetRequest
type: object
required:
- type
properties:
hiddenByDefault:
description: When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
type: boolean
position:
title: WidgetPosition
description: Where to place this widget on the task. `Top` — before all existing widgets. `Bottom` — after all existing widgets (default when `position` is omitted). `After` — immediately after the widget identified by `widgetId`.
oneOf:
- title: WidgetPositionAfter
type: object
required:
- widgetId
- type
properties:
widgetId:
title: EntityID
description: The ID of the widget.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: After
- title: WidgetPositionBottom
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Bottom
- title: WidgetPositionTop
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Top
discriminator:
propertyName: type
mapping:
After: '#/components/schemas/WidgetPositionAfter'
Bottom: '#/components/schemas/WidgetPositionBottom'
Top: '#/components/schemas/WidgetPositionTop'
linkedTemplateId:
title: EntityID
description: The ID of the linked workflow or page that this CrossLink widget points to.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
enum:
- Text
- Image
- File
- Video
- Embed
- CrossLink
const: CrossLink
- title: CreatePageEmbedWidgetRequest
type: object
required:
- type
properties:
hiddenByDefault:
description: When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
type: boolean
position:
title: WidgetPosition
description: Where to place this widget on the task. `Top` — before all existing widgets. `Bottom` — after all existing widgets (default when `position` is omitted). `After` — immediately after the widget identified by `widgetId`.
oneOf:
- title: WidgetPositionAfter
type: object
required:
- widgetId
- type
properties:
widgetId:
title: EntityID
description: The ID of the widget.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: After
- title: WidgetPositionBottom
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Bottom
- title: WidgetPositionTop
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Top
discriminator:
propertyName: type
mapping:
After: '#/components/schemas/WidgetPositionAfter'
Bottom: '#/components/schemas/WidgetPositionBottom'
Top: '#/components/schemas/WidgetPositionTop'
url:
description: Target URL.
type: string
maxLength: 4000
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
enum:
- Text
- Image
- File
- Video
- Embed
- CrossLink
const: Embed
- title: CreatePageFileWidgetRequest
type: object
required:
- type
properties:
hiddenByDefault:
description: When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
type: boolean
position:
title: WidgetPosition
description: Where to place this widget on the task. `Top` — before all existing widgets. `Bottom` — after all existing widgets (default when `position` is omitted). `After` — immediately after the widget identified by `widgetId`.
oneOf:
- title: WidgetPositionAfter
type: object
required:
- widgetId
- type
properties:
widgetId:
title: EntityID
description: The ID of the widget.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: After
- title: WidgetPositionBottom
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Bottom
- title: WidgetPositionTop
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Top
discriminator:
propertyName: type
mapping:
After: '#/components/schemas/WidgetPositionAfter'
Bottom: '#/components/schemas/WidgetPositionBottom'
Top: '#/components/schemas/WidgetPositionTop'
description:
description: Optional long-form description.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
enum:
- Text
- Image
- File
- Video
- Embed
- CrossLink
const: File
- title: CreatePageImageWidgetRequest
type: object
required:
- type
properties:
hiddenByDefault:
description: When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
type: boolean
position:
title: WidgetPosition
description: Where to place this widget on the task. `Top` — before all existing widgets. `Bottom` — after all existing widgets (default when `position` is omitted). `After` — immediately after the widget identified by `widgetId`.
oneOf:
- title: WidgetPositionAfter
type: object
required:
- widgetId
- type
properties:
widgetId:
title: EntityID
description: The ID of the widget.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: After
- title: WidgetPositionBottom
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Bottom
- title: WidgetPositionTop
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Top
discriminator:
propertyName: type
mapping:
After: '#/components/schemas/WidgetPositionAfter'
Bottom: '#/components/schemas/WidgetPositionBottom'
Top: '#/components/schemas/WidgetPositionTop'
caption:
description: Caption text rendered with the image.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
enum:
- Text
- Image
- File
- Video
- Embed
- CrossLink
const: Image
- title: CreatePageTextWidgetRequest
type: object
required:
- type
properties:
hiddenByDefault:
description: When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
type: boolean
position:
title: WidgetPosition
description: Where to place this widget on the task. `Top` — before all existing widgets. `Bottom` — after all existing widgets (default when `position` is omitted). `After` — immediately after the widget identified by `widgetId`.
oneOf:
- title: WidgetPositionAfter
type: object
required:
- widgetId
- type
properties:
widgetId:
title: EntityID
description: The ID of the widget.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: After
- title: WidgetPositionBottom
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Bottom
- title: WidgetPositionTop
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Top
discriminator:
propertyName: type
mapping:
After: '#/components/schemas/WidgetPositionAfter'
Bottom: '#/components/schemas/WidgetPositionBottom'
Top: '#/components/schemas/WidgetPositionTop'
content:
description: Rich text content. May contain merge tags.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
enum:
- Text
- Image
- File
- Video
- Embed
- CrossLink
const: Text
- title: CreatePageVideoWidgetRequest
type: object
required:
- type
properties:
hiddenByDefault:
description: When `true`, the widget is hidden by default; conditional logic rules can reveal it at runtime. Defaults to `false`.
type: boolean
position:
title: WidgetPosition
description: Where to place this widget on the task. `Top` — before all existing widgets. `Bottom` — after all existing widgets (default when `position` is omitted). `After` — immediately after the widget identified by `widgetId`.
oneOf:
- title: WidgetPositionAfter
type: object
required:
- widgetId
- type
properties:
widgetId:
title: EntityID
description: The ID of the widget.
type: string
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: After
- title: WidgetPositionBottom
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Bottom
- title: WidgetPositionTop
type: object
required:
- type
properties:
type:
description: Discriminator value for this variant. See the parent oneOf for the full set of values.
type: string
const: Top
# --- truncated at 32 KB (285 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/process-street/refs/heads/main/openapi/process-street-page-widgets-api-openapi.yml