Update a SurfaceScope
curl --request PATCH \
--url https://api.checkfu.com/v1/surface-scopes/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'checkfu-version: <checkfu-version>' \
--data '
{
"expected_version": 1,
"display_name": "<string>",
"verified_member": null,
"membership_assertion": null,
"ambient_policy": {
"enabled": true,
"muted": true,
"max_responses_per_window": 1,
"max_tokens_per_window": 1,
"self_quiet_threshold": 1
}
}
'import requests
url = "https://api.checkfu.com/v1/surface-scopes/{id}"
payload = {
"expected_version": 1,
"display_name": "<string>",
"verified_member": None,
"membership_assertion": None,
"ambient_policy": {
"enabled": True,
"muted": True,
"max_responses_per_window": 1,
"max_tokens_per_window": 1,
"self_quiet_threshold": 1
}
}
headers = {
"checkfu-version": "<checkfu-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'checkfu-version': '<checkfu-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
expected_version: 1,
display_name: '<string>',
verified_member: null,
membership_assertion: null,
ambient_policy: {
enabled: true,
muted: true,
max_responses_per_window: 1,
max_tokens_per_window: 1,
self_quiet_threshold: 1
}
})
};
fetch('https://api.checkfu.com/v1/surface-scopes/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.checkfu.com/v1/surface-scopes/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'expected_version' => 1,
'display_name' => '<string>',
'verified_member' => null,
'membership_assertion' => null,
'ambient_policy' => [
'enabled' => true,
'muted' => true,
'max_responses_per_window' => 1,
'max_tokens_per_window' => 1,
'self_quiet_threshold' => 1
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"checkfu-version: <checkfu-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.checkfu.com/v1/surface-scopes/{id}"
payload := strings.NewReader("{\n \"expected_version\": 1,\n \"display_name\": \"<string>\",\n \"verified_member\": null,\n \"membership_assertion\": null,\n \"ambient_policy\": {\n \"enabled\": true,\n \"muted\": true,\n \"max_responses_per_window\": 1,\n \"max_tokens_per_window\": 1,\n \"self_quiet_threshold\": 1\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("checkfu-version", "<checkfu-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.checkfu.com/v1/surface-scopes/{id}")
.header("checkfu-version", "<checkfu-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expected_version\": 1,\n \"display_name\": \"<string>\",\n \"verified_member\": null,\n \"membership_assertion\": null,\n \"ambient_policy\": {\n \"enabled\": true,\n \"muted\": true,\n \"max_responses_per_window\": 1,\n \"max_tokens_per_window\": 1,\n \"self_quiet_threshold\": 1\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.checkfu.com/v1/surface-scopes/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expected_version\": 1,\n \"display_name\": \"<string>\",\n \"verified_member\": null,\n \"membership_assertion\": null,\n \"ambient_policy\": {\n \"enabled\": true,\n \"muted\": true,\n \"max_responses_per_window\": 1,\n \"max_tokens_per_window\": 1,\n \"self_quiet_threshold\": 1\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"workspace_id": "<string>",
"external_installation_id": "<string>",
"external_id": "<string>",
"visibility": "public",
"membership": "public",
"inheritance": "inherit",
"display_name": "<string>",
"state": "active",
"version": 1,
"created_at": "<string>",
"updated_at": "<string>",
"kind": "root",
"parent_id": null,
"verified_member": {
"principal_id": "<string>",
"external_identity_link_id": "<string>",
"paired_at": "<string>"
},
"membership_assertion": {
"asserted_at": "<string>",
"freshness_horizon_seconds": 43230
},
"ambient_policy": {
"enabled": true,
"muted": true,
"max_responses_per_window": 1,
"max_tokens_per_window": 1,
"self_quiet_threshold": 1
}
}{
"error": {
"type": "validation.malformed",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#validation-malformed"
}
}{
"error": {
"type": "auth.invalid_key",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
}
}{
"error": {
"type": "auth.disabled_tenancy",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
}
}{
"error": {
"type": "validation.not_found",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#validation-not-found"
}
}{
"error": {
"type": "validation.conflict",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#validation-conflict"
}
}{
"error": {
"type": "budget.exceeded",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
}
}{
"error": {
"type": "runtime.internal",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#runtime-internal"
}
}Update a SurfaceScope
Updates a SurfaceScope’s state, visibility, membership, inheritance, or display_name under a compare-and-swap on expected_version. There is no DELETE for a scope: its lifecycle ends by patching state to archived, which is terminal and cannot be undone. Governance changes take effect at the documented check boundaries for placements already using the scope.
Checkfu support posture: alpha; hosted. Required evidence journey: collaboration-identity. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.
PATCH
/
v1
/
surface-scopes
/
{id}
Update a SurfaceScope
curl --request PATCH \
--url https://api.checkfu.com/v1/surface-scopes/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'checkfu-version: <checkfu-version>' \
--data '
{
"expected_version": 1,
"display_name": "<string>",
"verified_member": null,
"membership_assertion": null,
"ambient_policy": {
"enabled": true,
"muted": true,
"max_responses_per_window": 1,
"max_tokens_per_window": 1,
"self_quiet_threshold": 1
}
}
'import requests
url = "https://api.checkfu.com/v1/surface-scopes/{id}"
payload = {
"expected_version": 1,
"display_name": "<string>",
"verified_member": None,
"membership_assertion": None,
"ambient_policy": {
"enabled": True,
"muted": True,
"max_responses_per_window": 1,
"max_tokens_per_window": 1,
"self_quiet_threshold": 1
}
}
headers = {
"checkfu-version": "<checkfu-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'checkfu-version': '<checkfu-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
expected_version: 1,
display_name: '<string>',
verified_member: null,
membership_assertion: null,
ambient_policy: {
enabled: true,
muted: true,
max_responses_per_window: 1,
max_tokens_per_window: 1,
self_quiet_threshold: 1
}
})
};
fetch('https://api.checkfu.com/v1/surface-scopes/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.checkfu.com/v1/surface-scopes/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'expected_version' => 1,
'display_name' => '<string>',
'verified_member' => null,
'membership_assertion' => null,
'ambient_policy' => [
'enabled' => true,
'muted' => true,
'max_responses_per_window' => 1,
'max_tokens_per_window' => 1,
'self_quiet_threshold' => 1
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"checkfu-version: <checkfu-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.checkfu.com/v1/surface-scopes/{id}"
payload := strings.NewReader("{\n \"expected_version\": 1,\n \"display_name\": \"<string>\",\n \"verified_member\": null,\n \"membership_assertion\": null,\n \"ambient_policy\": {\n \"enabled\": true,\n \"muted\": true,\n \"max_responses_per_window\": 1,\n \"max_tokens_per_window\": 1,\n \"self_quiet_threshold\": 1\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("checkfu-version", "<checkfu-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.checkfu.com/v1/surface-scopes/{id}")
.header("checkfu-version", "<checkfu-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expected_version\": 1,\n \"display_name\": \"<string>\",\n \"verified_member\": null,\n \"membership_assertion\": null,\n \"ambient_policy\": {\n \"enabled\": true,\n \"muted\": true,\n \"max_responses_per_window\": 1,\n \"max_tokens_per_window\": 1,\n \"self_quiet_threshold\": 1\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.checkfu.com/v1/surface-scopes/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expected_version\": 1,\n \"display_name\": \"<string>\",\n \"verified_member\": null,\n \"membership_assertion\": null,\n \"ambient_policy\": {\n \"enabled\": true,\n \"muted\": true,\n \"max_responses_per_window\": 1,\n \"max_tokens_per_window\": 1,\n \"self_quiet_threshold\": 1\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"workspace_id": "<string>",
"external_installation_id": "<string>",
"external_id": "<string>",
"visibility": "public",
"membership": "public",
"inheritance": "inherit",
"display_name": "<string>",
"state": "active",
"version": 1,
"created_at": "<string>",
"updated_at": "<string>",
"kind": "root",
"parent_id": null,
"verified_member": {
"principal_id": "<string>",
"external_identity_link_id": "<string>",
"paired_at": "<string>"
},
"membership_assertion": {
"asserted_at": "<string>",
"freshness_horizon_seconds": 43230
},
"ambient_policy": {
"enabled": true,
"muted": true,
"max_responses_per_window": 1,
"max_tokens_per_window": 1,
"self_quiet_threshold": 1
}
}{
"error": {
"type": "validation.malformed",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#validation-malformed"
}
}{
"error": {
"type": "auth.invalid_key",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
}
}{
"error": {
"type": "auth.disabled_tenancy",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
}
}{
"error": {
"type": "validation.not_found",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#validation-not-found"
}
}{
"error": {
"type": "validation.conflict",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#validation-conflict"
}
}{
"error": {
"type": "budget.exceeded",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
}
}{
"error": {
"type": "runtime.internal",
"message": "<string>",
"more": "https://docs.checkfu.com/reference/errors#runtime-internal"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Available options:
2026-08-27 Path Parameters
Pattern:
^surf_[0-9a-f]{32}$Body
application/json
Required range:
x > 0Available options:
active, disabled, disconnected, archived Available options:
public, private, personal Available options:
public, provider_members, personal Available options:
inherit, isolate Required string length:
1 - 255Show child attributes
Show child attributes
Response
Success
- Option 1
- Option 2
Pattern:
^surf_[0-9a-f]{32}$Pattern:
^wrkspc_[0-9a-f]{32}$Pattern:
^exti_[0-9a-f]{32}$Required string length:
1 - 512Available options:
public, private, personal Available options:
public, provider_members, personal Available options:
inherit, isolate Required string length:
1 - 255Available options:
active, disabled, disconnected, archived Required range:
x > 0Available options:
root Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes