> ## Documentation Index > Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt > Use this file to discover all available pages before exploring further. # Save Profile > Save an LLM configuration as a named profile. If ``request.llm`` is supplied, it is saved as the profile's config. Otherwise the current ``agent_settings.llm`` is snapshotted. Existing profiles with the same name are overwritten. Runs inside a per-user lock to prevent lost updates between concurrent profile writes. Returns 409 if the user is already at the profile cap (:data:`MAX_PROFILES_PER_USER`). ## OpenAPI ````yaml /openapi/openhands-cloud.json post /api/v1/settings/profiles/{name} openapi: 3.1.0 info: title: OpenHands description: 'OpenHands: Code Less, Make More' version: 0.0.1 servers: [] security: [] paths: /api/v1/settings/profiles/{name}: post: tags: - Settings summary: Save Profile description: |- Save an LLM configuration as a named profile. If ``request.llm`` is supplied, it is saved as the profile's config. Otherwise the current ``agent_settings.llm`` is snapshotted. Existing profiles with the same name are overwritten. Runs inside a per-user lock to prevent lost updates between concurrent profile writes. Returns 409 if the user is already at the profile cap (:data:`MAX_PROFILES_PER_USER`). operationId: save_profile_api_v1_settings_profiles__name__post parameters: - name: name in: path required: true schema: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9._-]{1,64}$ title: Name requestBody: content: application/json: schema: anyOf: - $ref: >- #/components/schemas/openhands__app_server__settings__settings_router__SaveProfileRequest - type: 'null' title: Request responses: '201': description: Successful Response content: application/json: schema: $ref: >- #/components/schemas/openhands__app_server__settings__settings_router__ProfileMutationResponse '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: openhands__app_server__settings__settings_router__SaveProfileRequest: properties: include_secrets: type: boolean title: Include Secrets default: true llm: anyOf: - $ref: '#/components/schemas/StrictLLM' - type: 'null' preserve_existing_api_key: type: boolean title: Preserve Existing Api Key default: false type: object title: SaveProfileRequest description: >- Request body for saving a profile. If ``llm`` is provided, it is used as the profile config; otherwise the current ``agent_settings.llm`` is saved. The ``llm`` field is typed as :class:`StrictLLM`, which forbids unknown keys — so a typo like ``{"llm": {"custom_header": "x"}}`` returns 422 instead of being silently dropped. **Security note:** when ``llm.api_key`` is included in the request body, it is transmitted in plaintext over the wire and present in any request log or error trace that captures request bodies. ``SecretStr`` masks it in Pydantic reprs, but callers and operators should still avoid logging raw request bodies on this endpoint. openhands__app_server__settings__settings_router__ProfileMutationResponse: properties: name: type: string title: Name message: type: string title: Message type: object required: - name - message title: ProfileMutationResponse description: Response body for save/delete operations. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError StrictLLM: properties: model: type: string title: Model description: Model name. default: gpt-5.5 openhands_settings: depends_on: [] prominence: critical api_key: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Api Key description: API key. openhands_settings: depends_on: [] label: API Key prominence: critical auth_type: type: string enum: - api_key - subscription title: Auth Type description: Authentication mode for the LLM. default: api_key openhands_settings: depends_on: [] label: Authentication prominence: critical subscription_vendor: anyOf: - type: string const: openai - type: 'null' title: Subscription Vendor description: Subscription provider for subscription-backed LLM access. openhands_settings: depends_on: - auth_type label: Subscription provider prominence: critical base_url: anyOf: - type: string - type: 'null' title: Base Url description: Custom base URL. openhands_settings: depends_on: [] prominence: major api_version: anyOf: - type: string - type: 'null' title: Api Version description: API version (e.g., Azure). openhands_settings: depends_on: [] prominence: minor aws_access_key_id: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Aws Access Key Id openhands_settings: depends_on: [] prominence: minor aws_secret_access_key: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Aws Secret Access Key openhands_settings: depends_on: [] prominence: minor aws_session_token: anyOf: - type: string - type: string format: password writeOnly: true - type: 'null' title: Aws Session Token openhands_settings: depends_on: [] prominence: minor aws_region_name: anyOf: - type: string - type: 'null' title: Aws Region Name openhands_settings: depends_on: [] prominence: minor aws_profile_name: anyOf: - type: string - type: 'null' title: Aws Profile Name openhands_settings: depends_on: [] prominence: minor aws_role_name: anyOf: - type: string - type: 'null' title: Aws Role Name openhands_settings: depends_on: [] prominence: minor aws_session_name: anyOf: - type: string - type: 'null' title: Aws Session Name openhands_settings: depends_on: [] prominence: minor aws_bedrock_runtime_endpoint: anyOf: - type: string - type: 'null' title: Aws Bedrock Runtime Endpoint openhands_settings: depends_on: [] prominence: minor openrouter_site_url: type: string title: Openrouter Site Url default: https://docs.all-hands.dev/ openhands_settings: depends_on: [] prominence: minor openrouter_app_name: type: string title: Openrouter App Name default: OpenHands openhands_settings: depends_on: [] prominence: minor num_retries: type: integer minimum: 0 title: Num Retries default: 5 openhands_settings: depends_on: [] prominence: minor retry_multiplier: type: number minimum: 0 title: Retry Multiplier default: 8 openhands_settings: depends_on: [] prominence: minor retry_min_wait: type: integer minimum: 0 title: Retry Min Wait default: 8 openhands_settings: depends_on: [] prominence: minor retry_max_wait: type: integer minimum: 0 title: Retry Max Wait default: 64 openhands_settings: depends_on: [] prominence: minor timeout: anyOf: - type: integer minimum: 0 - type: 'null' title: Timeout description: >- HTTP timeout in seconds. Default is 300s (5 minutes). Set to None to disable timeout (not recommended for production). default: 300 openhands_settings: depends_on: [] prominence: minor max_message_chars: type: integer minimum: 1 title: Max Message Chars description: Approx max chars in each event/content sent to the LLM. default: 30000 openhands_settings: depends_on: [] prominence: minor temperature: anyOf: - type: number minimum: 0 - type: 'null' title: Temperature description: >- Sampling temperature for response generation. Defaults to None (uses provider default temperature). Set to 0.0 for deterministic outputs, or higher values (0.7-1.0) for more creative responses. openhands_settings: depends_on: [] prominence: minor top_p: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Top P description: >- Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs. openhands_settings: depends_on: [] prominence: minor top_k: anyOf: - type: number minimum: 0 - type: 'null' title: Top K openhands_settings: depends_on: [] prominence: minor max_input_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Input Tokens description: >- The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4). openhands_settings: depends_on: [] prominence: minor max_output_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Output Tokens description: The maximum number of output tokens. This is sent to the LLM. openhands_settings: depends_on: [] prominence: minor model_canonical_name: anyOf: - type: string - type: 'null' title: Model Canonical Name description: >- Optional canonical model name for feature registry lookups. The OpenHands SDK maintains a model feature registry that maps model names to capabilities (e.g., vision support, prompt caching, responses API support). When using proxied or aliased model identifiers, set this field to the canonical model name (e.g., 'openai/gpt-4o') to ensure correct capability detection. If not provided, the 'model' field will be used for capability lookups. openhands_settings: depends_on: [] prominence: minor api_mode: type: string enum: - auto - chat - responses title: Api Mode description: >- LLM API endpoint mode. 'auto' resolves from model metadata and SDK fallbacks; use 'chat' or 'responses' to override endpoint selection for proxy aliases and newly released models. default: auto openhands_settings: depends_on: [] prominence: minor capability_overrides: additionalProperties: anyOf: - type: boolean - type: string type: object title: Capability Overrides description: >- Explicit model capability overrides. Supported keys include supports_reasoning_effort, thinking_mode (adaptive, manual, none, or unknown), supports_sampling_params, supports_prompt_cache, supports_stop_words, supports_responses_api, supports_vision, and supports_prompt_cache_retention. Overrides take precedence over LiteLLM metadata and SDK fallbacks. openhands_settings: depends_on: [] prominence: minor extra_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Headers description: Optional HTTP headers to forward to LiteLLM requests. openhands_settings: depends_on: [] prominence: minor input_cost_per_token: anyOf: - type: number minimum: 0 - type: 'null' title: Input Cost Per Token description: The cost per input token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor output_cost_per_token: anyOf: - type: number minimum: 0 - type: 'null' title: Output Cost Per Token description: The cost per output token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor ollama_base_url: anyOf: - type: string - type: 'null' title: Ollama Base Url openhands_settings: depends_on: [] prominence: minor stream: type: boolean title: Stream description: >- Enable streaming responses from the LLM. When enabled, the provided `on_token` callback in .completions and .responses will be invoked for each chunk of tokens. default: false openhands_settings: depends_on: [] prominence: minor drop_params: type: boolean title: Drop Params default: true openhands_settings: depends_on: [] prominence: minor modify_params: type: boolean title: Modify Params description: >- Modify params allows litellm to do transformations like adding a default message, when a message is empty. default: true openhands_settings: depends_on: [] prominence: minor disable_vision: anyOf: - type: boolean - type: 'null' title: Disable Vision description: >- If model is vision capable, this option allows to disable image processing (useful for cost reduction). openhands_settings: depends_on: [] prominence: minor disable_stop_word: anyOf: - type: boolean - type: 'null' title: Disable Stop Word description: Disable using of stop word. default: false openhands_settings: depends_on: [] prominence: minor caching_prompt: type: boolean title: Caching Prompt description: Enable caching of prompts. default: true openhands_settings: depends_on: [] prominence: minor log_completions: type: boolean title: Log Completions description: Enable logging of completions. default: false openhands_settings: depends_on: [] prominence: minor log_completions_folder: type: string title: Log Completions Folder description: >- The folder to log LLM completions to. Required if log_completions is True. default: logs/completions openhands_settings: depends_on: [] prominence: minor custom_tokenizer: anyOf: - type: string - type: 'null' title: Custom Tokenizer description: A custom tokenizer to use for token counting. openhands_settings: depends_on: [] prominence: minor native_tool_calling: type: boolean title: Native Tool Calling description: Whether to use native tool calling. default: true openhands_settings: depends_on: [] prominence: minor force_string_serializer: anyOf: - type: boolean - type: 'null' title: Force String Serializer description: >- Force using string content serializer when sending to LLM API. If None (default), auto-detect based on model. Useful for providers that do not support list content, like HuggingFace and Groq. openhands_settings: depends_on: [] prominence: minor inline_image_urls: anyOf: - type: boolean - type: 'null' title: Inline Image Urls description: >- If True, fetch any http(s) image URL in outgoing messages and inline it as a base64 ``data:`` URL before sending. If None (default), auto-detect based on model (some APIs such as Moonshot's public Kimi endpoint reject URL-formatted images and require base64). Set this explicitly when the model is reached through a proxy alias that hides the underlying provider (e.g. ``litellm_proxy/``). Note: inlining only runs when ``vision_is_active()`` is True, so the alias must still be recognised as vision-capable by the SDK feature registry or proxy model metadata. openhands_settings: depends_on: [] prominence: minor reasoning_effort: anyOf: - type: string enum: - low - medium - high - xhigh - none - type: 'null' title: Reasoning Effort description: >- Provider-neutral reasoning effort. Common values include 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', and 'max'. The SDK accepts future provider values and lets LiteLLM translate them. default: high openhands_settings: depends_on: [] prominence: minor reasoning_summary: anyOf: - type: string enum: - auto - concise - detailed - type: 'null' title: Reasoning Summary description: >- The level of detail for reasoning summaries. This is a string that can be one of 'auto', 'concise', or 'detailed'. Requires verified OpenAI organization. Only sent when explicitly set. openhands_settings: depends_on: [] prominence: minor enable_encrypted_reasoning: type: boolean title: Enable Encrypted Reasoning description: >- If True, ask for ['reasoning.encrypted_content'] in Responses API include. default: true openhands_settings: depends_on: [] prominence: minor prompt_cache_retention: anyOf: - type: string - type: 'null' title: Prompt Cache Retention description: >- Retention policy for prompt cache. Only sent for supported models (GPT-5+ and GPT-4.1, excluding Azure deployments); explicitly stripped for all others. default: 24h openhands_settings: depends_on: [] prominence: minor extended_thinking_budget: anyOf: - type: integer - type: 'null' title: Extended Thinking Budget description: >- Legacy token budget for models confirmed to use manual Anthropic extended thinking. Ignored for adaptive-thinking models. Prefer reasoning_effort for new integrations. default: 200000 openhands_settings: depends_on: [] prominence: minor seed: anyOf: - type: integer - type: 'null' title: Seed description: The seed to use for random number generation. openhands_settings: depends_on: [] prominence: minor usage_id: type: string title: Usage Id description: >- Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking. default: default openhands_settings: depends_on: [] prominence: minor litellm_extra_body: additionalProperties: true type: object title: Litellm Extra Body description: >- Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference endpoints that need additional parameters for configuration, routing, or advanced features. NOTE: Not all LLM providers support extra_body parameters. Some providers (e.g., OpenAI) may reject requests with unrecognized options. This is commonly supported by: - LiteLLM proxy servers (routing metadata, tracing) - vLLM endpoints (return_token_ids, etc.) - Custom inference clusters Examples: - Proxy routing: {'trace_version': '1.0.0', 'tags': ['agent:my-agent']} - vLLM features: {'return_token_ids': True} openhands_settings: depends_on: [] prominence: minor fallback_strategy: anyOf: - $ref: '#/components/schemas/FallbackStrategy' - type: 'null' description: >- Optional fallback strategy for trying alternate LLMs on transient failure. Construct with FallbackStrategy(fallback_llms=[...]).Excluded from serialization; must be reconfigured after load. additionalProperties: false type: object title: StrictLLM description: |- LLM variant that rejects unknown fields. The base ``LLM`` model has ``extra='ignore'``, so typos and renamed keys silently disappear. For API input we want to fail loud, otherwise users can POST ``{"llm": {"custom_header": "x"}}`` and get a 201 with the field quietly dropped. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError FallbackStrategy: properties: fallback_llms: items: type: string type: array title: Fallback Llms description: Ordered list of LLM profile names to try on transient failure. profile_store_dir: anyOf: - type: string - type: string format: path - type: 'null' title: Profile Store Dir description: >- Path to directory containing profiles. If not specified, defaults to `.openhands/profiles`. type: object required: - fallback_llms title: FallbackStrategy description: |- Encapsulates fallback behavior for LLM calls. When the primary LLM fails with a transient error (after retries), this strategy tries alternate LLMs loaded from LLMProfileStore profiles. Fallback is per-call: each new request starts with the primary model. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-Access-Token ````