--- title: "Patch Instance" method: PATCH path: "/api/integrations/instances/{instance_id}" tags: ["integrations"] --- # Patch Instance `PATCH /api/integrations/instances/{instance_id}` ## Request - Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from) - URL: `https://app.thinqos.com/api/integrations/instances/{instance_id}` - Auth: none declared Update editable settings on an integration (connected tool / MCP & OAuth registration) you own — a partial update, so pass ONLY the fields you want to change; omitted fields are left untouched. Set alias to rename only this connection; name and description edit the shared connector definition used by sibling connections. The registration_id comes from integration_list. Editable fields: - alias: the display name (e.g. rename 'Gmail (read-only)' to 'Gmail — dan@example.com'). Must be non-empty. - health_check_tool: the tool the proactive probe + 'Test connection' call to validate the credential. tools/list-only by default, which can show green even when a per-user OAuth credential is dead; naming a safe READ-ONLY no-required-args tool (e.g. 'list_calendars', 'list_files') makes the probe actually exercise the credential. Pass an empty string to clear it (revert to tools/list-only). - health_check_arguments: reviewed JSON arguments for the safe probe. These are stored on the profile and supplied by the platform, never by the caller of the synthetic health tool. - health_check_declined + health_check_decline_reason: explicitly record that no safe probe exists and why. Declining clears the configured tool and arguments. - enabled: enable/disable the integration. - description: free-text description. - connection_mode: 'shared' (one credential the whole folder uses) or 'per_caller' (each identity connects and uses their own credential). shared -> per_caller is a pure flip. per_caller -> shared keeps only the most-recently-updated connection and deletes the rest; if more than one row would be deleted this fails with the count unless you also pass confirm_credential_deletion=true. In a folder with MORE THAN ONE member, per_caller -> shared also means 'Share the owner's account with this group' — everyone acts as one account — so it fails with the blast radius unless you also pass confirm_shared_account_exposure=true. Show that to the user first; the safe default is 'Each member connects separately' (per_caller). Fails with a clear message if you don't own the integration, the new alias collides, connection_mode is invalid, a per_caller -> shared downgrade needs confirmation, or no editable field was provided. ## Path parameters - `instance_id` string, uuid, required ## Headers - `x-impersonate-identity-id` string, nullable ## Request body - RegistrationUpdate: Patch payload. Unset fields are not modified. Including ``auth_kind`` switches the registration's authentication mode in place. The service clears stale fields for the previous mode (e.g. switching to ``oauth2`` clears ``auth_header_name`` + ``auth_secret_ref`` and any cached OAuth tokens, forcing a re-Connect). To prevent leaving the row in an inconsistent state, ``auth_header_name`` and ``oauth_resource_url`` may only be set when ``auth_kind`` is also set. ``alias`` edits the configured instance display name. ``name`` is retained for legacy definition/template-source renames. ``transport`` and ``base_url`` are also editable. The service clears state that no longer applies on transitions: a ``base_url`` change on an oauth2 registration drops the cached tokens (the audience moved); any transport change clears ``last_test_*`` since the upstream tool catalog is no longer authoritative. - `name` string, nullable: Shared connector definition name. Changes every connection using that definition and this connection's alias. To rename only this connection, set alias instead. - `alias` string, nullable: Display label for this connection only. Does not rename sibling connections. - `transport` 'http' | 'sse' | 'stdio_bridge' | 'rest', nullable - `base_url` string, nullable - `display_icon_url` string, nullable - `description` string, nullable: Shared connector definition description. Changes every connection using that definition; this is not a per-connection note. - `trusted` boolean, nullable - `enabled` boolean, nullable - `refresh_seconds` integer, nullable - `rate_limit_per_minute` integer, nullable - `request_max_bytes` integer, nullable - `response_max_bytes` integer, nullable - `plaintext_secret` string, nullable - `health_check_tool` string, nullable - `health_check_arguments` object, nullable - `health_check_declined` boolean, nullable - `health_check_decline_reason` string, nullable - `impersonate_service_account` string, nullable - `oauth_client_id` string, nullable - `oauth_authorization_url` string, nullable - `oauth_token_url` string, nullable - `oauth_registration_url` string, nullable - `oauth_scopes` string, nullable - `oauth_pkce_enabled` boolean, nullable - `oauth_client_secret_plaintext` string, nullable - `auth_kind` 'none' | 'bearer' | 'api_key_header' | 'oauth2' | 'gcp_oidc' | 'gcp_service_account' | 'github_app', nullable - `auth_header_name` string, nullable - `oauth_resource_url` string, nullable - `stdio_command` string, nullable - `stdio_args` unknown[], nullable - unknown - `stdio_env` object, nullable - `rest_manifest` object, nullable - `rest_openapi_source_url` string, nullable - `secret_refs` object, nullable - `secret_values` object, nullable - `remove_secret_names` string[], nullable - `talkable` boolean, nullable - `library_id` string, uuid, nullable - `connection_mode` 'shared' | 'per_caller', nullable - `confirm_credential_deletion` boolean - `confirm_shared_account_exposure` boolean ## Response `200` Successful Response - RegistrationOut: Read-side. Secret refs are accepted on writes but not echoed from connections. - `id` string, uuid, required - `definition_id` string, uuid, required - `definition_slug` string, nullable - `account_capture_source` 'gmail' | 'google-calendar', nullable - `library_id` string, uuid, nullable - `library_name` string, nullable - `my_role` string, nullable - `connection_mode` 'shared' | 'per_caller', required - `alias` string, required - `name` string, required - `transport` 'http' | 'sse' | 'stdio_bridge' | 'rest', required - `base_url` string, required - `display_icon_url` string, nullable - `display_icon_is_inferred` boolean - `auth_kind` 'none' | 'bearer' | 'api_key_header' | 'oauth2' | 'gcp_oidc' | 'gcp_service_account' | 'github_app', required - `auth_header_name` string, nullable, required - `auth_secret_ref` string, nullable - `description` string, nullable, required - `trusted` boolean, required - `enabled` boolean, required - `health_check_tool` string, nullable, required - `health_check_arguments` object - `health_check_declined` boolean - `health_check_decline_reason` string, nullable - `refresh_seconds` integer, required - `rate_limit_per_minute` integer, nullable, required - `request_max_bytes` integer, required - `response_max_bytes` integer, required - `talkable` boolean - `stdio_command` string, nullable - `stdio_args` unknown[] - unknown - `stdio_env` object - `rest_manifest` object, nullable - `rest_openapi_source_url` string, nullable - `icon_url` string, nullable - `icon_data_url` string, nullable - `secret_refs` object - `config_version` integer, nullable - `tool_overrides` object - `installed_template_version` integer, nullable - `latest_template_version` integer, nullable - `template_update_available` boolean - `published_as_template` boolean - `published_template_version` integer, nullable - `published_template_visibility` string, nullable - `oauth_resource_url` string, nullable - `oauth_authorization_url` string, nullable - `oauth_token_url` string, nullable - `oauth_client_id` string, nullable - `oauth_scopes` string, nullable - `oauth_pkce_enabled` boolean - `oauth_client_secret_set` boolean - `oauth_requires_manual_client` boolean - `oauth_token_expires_at` string, date-time, nullable - `oauth_connected` boolean - `oauth_granted_scopes` string, nullable - `oauth_principal` object, nullable - `account_identifiable` boolean, nullable - `permissions` ConnectionPermissionOut[], nullable - `key` string, required - `label` string, required - `permissions_summary` string, nullable - `provider_name` string, nullable - `provider_consent_url` string, nullable - `sign_in_note` string, nullable - `owned_by_viewer` boolean, nullable - `org_naming_mismatch_warning` string, nullable - `credential_connected` boolean - `credential_status` 'connected' | 'needs_reconnect' | 'admin_repair' | 'unreachable' | 'missing' - `viewer_removal` 'self' | 'other', nullable - `credential_last_auth_error` string, nullable - `credential_failure_code` string, nullable - `access_nature` string, nullable - `reauth_class` string, nullable - `server_name` string, nullable - `server_version` string, nullable - `protocol_version` string, nullable - `server_capabilities` object, nullable - `server_instructions` string, nullable - `last_test_success` boolean, nullable - `last_test_tool_count` integer, nullable - `last_test_error` string, nullable - `last_test_duration_ms` integer, nullable - `last_test_at` string, date-time, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/ce2c2ce318b1?raw)