> ## Documentation Index > Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt > Use this file to discover all available pages before exploring further. # Update agent profile > Changes an agent profile by merge patch, answering the profile: an absent field keeps its value. Use this tool when you need to: - Rename a profile, or change its model and reasoning effort - Change or remove what a profile pins its tasks to run on, or its fallback for a plan whose window is spent Examples: - PATCH /agent-profiles/{profileID} {"model": "claude-sonnet-5-5", "reasoning_effort": null} - PATCH /agent-profiles/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21 {"runs_on": {"runs_on": "stored", "connection_id": "0b9d3e57-2c1a-4f6e-8d7b-5a4c3e2f1d09"}, "fallback": {"mode": "any_usable", "then": {"runs_on": "aether"}}} Hints: - profileID is the profile's uuid. Fields: name (1 to 100 characters, stored trimmed, 400 when blank once trimmed), agent_type, model, reasoning_effort (null clears it to the model's default), runs_on and fallback. The schema answers 422 for a patch naming no field, a value outside its type or enum, an unknown field, or a profileID that is not a uuid. - The model and effort are checked together with the profile's values of those the patch omits (400 for a pair the catalog does not pair with the profile's agent), and written only while the profile still holds the ones they were checked against (409 agent_profile_changed otherwise); naming them as they are writes neither. - A profile keeps its agent: agent_type is absent or names the profile's own; another is refused with 409 agent_profile_harness_fixed, or with 400 when the catalog does not pair it with the model and effort. - runs_on absent, or naming the connection the profile already pins, keeps the stored pin, whoever holds it; default pins nobody; aether, Aether inference (Claude Code and Codex only); stored, a connection the caller holds that works with the profile's agent. - fallback belongs to a profile that pins a plan, whose window can be spent: none stops, named takes the connection or Aether inference, and any_usable tries the pinned connection holder's held connections before its optional then hop. Only that holder writes a fallback other than none; anyone else omits it, sends the saved one back, or sets none. - Beside a kept pin, omitting fallback keeps it; sending the saved policy back is the same keep, and is possible only while its hop is still connected, because a read omits the connection_id a named write requires: omit fallback to keep a policy whose hop was disconnected. - A patch that replaces the pin brings its own fallback: omitted while the saved fallback is not none, it is refused with 409 fallback_required_with_pin; omitted while it is none, it stays none. Unpinning (runs_on default) clears the fallback. - Refused with 409 for a name another profile has. The pin is refused with 404 connection_not_held for a connection the caller does not hold (the message names the agent to connect one for), 409 connection_harness_mismatch for a connection of another agent, 409 connection_agent_only for the caller's agent's own ChatGPT login, 409 aether_inference_unserved for Aether inference on OpenCode, and 409 aether_inference_unavailable where this deployment serves no Aether inference. - A fallback is refused with 409 fallback_requires_pin beside anything but a plan pin, 404 connection_not_held when a non-holder writes one or the named connection is not the holder's for the agent, 409 fallback_is_own_connection when the named connection is the pin itself, 409 agent_profile_changed when the pin a kept-pin fallback write was checked against changed before it landed, and the pin's harness refusals (409 connection_harness_mismatch, connection_agent_only, aether_inference_unserved, aether_inference_unavailable) worded for the fallback. - Use getAgentProfile instead to read the profile before changing it, and deleteAgentProfile to remove it. - Restricted to an owner or admin of the profile's organization, checked after the body is validated: a member is refused with 403 control_forbidden, a viewer or billing member with 403 org_role_insufficient, a suspended organization with 403 org_suspended, a profile the caller cannot see with 404, and an agent host's grant with 403 agent_host_route_not_allowed; 503 when the membership check is unavailable. ## OpenAPI ````yaml api-reference/openapi.json PATCH /agent-profiles/{profileID} openapi: 3.1.0 info: title: Aether API version: 0.1.0 servers: - url: https://api.runaether.dev security: - bearerAuth: [] paths: /agent-profiles/{profileID}: patch: tags: - agent-profiles summary: Update agent profile description: >- Changes an agent profile by merge patch, answering the profile: an absent field keeps its value. Use this tool when you need to: - Rename a profile, or change its model and reasoning effort - Change or remove what a profile pins its tasks to run on, or its fallback for a plan whose window is spent Examples: - PATCH /agent-profiles/{profileID} {"model": "claude-sonnet-5-5", "reasoning_effort": null} - PATCH /agent-profiles/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21 {"runs_on": {"runs_on": "stored", "connection_id": "0b9d3e57-2c1a-4f6e-8d7b-5a4c3e2f1d09"}, "fallback": {"mode": "any_usable", "then": {"runs_on": "aether"}}} Hints: - profileID is the profile's uuid. Fields: name (1 to 100 characters, stored trimmed, 400 when blank once trimmed), agent_type, model, reasoning_effort (null clears it to the model's default), runs_on and fallback. The schema answers 422 for a patch naming no field, a value outside its type or enum, an unknown field, or a profileID that is not a uuid. - The model and effort are checked together with the profile's values of those the patch omits (400 for a pair the catalog does not pair with the profile's agent), and written only while the profile still holds the ones they were checked against (409 agent_profile_changed otherwise); naming them as they are writes neither. - A profile keeps its agent: agent_type is absent or names the profile's own; another is refused with 409 agent_profile_harness_fixed, or with 400 when the catalog does not pair it with the model and effort. - runs_on absent, or naming the connection the profile already pins, keeps the stored pin, whoever holds it; default pins nobody; aether, Aether inference (Claude Code and Codex only); stored, a connection the caller holds that works with the profile's agent. - fallback belongs to a profile that pins a plan, whose window can be spent: none stops, named takes the connection or Aether inference, and any_usable tries the pinned connection holder's held connections before its optional then hop. Only that holder writes a fallback other than none; anyone else omits it, sends the saved one back, or sets none. - Beside a kept pin, omitting fallback keeps it; sending the saved policy back is the same keep, and is possible only while its hop is still connected, because a read omits the connection_id a named write requires: omit fallback to keep a policy whose hop was disconnected. - A patch that replaces the pin brings its own fallback: omitted while the saved fallback is not none, it is refused with 409 fallback_required_with_pin; omitted while it is none, it stays none. Unpinning (runs_on default) clears the fallback. - Refused with 409 for a name another profile has. The pin is refused with 404 connection_not_held for a connection the caller does not hold (the message names the agent to connect one for), 409 connection_harness_mismatch for a connection of another agent, 409 connection_agent_only for the caller's agent's own ChatGPT login, 409 aether_inference_unserved for Aether inference on OpenCode, and 409 aether_inference_unavailable where this deployment serves no Aether inference. - A fallback is refused with 409 fallback_requires_pin beside anything but a plan pin, 404 connection_not_held when a non-holder writes one or the named connection is not the holder's for the agent, 409 fallback_is_own_connection when the named connection is the pin itself, 409 agent_profile_changed when the pin a kept-pin fallback write was checked against changed before it landed, and the pin's harness refusals (409 connection_harness_mismatch, connection_agent_only, aether_inference_unserved, aether_inference_unavailable) worded for the fallback. - Use getAgentProfile instead to read the profile before changing it, and deleteAgentProfile to remove it. - Restricted to an owner or admin of the profile's organization, checked after the body is validated: a member is refused with 403 control_forbidden, a viewer or billing member with 403 org_role_insufficient, a suspended organization with 403 org_suspended, a profile the caller cannot see with 404, and an agent host's grant with 403 agent_host_route_not_allowed; 503 when the membership check is unavailable. operationId: patchAgentProfile parameters: - in: path name: profileID required: true schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchAgentProfileRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentProfile' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/AgentProfilesErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/AgentProfilesErrorResponse' description: Unauthorized '403': content: application/json: schema: anyOf: - $ref: '#/components/schemas/OrgAuthorizationErrorResponse' - $ref: '#/components/schemas/ControlForbiddenErrorResponse' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/AgentProfilesErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/AgentProfilesErrorResponse' description: Conflict '422': content: application/json: schema: $ref: '#/components/schemas/AgentProfilesErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/AgentProfilesErrorResponse' description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/AgentProfilesErrorResponse' description: Service Unavailable components: schemas: PatchAgentProfileRequest: additionalProperties: false minProperties: 1 properties: agent_type: $ref: '#/components/schemas/AgentType' fallback: $ref: '#/components/schemas/ConnectionFallbackWrite' model: minLength: 1 type: string name: maxLength: 100 minLength: 1 type: string reasoning_effort: enum: - ultra - max - xhigh - high - medium - low - ultrathink - ultracode type: - string - 'null' runs_on: description: >- What the profile's tasks run on: absent keeps the profile's pin; default pins nobody, so each task runs on its creator's default; aether, Aether inference (Claude Code and Codex only); stored, a connection by id, which you hold or the profile already pins, that works with the profile's agent. discriminator: mapping: aether: '#/components/schemas/AgentProfilePinAether' default: '#/components/schemas/AgentProfilePinDefault' stored: '#/components/schemas/AgentProfilePinStored' propertyName: runs_on oneOf: - $ref: '#/components/schemas/AgentProfilePinDefault' - $ref: '#/components/schemas/AgentProfilePinAether' - $ref: '#/components/schemas/AgentProfilePinStored' type: object AgentProfile: additionalProperties: false properties: agent_type: $ref: '#/components/schemas/AgentType' created_at: format: date-time type: string fallback: $ref: '#/components/schemas/ConnectionFallback' id: format: uuid type: string model: minLength: 1 type: string name: maxLength: 100 minLength: 1 type: string reasoning_effort: enum: - ultra - max - xhigh - high - medium - low - ultrathink - ultracode type: - string - 'null' runs_on: description: >- What the profile's tasks run on: default pins nobody, so each task runs on its creator's default; aether, Aether inference; stored, the connection it pins. discriminator: mapping: aether: '#/components/schemas/AgentProfileRunsOnAether' default: '#/components/schemas/AgentProfileRunsOnDefault' stored: '#/components/schemas/AgentProfileRunsOnStored' propertyName: runs_on oneOf: - $ref: '#/components/schemas/AgentProfileRunsOnDefault' - $ref: '#/components/schemas/AgentProfileRunsOnAether' - $ref: '#/components/schemas/AgentProfileRunsOnStored' updated_at: format: date-time type: string required: - id - name - agent_type - model - reasoning_effort - runs_on - fallback - created_at - updated_at type: object AgentProfilesErrorResponse: additionalProperties: false properties: code: enum: - account_deleting - aether_inference_unavailable - aether_inference_unserved - agent_connector_not_found - agent_default_project_archived - agent_profile_changed - agent_profile_harness_fixed - bad_gateway - bad_request - conflict - connection_agent_only - connection_harness_mismatch - connection_not_held - control_forbidden - default_skill_required - fallback_is_own_connection - fallback_required_with_pin - fallback_requires_pin - forbidden - gateway_timeout - gone - integration_auth_unexpected - integration_not_in_directory - integration_shape_changed - internal_error - mcp_connection_github_not_connected - mcp_connection_oauth_not_accepted - mcp_connection_org_not_offered - mcp_connection_secret_invalid - mcp_connection_server_changed - mcp_connection_static_secret_not_accepted - mcp_credential_policy_not_applicable - mcp_credential_policy_org_unavailable - mcp_credential_policy_required - mcp_oauth_app_auth_method_unsupported - mcp_oauth_app_invalid - mcp_oauth_app_issuer_invalid - mcp_oauth_app_required - mcp_oauth_not_advertised - mcp_oauth_pkce_unsupported - mcp_oauth_registration_failed - mcp_repo_config_invalid - mcp_server_address_refused - mcp_server_aether_managed - mcp_server_api_key_not_applicable - mcp_server_args_invalid - mcp_server_auth_discovery_failed - mcp_server_auth_unsupported - mcp_server_directory_managed - mcp_server_directory_moved - mcp_server_display_name_invalid - mcp_server_env_invalid - mcp_server_headers_invalid - mcp_server_key_invalid - mcp_server_key_reserved - mcp_server_key_taken - mcp_server_kind_change_refused - mcp_server_not_from_directory - mcp_server_not_mcp - mcp_server_package_invalid - mcp_server_plugin_bundled - mcp_server_plugin_off - mcp_server_response_too_large - mcp_server_return_to_invalid - mcp_server_runtime_invalid - mcp_server_switched_off - mcp_server_unreachable - mcp_server_url_invalid - mcp_server_version_unpinned - method_not_allowed - not_acceptable - not_found - not_implemented - org_role_insufficient - org_suspended - payment_required - plugin_moved - plugin_name_taken - plugin_request_invalid - plugin_server_key_reserved - plugin_server_key_taken - plugin_server_probe_failed - plugin_server_required - plugin_skill_invalid - plugin_source_address_refused - plugin_source_empty - plugin_source_invalid - plugin_source_not_found - plugin_source_not_public - plugin_source_too_large - plugin_source_unreachable - plugin_source_unsupported - plugin_switched_off - plugin_undeliverable - precondition_failed - rate_limited - request_canceled - request_timeout - request_too_large - service_unavailable - skill_slug_reserved - unauthenticated - unsupported_media_type - validation_failed minLength: 1 type: string error: minLength: 1 type: string errors: items: $ref: '#/components/schemas/ErrorDetail' type: array required: - error - code type: object OrgAuthorizationErrorResponse: additionalProperties: false properties: code: enum: - org_membership_required - org_role_insufficient - org_suspended - account_deleting - agent_host_route_not_allowed - credential_kind_not_admitted type: string error: minLength: 1 type: string required: - error - code type: object ControlForbiddenErrorResponse: additionalProperties: false properties: code: enum: - control_forbidden type: string error: minLength: 1 type: string required: - error - code type: object AgentType: description: >- The agent harness that runs a task, a profile or a connection: claude-code is Claude Code, codex is Codex, opencode is OpenCode. enum: - codex - claude-code - opencode type: string ConnectionFallbackWrite: description: >- What a task continues on when its plan's window is spent: none stops it; named takes the connection or Aether inference; any_usable takes the first held connection the window does not block, then its optional named hop. oneOf: - $ref: '#/components/schemas/ConnectionFallbackNone' - $ref: '#/components/schemas/ConnectionFallbackWriteNamedAether' - $ref: '#/components/schemas/ConnectionFallbackWriteNamedStored' - $ref: '#/components/schemas/ConnectionFallbackWriteAnyUsable' AgentProfilePinAether: additionalProperties: false properties: runs_on: description: >- Aether inference, paid from your organization's balance: Claude Code and Codex only. enum: - aether type: string required: - runs_on type: object AgentProfilePinDefault: additionalProperties: false properties: runs_on: description: 'No pin: each task runs on its creator''s default.' enum: - default type: string required: - runs_on type: object AgentProfilePinStored: additionalProperties: false properties: connection_id: description: A connection you hold that works with the harness. format: uuid type: string runs_on: description: The connection connection_id names. enum: - stored type: string required: - runs_on - connection_id type: object ConnectionFallback: description: >- What a task continues on when its plan's window is spent: none stops it; named takes the connection or Aether inference; any_usable takes the first held connection the window does not block, then its optional named hop. A stored named hop without connection_id was disconnected. oneOf: - $ref: '#/components/schemas/ConnectionFallbackNone' - $ref: '#/components/schemas/ConnectionFallbackNamedAether' - $ref: '#/components/schemas/ConnectionFallbackNamedStored' - $ref: '#/components/schemas/ConnectionFallbackAnyUsable' AgentProfileRunsOnAether: additionalProperties: false properties: runs_on: description: Aether inference, paid from the task's organization's balance. enum: - aether type: string required: - runs_on type: object AgentProfileRunsOnDefault: additionalProperties: false properties: runs_on: description: 'No pin: each task runs on its creator''s default.' enum: - default type: string required: - runs_on type: object AgentProfileRunsOnStored: additionalProperties: false properties: id: format: uuid type: string name: minLength: 1 type: string option: enum: - claude_plan - anthropic_api_key - chatgpt_plan - openai_api_key - openrouter_api_key - opencode_auth_file type: string owner: description: Who holds the connection, by their display name, else their email. minLength: 1 type: string runs_on: enum: - stored type: string required: - runs_on - id - option - name - owner type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ConnectionFallbackNone: additionalProperties: false properties: mode: enum: - none type: string required: - mode type: object ConnectionFallbackWriteNamedAether: additionalProperties: false properties: mode: enum: - named type: string runs_on: description: >- Aether inference, paid from your organization's balance: Claude Code and Codex only. enum: - aether type: string required: - mode - runs_on type: object ConnectionFallbackWriteNamedStored: additionalProperties: false properties: connection_id: description: A connection you hold that works with the harness. format: uuid type: string mode: enum: - named type: string runs_on: description: The connection connection_id names. enum: - stored type: string required: - mode - runs_on - connection_id type: object ConnectionFallbackWriteAnyUsable: additionalProperties: false properties: mode: enum: - any_usable type: string then: discriminator: mapping: aether: '#/components/schemas/ConnectionFallbackWriteAether' stored: '#/components/schemas/ConnectionFallbackWriteStored' propertyName: runs_on oneOf: - $ref: '#/components/schemas/ConnectionFallbackWriteAether' - $ref: '#/components/schemas/ConnectionFallbackWriteStored' required: - mode type: object ConnectionFallbackNamedAether: additionalProperties: false properties: mode: enum: - named type: string runs_on: description: >- Aether inference, paid from your organization's balance: Claude Code and Codex only. enum: - aether type: string required: - mode - runs_on type: object ConnectionFallbackNamedStored: additionalProperties: false properties: connection_id: description: A connection you hold that works with the harness. format: uuid type: string mode: enum: - named type: string runs_on: description: The connection connection_id names. enum: - stored type: string required: - mode - runs_on type: object ConnectionFallbackAnyUsable: additionalProperties: false properties: mode: enum: - any_usable type: string then: discriminator: mapping: aether: '#/components/schemas/ConnectionFallbackAether' stored: '#/components/schemas/ConnectionFallbackStored' propertyName: runs_on oneOf: - $ref: '#/components/schemas/ConnectionFallbackAether' - $ref: '#/components/schemas/ConnectionFallbackStored' required: - mode type: object ConnectionFallbackWriteAether: additionalProperties: false properties: runs_on: description: >- Aether inference, paid from your organization's balance: Claude Code and Codex only. enum: - aether type: string required: - runs_on type: object ConnectionFallbackWriteStored: additionalProperties: false properties: connection_id: description: A connection you hold that works with the harness. format: uuid type: string runs_on: description: The connection connection_id names. enum: - stored type: string required: - runs_on - connection_id type: object ConnectionFallbackAether: additionalProperties: false properties: runs_on: description: >- Aether inference, paid from your organization's balance: Claude Code and Codex only. enum: - aether type: string required: - runs_on type: object ConnectionFallbackStored: additionalProperties: false properties: connection_id: description: A connection you hold that works with the harness. format: uuid type: string runs_on: description: The connection connection_id names. enum: - stored type: string required: - runs_on type: object securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.