> ## Documentation Index > Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update Settings > Update settings with partial changes. Accepts ``agent_settings_diff``, ``conversation_settings_diff``, ``misc_settings_diff``, and/or ``active_profile`` for incremental updates. Setting ``active_profile`` loads and applies that profile's LLM, same as ``POST /api/profiles/{name}/activate``, unless ``agent_settings_diff.llm`` is also given. The three ``*_settings_diff`` fields are deep-merged; nested objects merge recursively, and a ``null`` value **inside a nested map deletes that entry** — the "unset" primitive that lets a client remove a single map key without round-tripping the whole map. To remove one MCP server's header:: PATCH /api/settings {"agent_settings_diff": {"mcp_config": {"svc": {"headers": {"X-Old": null}}}}} A ``null`` on a top-level *field* (e.g. ``{"confirmation_mode": null}``) is **not** an unset — it flows to model validation as before, so it still fails loudly rather than silently resetting the field to its default. ``misc_settings_diff`` is deep-merged into the persisted ``misc_settings`` block. The agent-server treats ``misc_settings`` as opaque frontend-owned data: nested dicts are merged recursively, lists are replaced wholesale, and the contents are never read or validated server-side. Uses file locking to prevent concurrent updates from overwriting each other. Raises: HTTPException: 400 if the update payload contains invalid values. ## OpenAPI ````yaml /openapi/agent-sdk.json patch /api/settings openapi: 3.1.0 info: description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent title: OpenHands Agent Server version: 1.52.0 servers: [] security: [] paths: /api/settings: patch: tags: - Settings summary: Update Settings description: >- Update settings with partial changes. Accepts ``agent_settings_diff``, ``conversation_settings_diff``, ``misc_settings_diff``, and/or ``active_profile`` for incremental updates. Setting ``active_profile`` loads and applies that profile's LLM, same as ``POST /api/profiles/{name}/activate``, unless ``agent_settings_diff.llm`` is also given. The three ``*_settings_diff`` fields are deep-merged; nested objects merge recursively, and a ``null`` value **inside a nested map deletes that entry** — the "unset" primitive that lets a client remove a single map key without round-tripping the whole map. To remove one MCP server's header:: PATCH /api/settings {"agent_settings_diff": {"mcp_config": {"svc": {"headers": {"X-Old": null}}}}} A ``null`` on a top-level *field* (e.g. ``{"confirmation_mode": null}``) is **not** an unset — it flows to model validation as before, so it still fails loudly rather than silently resetting the field to its default. ``misc_settings_diff`` is deep-merged into the persisted ``misc_settings`` block. The agent-server treats ``misc_settings`` as opaque frontend-owned data: nested dicts are merged recursively, lists are replaced wholesale, and the contents are never read or validated server-side. Uses file locking to prevent concurrent updates from overwriting each other. Raises: HTTPException: 400 if the update payload contains invalid values. operationId: update_settings_api_settings_patch requestBody: content: application/json: schema: $ref: '#/components/schemas/SettingsUpdateRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SettingsResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - APIKeyHeader: [] components: schemas: SettingsUpdateRequest: description: |- Request model for PATCH /api/settings. Supports partial updates via diff objects that are deep-merged with existing settings. ``misc_settings_diff`` is deep-merged into the persisted ``misc_settings`` block with the same semantics as ``agent_settings_diff`` and ``conversation_settings_diff``: nested dicts merge recursively, and lists are replaced wholesale rather than merged. Because ``misc_settings`` is opaque to the agent-server, callers are responsible for the shape of what they store there. properties: active_agent_profile_id: anyOf: - pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ type: string - type: 'null' description: Stable id of the active AgentProfile to persist; null clears it. title: Active Agent Profile Id active_meta_profile: anyOf: - pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ type: string - type: 'null' description: Name of the active meta-profile to persist; null clears it. title: Active Meta Profile active_profile: anyOf: - pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ type: string - type: 'null' description: Name of the active LLM profile to persist; null clears it. title: Active Profile agent_settings_diff: anyOf: - additionalProperties: true properties: mcp_config: anyOf: - $ref: '#/components/schemas/MCPConfigPatch' - type: 'null' title: _AgentSettingsPatchContract type: object - type: 'null' title: Agent Settings Diff conversation_settings_diff: anyOf: - additionalProperties: true type: object - type: 'null' title: Conversation Settings Diff misc_settings_diff: anyOf: - additionalProperties: true type: object - type: 'null' title: Misc Settings Diff title: SettingsUpdateRequest type: object SettingsResponse: description: >- Response model for GET /api/settings. Contains the full settings payload including agent configuration, conversation settings, active LLM profile, miscellaneous frontend-owned settings, and a flag indicating whether an LLM API key is set. The ``agent_settings`` and ``conversation_settings`` fields are raw dicts because the server controls secret serialization via context. Use the typed accessor methods for validation: Example:: response = SettingsResponse.model_validate(api_response.json()) agent = response.get_agent_settings() # Returns AgentSettingsConfig conv = response.get_conversation_settings() # Returns ConversationSettings ``misc_settings`` is an opaque container for frontend-owned data that the agent-server persists but does not interpret — see the docstring of :class:`PersistedSettings.misc_settings`. properties: active_agent_profile_id: anyOf: - type: string - type: 'null' description: Stable id of the currently active AgentProfile, if one is set. title: Active Agent Profile Id active_meta_profile: anyOf: - type: string - type: 'null' description: Name of the currently active meta-profile, if one is selected. title: Active Meta Profile active_profile: anyOf: - type: string - type: 'null' description: Name of the currently active LLM profile, if one is selected. title: Active Profile agent_settings: additionalProperties: true properties: agent_kind: anyOf: - enum: - openhands - acp type: string - type: 'null' title: Agent Kind mcp_config: $ref: '#/components/schemas/MCPConfig' schema_version: anyOf: - minimum: 1 type: integer - type: 'null' title: Schema Version required: - mcp_config title: _AgentSettingsContract type: object conversation_settings: additionalProperties: true title: Conversation Settings type: object llm_api_key_is_set: title: Llm Api Key Is Set type: boolean misc_settings: additionalProperties: true title: Misc Settings type: object required: - agent_settings - conversation_settings - llm_api_key_is_set title: SettingsResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object MCPConfigPatch: additionalProperties: anyOf: - $ref: '#/components/schemas/MCPServerPatch' - type: 'null' description: Sparse MCP map patch; a null map value deletes that named server. title: MCPConfigPatch type: object MCPConfig: additionalProperties: $ref: '#/components/schemas/MCPServer-Output' description: Canonical persisted MCP server map keyed by stable server name. title: MCPConfig type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object MCPServerPatch: additionalProperties: false description: Sparse RFC 7386 merge patch for one persisted MCP server. properties: args: anyOf: - items: type: string type: array - type: 'null' title: Args auth: anyOf: - discriminator: mapping: api_key: '#/components/schemas/MCPApiKeyAuthCredential-Input' basic: '#/components/schemas/MCPBasicAuthCredential-Input' bearer: '#/components/schemas/MCPBearerAuthCredential-Input' header: '#/components/schemas/MCPHeaderAuthCredential-Input' none: '#/components/schemas/MCPNoneAuthCredential' oauth2: '#/components/schemas/MCPOAuthAuthCredential-Input' propertyName: strategy oneOf: - $ref: '#/components/schemas/MCPNoneAuthCredential' - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Input' - $ref: '#/components/schemas/MCPBearerAuthCredential-Input' - $ref: '#/components/schemas/MCPBasicAuthCredential-Input' - $ref: '#/components/schemas/MCPHeaderAuthCredential-Input' - $ref: '#/components/schemas/MCPOAuthAuthCredential-Input' - type: 'null' title: Auth command: anyOf: - minLength: 1 type: string - type: 'null' title: Command cwd: anyOf: - type: string - type: 'null' title: Cwd description: anyOf: - type: string - type: 'null' title: Description enabled: anyOf: - type: boolean - type: 'null' description: >- Switch the server off (false) or back on (true) without touching the rest of its configuration. A null clears the override, which restores the canonical default (enabled). title: Enabled env: anyOf: - additionalProperties: anyOf: - format: password type: string writeOnly: true - type: 'null' type: object - type: 'null' title: Env headers: anyOf: - additionalProperties: anyOf: - format: password type: string writeOnly: true - type: 'null' type: object - type: 'null' title: Headers icon: anyOf: - type: string - type: 'null' title: Icon keep_alive: anyOf: - type: boolean - type: 'null' title: Keep Alive sse_read_timeout: anyOf: - type: number - type: 'null' title: Sse Read Timeout timeout: anyOf: - type: number - type: 'null' title: Timeout transport: anyOf: - enum: - stdio - http - sse - streamable-http type: string - type: 'null' title: Transport url: anyOf: - minLength: 1 type: string - type: 'null' title: Url title: MCPServerPatch type: object MCPServer-Output: additionalProperties: false description: One MCP server in the settings DataModel. properties: args: anyOf: - items: type: string type: array - type: 'null' title: Args auth: anyOf: - discriminator: mapping: api_key: '#/components/schemas/MCPApiKeyAuthCredential-Output' basic: '#/components/schemas/MCPBasicAuthCredential-Output' bearer: '#/components/schemas/MCPBearerAuthCredential-Output' header: '#/components/schemas/MCPHeaderAuthCredential-Output' none: '#/components/schemas/MCPNoneAuthCredential' oauth2: '#/components/schemas/MCPOAuthAuthCredential-Output' propertyName: strategy oneOf: - $ref: '#/components/schemas/MCPNoneAuthCredential' - $ref: '#/components/schemas/MCPApiKeyAuthCredential-Output' - $ref: '#/components/schemas/MCPBearerAuthCredential-Output' - $ref: '#/components/schemas/MCPBasicAuthCredential-Output' - $ref: '#/components/schemas/MCPHeaderAuthCredential-Output' - $ref: '#/components/schemas/MCPOAuthAuthCredential-Output' - type: 'null' title: Auth command: anyOf: - minLength: 1 type: string - type: 'null' title: Command cwd: anyOf: - type: string - type: 'null' title: Cwd description: anyOf: - type: string - type: 'null' title: Description enabled: default: true description: >- Whether this server is exposed to the agent. A disabled server stays fully configured -- including its secrets -- but is skipped when MCP tools are created and when servers are forwarded to an ACP subprocess. title: Enabled type: boolean env: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Env headers: anyOf: - additionalProperties: anyOf: - type: string - type: 'null' type: object - type: 'null' title: Headers icon: anyOf: - type: string - type: 'null' title: Icon keep_alive: anyOf: - type: boolean - type: 'null' title: Keep Alive sse_read_timeout: anyOf: - type: number - type: 'null' title: Sse Read Timeout timeout: anyOf: - type: number - type: 'null' title: Timeout transport: anyOf: - enum: - stdio - http - sse - streamable-http type: string - type: 'null' title: Transport url: anyOf: - minLength: 1 type: string - type: 'null' title: Url title: MCPServer type: object MCPApiKeyAuthCredential-Input: properties: header_name: anyOf: - type: string - type: 'null' title: Header Name strategy: const: api_key title: Strategy type: string value: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Value required: - strategy title: MCPApiKeyAuthCredential type: object MCPBasicAuthCredential-Input: properties: password: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Password strategy: const: basic title: Strategy type: string username: title: Username type: string required: - strategy - username title: MCPBasicAuthCredential type: object MCPBearerAuthCredential-Input: properties: strategy: const: bearer title: Strategy type: string value: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Value required: - strategy title: MCPBearerAuthCredential type: object MCPHeaderAuthCredential-Input: properties: headers: additionalProperties: format: password type: string writeOnly: true title: Headers type: object strategy: const: header title: Strategy type: string required: - strategy title: MCPHeaderAuthCredential type: object MCPNoneAuthCredential: properties: strategy: const: none title: Strategy type: string required: - strategy title: MCPNoneAuthCredential type: object MCPOAuthAuthCredential-Input: properties: authentication: anyOf: - $ref: '#/components/schemas/MCPOAuthAuthentication-Input' - type: 'null' state: anyOf: - $ref: '#/components/schemas/MCPOAuthState-Input' - type: 'null' strategy: const: oauth2 title: Strategy type: string required: - strategy title: MCPOAuthAuthCredential type: object MCPApiKeyAuthCredential-Output: properties: header_name: anyOf: - type: string - type: 'null' title: Header Name strategy: const: api_key title: Strategy type: string value: anyOf: - type: string - type: 'null' title: Value required: - strategy title: MCPApiKeyAuthCredential type: object MCPBasicAuthCredential-Output: properties: password: anyOf: - type: string - type: 'null' title: Password strategy: const: basic title: Strategy type: string username: title: Username type: string required: - strategy - username title: MCPBasicAuthCredential type: object MCPBearerAuthCredential-Output: properties: strategy: const: bearer title: Strategy type: string value: anyOf: - type: string - type: 'null' title: Value required: - strategy title: MCPBearerAuthCredential type: object MCPHeaderAuthCredential-Output: properties: headers: additionalProperties: anyOf: - type: string - type: 'null' title: Headers type: object strategy: const: header title: Strategy type: string required: - strategy title: MCPHeaderAuthCredential type: object MCPOAuthAuthCredential-Output: properties: authentication: anyOf: - $ref: '#/components/schemas/MCPOAuthAuthentication-Output' - type: 'null' state: anyOf: - $ref: '#/components/schemas/MCPOAuthState-Output' - type: 'null' strategy: const: oauth2 title: Strategy type: string required: - strategy title: MCPOAuthAuthCredential type: object MCPOAuthAuthentication-Input: additionalProperties: false properties: additional_client_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Additional Client Metadata client_auth_method: anyOf: - enum: - none - client_secret_post - client_secret_basic - private_key_jwt type: string - type: 'null' title: Client Auth Method client_id: anyOf: - type: string - type: 'null' title: Client Id client_metadata_url: anyOf: - type: string - type: 'null' title: Client Metadata Url client_name: anyOf: - type: string - type: 'null' title: Client Name client_secret: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Client Secret scopes: anyOf: - type: string - items: type: string type: array - type: 'null' title: Scopes type: const: oauth title: Type type: string required: - type title: MCPOAuthAuthentication type: object MCPOAuthState-Input: properties: client_info: anyOf: - $ref: '#/components/schemas/MCPOAuthClientInfoState-Input' - type: 'null' token_expires_at: anyOf: - type: number - type: 'null' title: Token Expires At tokens: anyOf: - $ref: '#/components/schemas/MCPOAuthTokenState-Input' - type: 'null' title: MCPOAuthState type: object MCPOAuthAuthentication-Output: additionalProperties: false properties: additional_client_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Additional Client Metadata client_auth_method: anyOf: - enum: - none - client_secret_post - client_secret_basic - private_key_jwt type: string - type: 'null' title: Client Auth Method client_id: anyOf: - type: string - type: 'null' title: Client Id client_metadata_url: anyOf: - type: string - type: 'null' title: Client Metadata Url client_name: anyOf: - type: string - type: 'null' title: Client Name client_secret: anyOf: - type: string - type: 'null' title: Client Secret scopes: anyOf: - type: string - items: type: string type: array - type: 'null' title: Scopes type: const: oauth title: Type type: string required: - type title: MCPOAuthAuthentication type: object MCPOAuthState-Output: properties: client_info: anyOf: - $ref: '#/components/schemas/MCPOAuthClientInfoState-Output' - type: 'null' token_expires_at: anyOf: - type: number - type: 'null' title: Token Expires At tokens: anyOf: - $ref: '#/components/schemas/MCPOAuthTokenState-Output' - type: 'null' title: MCPOAuthState type: object MCPOAuthClientInfoState-Input: additionalProperties: true properties: client_secret: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Client Secret title: MCPOAuthClientInfoState type: object MCPOAuthTokenState-Input: additionalProperties: true properties: access_token: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Access Token refresh_token: anyOf: - format: password type: string writeOnly: true - type: 'null' title: Refresh Token title: MCPOAuthTokenState type: object MCPOAuthClientInfoState-Output: additionalProperties: true properties: client_secret: anyOf: - type: string - type: 'null' title: Client Secret title: MCPOAuthClientInfoState type: object MCPOAuthTokenState-Output: additionalProperties: true properties: access_token: anyOf: - type: string - type: 'null' title: Access Token refresh_token: anyOf: - type: string - type: 'null' title: Refresh Token title: MCPOAuthTokenState type: object securitySchemes: APIKeyHeader: in: header name: X-Session-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.