Views endpoints

Shared saved views (filters + sort) and the runs they select. Every operation with parameters, body, responses, errors and examples.

View this page as Markdown

Shared saved views (filters + sort) and the runs they select.

Base URL https://app.processcart.com/api/v1. Every operation below is also in the OpenAPI document and the interactive reference.

Operation Method and path Scope
List shared views GET /v1/views Scope views:read
Create a shared view POST /v1/views Scope views:write
Get a shared view GET /v1/views/{id} Scope views:read
Update a shared view PATCH /v1/views/{id} Scope views:write
Delete a shared view DELETE /v1/views/{id} Scope views:write
List the runs a view selects GET /v1/views/{id}/runs Scope runs:read

GET /v1/views

List shared views. Scope views:read · paginated ({ data, nextCursor, hasMore }). Operation id listViews · open in the API reference.

Every saved view shared with the workspace (org) or with groups (groups), by name, with the board query each one selects. Private views never appear. updatedSince turns the list into an incremental sync ordered by updatedAt ascending (inclusive).

Query parameters (an unknown parameter is a 422 validation_failed with errors[].code = "unknown_parameter")

Name Type Required Description
updatedSince string (date-time) no Incremental sync: only items whose updatedAt is at or after this instant (inclusive), ordered by updatedAt ascending; an explicit conflicting sort / order is a 422. Overlap by a minute and dedupe: a Run by (id, revision), any other item (workflow, view, webhook, schedule, automation rule) by (id, updatedAt) — a higher revision or a later updatedAt replaces the copy you hold, an equal one is unchanged.
limit integer no
cursor string no The nextCursor of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422.

Responses

Status Meaning Body
200 OK. ListViewsResponse
401 No usable credential. unauthorized — Authentication required; invalid_api_key — Invalid API key; key_revoked — API key revoked. Problem
403 insufficient_scope — Insufficient scope. Problem
405 The verb is not supported on this path. method_not_allowed — Method not allowed. Problem
422 validation_failed — Validation failed. Problem
429 rate_limited — Too many requests. Problem
500 internal_error — Internal error. Problem
503 unavailable — Service unavailable. Problem

Errors (every code this operation can answer; see Errors)

Example response (200)

{
  "data": [
    {
      "id": "d9d20dae-2010-4211-8b78-d724b96d3125",
      "name": "Alpha board",
      "query": {
        "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
        "status": [],
        "priority": [],
        "labels": [],
        "assignee": null,
        "due": null,
        "q": "",
        "qMode": "prefix",
        "sort": {
          "key": "started",
          "dir": "desc"
        },
        "columns": [
          "status",
          "priority",
          "progress",
          "key_date",
          "due",
          "assignees",
          "started"
        ]
      },
      "visibility": "org",
      "groupIds": [],
      "owner": {
        "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
        "name": "Fixture Admin"
      },
      "createdAt": "2026-10-13T00:39:38.376Z",
      "updatedAt": "2026-10-13T00:39:38.376Z"
    },
    {
      "id": "11478b4b-5c42-4bb8-829e-65d4c8493a3a",
      "name": "Reviewers' queue",
      "query": {
        "workflowId": null,
        "status": [
          "active",
          "on_hold"
        ],
        "priority": [],
        "labels": [],
        "assignee": {
          "kind": "group",
          "id": "46139a8e-9621-4f2c-98f3-8975bb8d2589"
        },
        "due": null,
        "q": "",
        "qMode": "prefix",
        "sort": {
          "key": "started",
          "dir": "desc"
        },
        "columns": [
          "status",
          "priority",
          "progress",
          "key_date",
          "due",
          "assignees",
          "started"
        ]
      },
      "visibility": "groups",
      "groupIds": [
        "46139a8e-9621-4f2c-98f3-8975bb8d2589"
      ],
      "owner": {
        "userId": "4f9b94a3-9d38-479d-a0f3-9c8f01dcff92",
        "name": "Fixture Member"
      },
      "createdAt": "2026-10-13T00:39:38.462Z",
      "updatedAt": "2026-10-13T00:39:38.462Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

POST /v1/views

Create a shared view. Scope views:write · accepts Idempotency-Key. Operation id createView · open in the API reference.

Saves a board query as a view shared with everyone (default) or with specific groups. Send only the query members you set — the rest take the board's defaults, and the response carries the complete query. The view is owned by the member who created the API key, who must still be a Builder or Admin of the workspace (else 403 — mint a key as a current Admin). Each owner keeps at most 30 views.

Request headers

Name Type Required Description
Idempotency-Key string no Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same Expected-Revision) replays the stored response (Idempotent-Replayed: true); a different body with the same key is refused (422 idempotency_key_reused) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 idempotency_key_reused), so prefix keys per integration. 409, 429 and 5xx answers are never stored.

Request body — application/json, CreateViewBody

Property Type Required Description
name string yes
query object yes The board query the view selects. Send only the members you set; the rest take the board's defaults: {"workflowId":null,"status":["active","on_hold"],"priority":[],"labels":[],"assignee":null,"due":null,"q":"","qMode":"prefix","sort":{"key":"started","dir":"desc"},"columns":["status","priority","progress","key_date","due","assignees","started"]}. sort.key without dir takes that key's natural direction (asc for name, key_date and due, else desc). An unknown member is a 422.
visibility "org" \ "groups" no
groupIds Uuid[] no

Responses

Status Meaning Body
201 Created. Location names the new resource. View
401 No usable credential. unauthorized — Authentication required; invalid_api_key — Invalid API key; key_revoked — API key revoked. Problem
403 insufficient_scope — Insufficient scope; not_allowed_for_key — Not allowed for this key; read_only_key — Read-only key. Problem
405 The verb is not supported on this path. method_not_allowed — Method not allowed. Problem
409 idempotency_in_progress — Request in progress. Problem
413 payload_too_large — Payload too large. Problem
415 unsupported_media_type — Unsupported media type. Problem
422 idempotency_key_reused — Idempotency key reused; validation_failed — Validation failed. Problem
429 rate_limited — Too many requests. Problem
500 internal_error — Internal error. Problem
503 unavailable — Service unavailable. Problem

Errors (every code this operation can answer; see Errors)

Example request

{
  "name": "Active by name",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [
      "active"
    ],
    "sort": {
      "key": "name"
    }
  }
}

Example response (201)

{
  "id": "6885f52f-03a9-464e-b9bb-95b359a3a57b",
  "name": "Active by name",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [
      "active"
    ],
    "priority": [],
    "labels": [],
    "assignee": null,
    "due": null,
    "q": "",
    "qMode": "prefix",
    "sort": {
      "key": "name",
      "dir": "asc"
    },
    "columns": [
      "status",
      "priority",
      "progress",
      "key_date",
      "due",
      "assignees",
      "started"
    ]
  },
  "visibility": "org",
  "groupIds": [],
  "owner": {
    "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
    "name": "Fixture Admin"
  },
  "createdAt": "2026-10-13T00:39:39.520Z",
  "updatedAt": "2026-10-13T00:39:39.520Z"
}

GET /v1/views/{id}

Get a shared view. Scope views:read. Operation id getView · open in the API reference.

One shared view with its query. A private view — even one owned by the member who created the key — is a 404.

Path parameters

Name Type Required Description
id string (uuid) yes

Responses

Status Meaning Body
200 OK. View
401 No usable credential. unauthorized — Authentication required; invalid_api_key — Invalid API key; key_revoked — API key revoked. Problem
403 insufficient_scope — Insufficient scope. Problem
404 not_found — Not found. Problem
405 The verb is not supported on this path. method_not_allowed — Method not allowed. Problem
422 validation_failed — Validation failed. Problem
429 rate_limited — Too many requests. Problem
500 internal_error — Internal error. Problem
503 unavailable — Service unavailable. Problem

Errors (every code this operation can answer; see Errors)

Example response (200)

{
  "id": "d9d20dae-2010-4211-8b78-d724b96d3125",
  "name": "Alpha board",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [],
    "priority": [],
    "labels": [],
    "assignee": null,
    "due": null,
    "q": "",
    "qMode": "prefix",
    "sort": {
      "key": "started",
      "dir": "desc"
    },
    "columns": [
      "status",
      "priority",
      "progress",
      "key_date",
      "due",
      "assignees",
      "started"
    ]
  },
  "visibility": "org",
  "groupIds": [],
  "owner": {
    "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
    "name": "Fixture Admin"
  },
  "createdAt": "2026-10-13T00:39:38.376Z",
  "updatedAt": "2026-10-13T00:39:38.376Z"
}

PATCH /v1/views/{id}

Update a shared view. Scope views:write · accepts Idempotency-Key. Operation id updateView · open in the API reference.

Renames a view, changes its query or changes who it is shared with. A query changes only the members it sends; the rest keep the view's stored values. Only a view owned by the member who created the key can be changed through the API, and that member must still be a Builder or Admin of the workspace (403 not_allowed_for_key otherwise). Switching to org drops the group list; groups needs at least one group of the workspace.

Path parameters

Name Type Required Description
id string (uuid) yes

Request headers

Name Type Required Description
Idempotency-Key string no Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same Expected-Revision) replays the stored response (Idempotent-Replayed: true); a different body with the same key is refused (422 idempotency_key_reused) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 idempotency_key_reused), so prefix keys per integration. 409, 429 and 5xx answers are never stored.

Request body — application/json, UpdateViewBody

Property Type Required Description
name string no
query object no Changes to the view's board query. Send only the members you change; the rest keep the view's stored values (null clears workflowId, assignee or due). sort.key without dir takes that key's natural direction. An unknown member is a 422.
visibility "org" \ "groups" no
groupIds Uuid[] no

Responses

Status Meaning Body
200 OK. View
401 No usable credential. unauthorized — Authentication required; invalid_api_key — Invalid API key; key_revoked — API key revoked. Problem
403 insufficient_scope — Insufficient scope; not_allowed_for_key — Not allowed for this key; read_only_key — Read-only key. Problem
404 not_found — Not found. Problem
405 The verb is not supported on this path. method_not_allowed — Method not allowed. Problem
409 idempotency_in_progress — Request in progress. Problem
413 payload_too_large — Payload too large. Problem
415 unsupported_media_type — Unsupported media type. Problem
422 idempotency_key_reused — Idempotency key reused; validation_failed — Validation failed. Problem
429 rate_limited — Too many requests. Problem
500 internal_error — Internal error. Problem
503 unavailable — Service unavailable. Problem

Errors (every code this operation can answer; see Errors)

Example request

{
  "name": "Alpha board (renamed)"
}

Example response (200)

{
  "id": "d9d20dae-2010-4211-8b78-d724b96d3125",
  "name": "Alpha board (renamed)",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [],
    "priority": [],
    "labels": [],
    "assignee": null,
    "due": null,
    "q": "",
    "qMode": "prefix",
    "sort": {
      "key": "started",
      "dir": "desc"
    },
    "columns": [
      "status",
      "priority",
      "progress",
      "key_date",
      "due",
      "assignees",
      "started"
    ]
  },
  "visibility": "groups",
  "groupIds": [
    "46139a8e-9621-4f2c-98f3-8975bb8d2589"
  ],
  "owner": {
    "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
    "name": "Fixture Admin"
  },
  "createdAt": "2026-10-13T00:39:38.376Z",
  "updatedAt": "2026-10-13T00:39:41.545Z"
}

DELETE /v1/views/{id}

Delete a shared view. Scope views:write · accepts Idempotency-Key. Operation id deleteView · open in the API reference.

Removes any shared view of the workspace, whoever owns it (the same power an Admin has in the app); the deletion is recorded in the audit log under the key's name. A private view is a 404.

Path parameters

Name Type Required Description
id string (uuid) yes

Request headers

Name Type Required Description
Idempotency-Key string no Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same Expected-Revision) replays the stored response (Idempotent-Replayed: true); a different body with the same key is refused (422 idempotency_key_reused) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 idempotency_key_reused), so prefix keys per integration. 409, 429 and 5xx answers are never stored.

Responses

Status Meaning Body
204 Done; no body. —
401 No usable credential. unauthorized — Authentication required; invalid_api_key — Invalid API key; key_revoked — API key revoked. Problem
403 insufficient_scope — Insufficient scope; read_only_key — Read-only key. Problem
404 not_found — Not found. Problem
405 The verb is not supported on this path. method_not_allowed — Method not allowed. Problem
409 idempotency_in_progress — Request in progress. Problem
422 idempotency_key_reused — Idempotency key reused; validation_failed — Validation failed. Problem
429 rate_limited — Too many requests. Problem
500 internal_error — Internal error. Problem
503 unavailable — Service unavailable. Problem

Errors (every code this operation can answer; see Errors)

GET /v1/views/{id}/runs

List the runs a view selects. Scope runs:read · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated ({ data, nextCursor, hasMore }). Operation id listViewRuns · open in the API reference.

Applies the view's stored query — filters and sort, exactly as the board does — and returns FULL Run resources, paged like GET /v1/runs and limited to the key's allowlist. A view that filters by the viewer (assignee: me) cannot be resolved for a key: call GET /v1/runs?assignee=u:<user id> instead (422). A view sorted by progress is a 422 too (that sort is computed in the app). updatedSince orders by updatedAt ascending instead of the view's sort.

Path parameters

Name Type Required Description
id string (uuid) yes

Query parameters (an unknown parameter is a 422 validation_failed with errors[].code = "unknown_parameter")

Name Type Required Description
updatedSince string (date-time) no Incremental sync: only items whose updatedAt is at or after this instant (inclusive), ordered by updatedAt ascending; an explicit conflicting sort / order is a 422. Overlap by a minute and dedupe: a Run by (id, revision), any other item (workflow, view, webhook, schedule, automation rule) by (id, updatedAt) — a higher revision or a later updatedAt replaces the copy you hold, an equal one is unchanged.
limit integer no
cursor string no The nextCursor of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422.

Responses

Status Meaning Body
200 OK. ListViewRunsResponse
401 No usable credential. unauthorized — Authentication required; invalid_api_key — Invalid API key; key_revoked — API key revoked. Problem
403 insufficient_scope — Insufficient scope. Problem
404 not_found — Not found. Problem
405 The verb is not supported on this path. method_not_allowed — Method not allowed. Problem
422 validation_failed — Validation failed. Problem
429 rate_limited — Too many requests. Problem
500 internal_error — Internal error. Problem
503 unavailable — Service unavailable. Problem

Errors (every code this operation can answer; see Errors)

Example response (200)

{
  "data": [
    {
      "id": "c4f32706-55c2-4524-8193-8ca38969a675",
      "name": "View run one",
      "status": "active",
      "priority": "none",
      "labels": [],
      "labelDetails": [],
      "dueAt": null,
      "keyDate": null,
      "revision": 1,
      "updatedAt": "2026-10-13T00:39:49.561Z",
      "startedAt": "2026-10-13T00:39:49.462Z",
      "startedBy": "api",
      "startedByUserId": null,
      "schedule": null,
      "scheduledFor": null,
      "completedAt": null,
      "deletedAt": null,
      "workflow": {
        "id": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
        "name": "Order fulfillment"
      },
      "versionId": "36e87c9b-845a-4294-942e-809c38fa6137",
      "url": "https://app.processcart.com/runs/c4f32706-55c2-4524-8193-8ca38969a675",
      "tasks": [
        {
          "key": "details",
          "title": "Details",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "review",
          "title": "Review",
          "kind": "approval",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [
            {
              "kind": "user",
              "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60"
            }
          ],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "stop",
          "title": "Sign-off",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "wrapup",
          "title": "Wrap up",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": true,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        }
      ],
      "fields": [
        {
          "key": "customer",
          "label": "Customer",
          "type": "text",
          "format": "none",
          "taskKey": "details",
          "value": "Ann",
          "formatted": "Ann",
          "visible": true
        },
        {
          "key": "order_code",
          "label": "Order code",
          "type": "text",
          "format": "custom",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "memo",
          "label": "Memo",
          "type": "textarea",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "quantity",
          "label": "Quantity",
          "type": "number",
          "format": "number",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "amount",
          "label": "Amount",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": 1700,
          "formatted": "$1,700.00",
          "visible": true
        },
        {
          "key": "fee",
          "label": "Fee",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate",
          "label": "Rate",
          "type": "number",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate_text",
          "label": "Rate (text)",
          "type": "text",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "ship_date",
          "label": "Ship date",
          "type": "date",
          "format": "date",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "start_time",
          "label": "Start time",
          "type": "time",
          "format": "time",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "gift_wrap",
          "label": "Gift wrap",
          "type": "dropdown",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "Yes",
            "No"
          ]
        },
        {
          "key": "tags",
          "label": "Tags",
          "type": "multi_choice",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "A",
            "B",
            "C"
          ]
        },
        {
          "key": "agree",
          "label": "Agree",
          "type": "checkbox",
          "format": null,
          "taskKey": "details",
          "value": false,
          "formatted": "No",
          "visible": true
        },
        {
          "key": "contact_email",
          "label": "Contact email",
          "type": "email",
          "format": "email",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "website",
          "label": "Website",
          "type": "url",
          "format": "url",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "phone",
          "label": "Phone",
          "type": "phone",
          "format": "phone",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "owner",
          "label": "Owner",
          "type": "members",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "steps",
          "label": "Steps",
          "type": "subtasks",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "items": [
            {
              "key": "photos",
              "label": "Photos"
            },
            {
              "key": "invoice",
              "label": "Invoice"
            }
          ]
        },
        {
          "key": "contract",
          "label": "Contract",
          "type": "file",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "double_amount",
          "label": "Double amount",
          "type": "formula",
          "format": "currency",
          "taskKey": "details",
          "value": 3400,
          "formatted": "$3,400.00",
          "visible": true
        },
        {
          "key": "source",
          "label": "Source",
          "type": "hidden",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": false
        }
      ]
    }
  ],
  "nextCursor": null,
  "hasMore": false
}