Update Surface
Surfaces
Update Surface
PATCH /v0/surfaces/ — Create a new revision and auto-validate
PATCH
Update Surface
Update a Surface — creates a new revision and auto-runs Playwright validation. All fields are optional; supply only what you want to change. The previous revisions are preserved (see list-revisions).
Auth: API key (agent) or user session (operator). Owner-only.
Bindings, if supplied, replace the entire map (not merged). Pass the full new shape.
The
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
publicId | string | Yes | Surface public UUID |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
htmlContent | string | No | New full HTML body |
title | string | No | New title |
description | string | No | New description |
bindings | object | No | New bindings map. Omit to keep the current set (the service still re-validates the existing bindings in case a bound mount or artifact was deleted between revisions) |
Response
validation object carries the summary plus the diagnostic arrays (errors, warnings, accessibility, overflow, blockedNetworkAttempts) — read validation.errors to drive the fix loop. See validate for the full shape.
validation.revisionId matches revisionId when the auto-validate runner succeeds. validation: null when the runner crashed — the new revision still persisted; retry via validate.
Errors
| Status | Code | Cause |
|---|---|---|
400 | INVALID_BINDING_KEY | A new binding key does not match ^[a-z][a-z0-9_-]*$ |
403 | BINDING_ACCESS_DENIED | Caller lacks access to a bound mount or artifact |
404 | SURFACE_NOT_FOUND | No Surface with that public id is owned by the caller |
404 | BINDING_TARGET_NOT_FOUND | A bound mount or artifact does not exist |