update_connector_installation_settings

Purpose

Write the settings a connector declares for its installations. settings is an object keyed by the field names in the connector's settings_fields (read them with get_connector); every declared rule runs, a key the connector never declared is refused, and fields left out keep their value. The installation is returned without its settings, because a settings field may be a secret. The REST twin is PATCH /v1/projects/{project}/connectors/{key}/installation/settings.

Required ability

project-connector:update

Input schema

{
  "type": "object",
  "required": ["project_id", "connector"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the project."
    },
    "connector": {
      "type": "string",
      "description": "The connector key, as list_connectors returns it."
    },
    "settings": {
      "type": "object",
      "description": "The fields to change, keyed by the names the connector declares in settings_fields; fields left out keep their value. Optional when capabilities is given."
    },
    "capabilities": {
      "type": "object",
      "description": "Capability switches to change, keyed by capability value (messaging, broadcasts, support_relay, native_payments, recovery_*) to true or false; switches left out keep their value. Optional when settings is given."
    }
  }
}

At least one of settings and capabilities is required. A capability the connector does not declare, or one that cannot be switched off (access_control, early_admission_hold, management_surface, portal_login, creator_registration), is refused.

Output shape

The installation, as get_connector_installation renders it, capabilities included: every capability the connector declares with enabled and toggleable. Settings are never serialised.

Events emitted

• connector.settings_updated naming the fields and the switches (capabilities.<key>) that changed, only when something did.

Example prompts

"Set the Discord installation's welcome message on Research Premium to 'Welcome aboard'."

"Switch broadcasts off for the Telegram connector on Research Premium; keep everything else."

Failure modes

• AUTHENTICATION_REQUIRED — no authenticated user on the request.
• TOKEN_MISSING_ABILITY — token lacks project-connector:update.
• RESOURCE_NOT_FOUND — the project is not visible to this token, or context.reason is unknown_connector.
• CONNECTOR_NOT_INSTALLED — the project has no installation of the connector.
• VALIDATION_FAILED — a key the connector does not declare, a declared rule failed, a capability it does not declare or cannot switch off, a switch that is not true or false, or neither settings nor capabilities given; context names the field or the capability.

Related

• get_connector — the declared settings_fields.
• Connectors API