Ensure surface (config-as-code converge)
Ensure surface (config-as-code converge)
Idempotently converge a repo-defined surface definition onto a product. Identity is name + product. Hash-only probes skip the payload in the steady state (a miss is a normal 200 `definitionRequired` response, not an error); full requests create the surface or update it when the canonical content hash differs. The response always carries the server-computed canonical hash. Set dryRun to plan without writing (CI drift gate), and onConflict: "overwrite" to converge over dashboard/API edits. Surfaces have no version snapshots, so there is no publish option.
Authentication
AuthorizationBearer
API key or Clerk session token
Path parameters
id
Request
This endpoint expects an object.
name
contentHash
definition
dryRun
expectedRemoteHash
onConflict
Allowed values:
Response
Converge result: unchanged | created | updated | definitionRequired (hash miss — retry with the full definition) | plan (dryRun)
OR
OR
Errors
400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error