custom-views-experimental

Update a custom view (experimental)

⚠️ Experimental — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.

Partially updates a view. Omitted fields are left unchanged. For REVISIONS, prefer the incremental fields — bundleEdits (exact search-and-replace on the stored render bundle) and queryUpserts/queryRemovals (per-query changes) — so you transmit only what changed instead of re-sending the whole payload. The full-replacement fields remain for rewrites: renderBundle, and queries (a FULL replacement of the query list — never drop queries the user didn't ask to remove). Replacement and incremental forms of the same aspect cannot be combined. The resulting SQL and bundle pass the same validation as createCustomView (SELECT-only, size cap, self-contained, paid:data listener). Works on DRAFT or PUBLISHED views — published embeds pick the change up on their next load. If the queries or hierarchy setting change during validation, returns 409 CUSTOM_VIEW_UPDATE_CONFLICT; fetch the current authoring definition and reapply your changes before retrying.

patch/experimental/views/{displayId}

Request

  • Base URL: https://api.agentpaid.io/api/v2
  • URL: https://api.agentpaid.io/api/v2/experimental/views/{displayId}
  • Auth: HTTP bearer

Path parameters

displayIdstring required

Request body

hierarchyEnabledboolean

Enable customer unit navigation for a customer-scoped view. Setting true requires customer hierarchies to be enabled for your organization, and every query must support unit selection. Existing views default to false.

capsEnabledboolean

Send the customer's unit caps to the render bundle as context.caps. Needs hierarchyEnabled on a customer-scoped view. Turn it on only for views that draw cap usage: each load then reads cap usage from billing. Caps are spend policy, so an API key also needs read:billing to receive them in the data (they are left out otherwise) or to mint this view's embed token. Defaults to false.

namestring

New human-readable view name.

descriptionstring nullable

New description; pass null to clear it.

renderBundlestring

Replacement render bundle. Re-validated (size cap, self-contained, paid:data listener) exactly like createCustomView. For small changes, prefer bundleEdits instead. Cannot be combined with bundleEdits.

queryRemovalsstring[]

Ids of stored queries to remove (applied before queryUpserts). Rejected if an id does not exist. Cannot be combined with queries.

Response

200

hierarchyEnabledboolean

Enable customer unit navigation for a customer-scoped view. Setting true requires customer hierarchies to be enabled for your organization, and every query must support unit selection. Existing views default to false.

capsEnabledboolean

Send the customer's unit caps to the render bundle as context.caps. Needs hierarchyEnabled on a customer-scoped view. Turn it on only for views that draw cap usage: each load then reads cap usage from billing. Caps are spend policy, so an API key also needs read:billing to receive them in the data (they are left out otherwise) or to mint this view's embed token. Defaults to false.

displayIdstring required

Stable public identifier used in preview/embed URLs.

namestring required
status'DRAFT' | 'PUBLISHED' required

A view is DRAFT until explicitly published. For customer-scoped views, only PUBLISHED views are embeddable and served to end-customers; a DRAFT is not. For organization-scoped views, publishing is only a 'ready to use' marker — both DRAFT and PUBLISHED are visible to your organization's members in Paid (publishing does not change who in the org can see it), and neither is ever embeddable to an end-customer.

previewUrlstring uri nullable required

Absolute URL to open this view in the Paid app for preview. Surface it to the user after creating or publishing a view. Null when the app URL is not configured.

scope'customer' | 'organization' required

'customer': data is scoped to one viewing customer and the view is embeddable per-customer. 'organization': data is org-wide and the view is internal-only.

Changes

No recorded changes to this operation across all 1 revision of this API.