> ## Documentation Index > Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update an agent > Partially update an agent (ChatSettings) by ID. **Access control:** - Users can update agents in their personal groups - Company admins can update agents in any group within their company - Sys-admin users can update any agent **Model configuration:** - `ml_model` and `ml_model_alias` are mutually exclusive — provide one or neither, not both - Setting one automatically clears the other - Explicitly sending `null` clears the field (agent falls back to company default) - Omitting the field leaves the current value unchanged ## OpenAPI ````yaml /api-reference/openapi-v3.yaml patch /api/v3/agents/{id} openapi: 3.1.0 info: title: LightOn API version: 3.15.0 (v3) description: >- LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. servers: - url: https://paradigm.lighton.ai security: [] tags: - name: Agents description: Operations about agents - name: Threads description: Operations about agents conversation threads - name: Tools description: Operations about native tools - name: Models description: Operations about AI models - name: MCP description: Operations about MCP servers - name: Sources description: Operations about sources used by agents conversation threads - name: Artifacts description: Operations about artifacts generated by agents conversation threads - name: Agent description: >- Operations about agents (deprecated). Please use the 'Agents' API component instead. - name: Files description: Operations about files - name: Facets description: Operations about facets - name: Tags description: Operations about tags - name: Workspaces description: Operations about workspaces - name: Files Processing description: Operations about files processing - name: Users description: Operations about users - name: API Keys description: Operations about API keys - name: User Groups description: Operations about user groups - name: SCIM description: Operations about SCIM paths: /api/v3/agents/{id}: patch: tags: - Agents summary: Update an agent description: >- Partially update an agent (ChatSettings) by ID. **Access control:** - Users can update agents in their personal groups - Company admins can update agents in any group within their company - Sys-admin users can update any agent **Model configuration:** - `ml_model` and `ml_model_alias` are mutually exclusive — provide one or neither, not both - Setting one automatically clears the other - Explicitly sending `null` clears the field (agent falls back to company default) - Omitting the field leaves the current value unchanged operationId: api_v3_agents_partial_update parameters: - in: path name: id schema: type: integer description: ID of the agent to update required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateAgentRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateAgentRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateAgentRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentSchema' description: '' '400': content: application/json: schema: description: Invalid request data description: '' '403': content: application/json: schema: description: Permission denied description: '' '404': content: application/json: schema: description: Agent, tool, or MCP server not found description: '' '503': description: >- API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' security: - bearerAuth: [] components: schemas: PatchedUpdateAgentRequest: type: object properties: name: type: - string - 'null' description: type: - string - 'null' instructions: type: - string - 'null' scope_workspaces_by_group: type: - boolean - 'null' native_tool_ids: type: - array - 'null' items: type: string format: uuid mcp_server_ids: type: - array - 'null' items: type: string format: uuid scoped_workspace_ids: type: - array - 'null' items: type: integer ml_model: type: - string - 'null' format: uuid ml_model_alias: type: - string - 'null' format: uuid AgentSchema: type: object properties: id: type: integer name: type: string description: type: - string - 'null' instructions: type: - string - 'null' company: $ref: '#/components/schemas/CompanySchema' group: $ref: '#/components/schemas/GroupSchema' workspaces: type: array items: $ref: '#/components/schemas/WorkspaceSchema' tools: $ref: '#/components/schemas/AgentToolsSchema' is_default: type: boolean ownership: type: string scope_workspaces_by_group: type: boolean scoped_workspace_ids: type: array items: type: integer ml_model: type: - string - 'null' format: uuid ml_model_alias: type: - string - 'null' format: uuid is_current_user_favorite: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time required: - company - created_at - description - group - id - instructions - is_current_user_favorite - is_default - ml_model - ml_model_alias - name - ownership - scope_workspaces_by_group - scoped_workspace_ids - tools - updated_at - workspaces ServiceMaintenance503: type: object description: >- Returned by the maintenance middleware when the requested endpoint is blocked. required: - detail - error - mode properties: detail: type: string example: System is under maintenance. error: type: string example: service_maintenance mode: type: string enum: - full_shutdown - warning_banner description: >- `full_shutdown` blocks all traffic; `warning_banner` also blocks and shows a dismissible toast. reason: type: string description: Operator-supplied maintenance reason, if any. started_at: type: string format: date-time endpoint_category_names: type: array items: type: string description: >- Non-empty only for category-scoped periods. Empty means all endpoints are affected. CompanySchema: type: object properties: id: type: integer name: type: string allow_ephemeral_mode: type: boolean is_sharing_enabled: type: boolean required: - allow_ephemeral_mode - id - is_sharing_enabled - name GroupSchema: type: object properties: name: type: string id: type: integer required: - id - name WorkspaceSchema: type: object properties: id: type: integer name: type: string category: type: string file_count: type: integer summaries: type: array items: $ref: '#/components/schemas/WorkspaceSummarySchema' default: [] required: - category - file_count - id - name AgentToolsSchema: type: object properties: native: type: array items: $ref: '#/components/schemas/NativeToolSchema' mcp_servers: type: array items: $ref: '#/components/schemas/MCPServerSchema' required: - mcp_servers - native WorkspaceSummarySchema: type: object properties: language: type: string summary: type: string required: - language - summary NativeToolSchema: type: object properties: id: type: string name: type: string object: type: string default: tool required: - id - name MCPServerSchema: type: object properties: id: type: string name: type: string object: type: string default: mcp_server required: - id - name securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````