Update surface views

PUT /api/v1/surface-views/{savedSurfaceViewId}: request fields and declared response contract.

PUT/api/v1/surface-views/{savedSurfaceViewId}

Authorization
Property	Value
Permission	`settings.read`
Workspace scope	required
Scope target	workspace

Parameters

Path parameters
Field	Type	Required	Nullable	Default
savedSurfaceViewId	string	required	non-null	—

Query parameters: none.

Request body

Request body fields
Field	Type	Required	Nullable	Default
name	string	required	non-null	—
icon	string	optional	non-null	—
position	integer	optional	non-null	—
renderer	string	required	non-null	—
filters	reference	optional	non-null	—
sort	array	optional	non-null	—
visibleFields	array	optional	non-null	—
fieldOrder	array	optional	non-null	—
rendererConfig	object	optional	non-null	—
rendererConfig.collection	object	optional	non-null	—
rendererConfig.collection.presentation	string	required	non-null	—
rendererConfig.table	object	optional	non-null	—
rendererConfig.table.pageSize	integer	optional	non-null	—
rendererConfig.kanban	object	optional	non-null	—
rendererConfig.kanban.groupField	string	required	non-null	—
rendererConfig.calendar	object	optional	non-null	—
rendererConfig.calendar.dateField	string	required	non-null	—
rendererConfig.calendar.endDateField	string	optional	non-null	—
rendererConfig.calendar.timezone	string	optional	non-null	—
rendererConfig.map	object	optional	non-null	—
rendererConfig.map.locationBinding	string	required	non-null	—
rendererConfig.map.colorField	string	optional	non-null	—
rendererConfig.map.avatarField	string	optional	non-null	—
rendererConfig.map.defaultViewport	object	optional	non-null	—
rendererConfig.map.defaultViewport.center	object	required	non-null	—
rendererConfig.map.defaultViewport.zoom	number	required	non-null	—
rendererConfig.dataGrid	object	optional	non-null	—
rendererConfig.dataGrid.rowHeight	"comfortable" \| "compact"	optional	non-null	—
rendererConfig.dataGrid.pinnedFields	object	optional	non-null	—
rendererConfig.dataGrid.pinnedFields.left	array	optional	non-null	—
rendererConfig.dataGrid.pinnedFields.right	array	optional	non-null	—
rendererConfig.dataGrid.visibleFieldOrder	array	optional	non-null	—
rendererConfig.dataGrid.columnWidths	object	optional	non-null	—
descriptorCompatibilityHash	string	required	non-null	—

Response

200

Response fields
Field	Type	Required	Nullable	Default
data	object	required	non-null	—
data.id	string	required	non-null	—
data.companyId	string	required	non-null	—
data.target	unknown	required	non-null	—
data.name	string	required	non-null	—
data.icon	string	optional	non-null	—
data.position	integer	required	non-null	—
data.visibility	"personal" \| "team"	required	non-null	—
data.ownerUserId	string	optional	non-null	—
data.renderer	string	required	non-null	—
data.filters	reference	optional	non-null	—
data.sort	array	optional	non-null	—
data.visibleFields	array	optional	non-null	—
data.fieldOrder	array	optional	non-null	—
data.rendererConfig	object	optional	non-null	—
data.rendererConfig.collection	object	optional	non-null	—
data.rendererConfig.collection.presentation	string	required	non-null	—
data.rendererConfig.table	object	optional	non-null	—
data.rendererConfig.table.pageSize	integer	optional	non-null	—
data.rendererConfig.kanban	object	optional	non-null	—
data.rendererConfig.kanban.groupField	string	required	non-null	—
data.rendererConfig.calendar	object	optional	non-null	—
data.rendererConfig.calendar.dateField	string	required	non-null	—
data.rendererConfig.calendar.endDateField	string	optional	non-null	—
data.rendererConfig.calendar.timezone	string	optional	non-null	—
data.rendererConfig.map	object	optional	non-null	—
data.rendererConfig.map.locationBinding	string	required	non-null	—
data.rendererConfig.map.colorField	string	optional	non-null	—
data.rendererConfig.map.avatarField	string	optional	non-null	—
data.rendererConfig.map.defaultViewport	object	optional	non-null	—
data.rendererConfig.dataGrid	object	optional	non-null	—
data.rendererConfig.dataGrid.rowHeight	"comfortable" \| "compact"	optional	non-null	—
data.rendererConfig.dataGrid.pinnedFields	object	optional	non-null	—
data.rendererConfig.dataGrid.visibleFieldOrder	array	optional	non-null	—
data.rendererConfig.dataGrid.columnWidths	object	optional	non-null	—
data.descriptorCompatibilityHash	string	required	non-null	—
data.provenance	unknown	optional	non-null	—
data.createdAt	unknown	required	non-null	—
data.updatedAt	unknown	required	non-null	—

Declared failures

Declared failures
Property	Value
SAVED_SURFACE_VIEW_INVALID	400 — not retryable
SAVED_SURFACE_VIEW_NOT_FOUND	404 — not retryable
SAVED_SURFACE_VIEW_STORE_FAILED	503 — retryable

Readback

Read the result back with:

savedSurfaceViews.listScoped

Request example

Schematic only. Replace placeholders with real values and include all required nested fields.

PUT /api/v1/surface-views/{savedSurfaceViewId} HTTP/1.1
Authorization: Bearer <token>
x-merulan-workspace-id: <workspace-id>
Content-Type: application/json

{
  "name": "<name>",
  "renderer": "<renderer>",
  "descriptorCompatibilityHash": "<descriptorCompatibilityHash>"
}