Update instance app surface settings

PUT

/api/v1/admin/apps/surfaces

const url = 'https://example.com/api/v1/admin/apps/surfaces';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"enabled":true,"surface":"notes"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://example.com/api/v1/admin/apps/surfaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "enabled": true, "surface": "notes" }'

Updates the instance app surface settings. It requires a signed-in User with the admin scope and the admin or owner Role. It can return 400 if the request is invalid, 401 if the session is missing or expired and 403 if access is denied. Route: /api/v1/admin/apps/surfaces. Inputs: . A recent account assertion is required. Do not automatically replay this operation after an uncertain result.

Authorizations

installationBearer
browserSession

Request Body^required

application/json

object

enabled

required

boolean

surface

required

These gates protect external automation credentials. Browser sessions remain usable so a User can always restore their own access in Settings.

string

Allowed values: notes api cli mcp mcp_events webmcp

Responses

200

application/json

object

effective_enabled

required

boolean

instance_enabled

required

boolean

surface

required

These gates protect external automation credentials. Browser sessions remain usable so a User can always restore their own access in Settings.

string

Allowed values: notes api cli mcp mcp_events webmcp

user_enabled

required

boolean

Example

{
  "surface": "notes"
}

Update instance app surface settings

Authorizations

Request Bodyrequired

Responses

200

Example

400

403

Request Body^required