---
title: "Modify AI operator instance"
method: PATCH
path: "/v1/ai/operators/{operator-id}"
tags: ["AI Operators"]
---

# Modify AI operator instance

`PATCH /v1/ai/operators/{operator-id}`

Partially update an AI operator instance; only the fields present in the request body are changed.

## Path parameters

- `operator-id` integer, required

## Request body

- AiOperatorConfig — AI operator instance configuration. All fields are optional on update; "name" is required on creation. Adaptive state fields (currentFocus, watchList, memento) are managed by the operator itself and cannot be set through this schema — use the reset-memento endpoint to clear them.
  - `name` string — Instance name (required on creation)
  - `description` string — Instance description
  - `enabled` boolean — Enable or disable the instance
  - `scopeFilter` string — Attention scope filter
  - `modelSlot` string — AI model slot to use (empty = default)
  - `minInterval` integer — Minimum interval between executions in seconds (floor 60)
  - `maxInterval` integer — Maximum interval between executions in seconds (must be >= minInterval)
  - `dailyTokenBudget` integer — Daily LLM token budget (0 = unlimited)
  - `personaPrompt` string — Additional persona instructions
  - `observationRetentionDays` integer — Observation retention override in days (0 = server default)
  - `observationMaxRecords` integer — Observation record cap override (0 = server default)

## Response `200`

Updated instance

- AiOperator
  - `id` integer — Unique instance identifier
  - `name` string — Instance name
  - `description` string — Instance description
  - `ownerUserId` integer — ID of the user who created the instance
  - `enabled` boolean — True if the instance is enabled
  - `executing` boolean — True if an iteration is currently running
  - `scopeFilter` string — Attention scope filter (object names or IDs)
  - `modelSlot` string — AI model slot used for executions (empty = default)
  - `minInterval` integer — Minimum interval between executions in seconds
  - `maxInterval` integer — Maximum interval between executions in seconds
  - `dailyTokenBudget` integer — Daily LLM token budget (0 = unlimited)
  - `tokensUsedToday` integer — LLM tokens used within the current usage day (UTC)
  - `personaPrompt` string — Additional persona instructions appended to the system prompt
  - `currentFocus` string — Current focus set by the operator itself
  - `watchList` string — Watch list maintained by the operator itself
  - `memento` string — State carried between iterations by the operator itself
  - `observationRetentionDays` integer — Observation retention override in days (0 = server default)
  - `observationMaxRecords` integer — Observation record cap override (0 = server default)
  - `lastExecutionTime` string, date-time — Time of the last completed execution
  - `nextExecutionTime` string, date-time — Scheduled time of the next execution
  - `iteration` integer — Number of completed iterations
  - `consecutiveFailures` integer — Consecutive failed executions (resets on success and restart)
  - `lastExplanation` string — Explanation returned by the last execution
  - `created` string, date-time — Instance creation time
  - `modified` string, date-time — Last configuration change time

## Other responses

- `400` — Invalid configuration
- `403` — Insufficient access rights
- `404` — Instance not found

---

[API](https://skmtc.net/netxms/apis/netxms-api.md) · [All operations](https://skmtc.net/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netxms/netxms-api/versions/14d93e5115dd/schema)