# Update assistant

Update an existing assistant's configuration, tools, and settings.

#### Path Parameters

**`assistant_id`** string required

The unique identifier of the assistant to update.

#### Request Body

**`name`** string optional

The name of the assistant. Must be unique within the organization.

**`description`** string optional

A brief description of the assistant's purpose and capabilities.

**`default_model_key`** string optional

The AI model key to use for this assistant. [View available models →](/docs/documentation/getting-started/models)

**`instructions`** string optional

System instructions that define the assistant's behavior and personality.

**`personality_id`** string optional

Style-profile id (`sty_…`, `kind=personality`). Null clears the character and keeps register settings. [List style profiles](/docs/api-reference/style-profiles/list).

**`personality_settings`** object optional

Partial register patch. Null clears to defaults. Omitted keys keep the stored value. Same enums as [Create assistant](/docs/api-reference/assistants/create).

**`avatar_id`** string optional

Predefined avatar identifier from the Aitronos avatar library. [View available avatars →](/assets/list.d669ff9103f000c8666b615b40b07c3fc85c38b5f79c4c450993a9c75eb89d8c.76c3c710.md)

**`tool_configurations`** object optional

Configuration for built-in system tools and external integrations. See [Assistant object](/docs/api-reference/objects/assistant-object) for full structure.

**`system_message`** array optional

Pre-configured system messages or input examples. An array of input message objects with texts, images, or files.

**`locale`** string optional

Language of this assistant's streamed [activity labels](/docs/api-reference/responses/create) (`activity.text`): `auto` (the default; `null` means the same and is read back as `auto`), a language tag such as `de` or `pt-BR`, or a language name such as `Swiss German`. Auto follows the language of the person's message, then the language they chose for their account, then English. A request's own `locale` takes precedence. The choices with built-in labels are listed by [List activity label languages](/docs/api-reference/assistants/list-activity-label-languages); any other language is stored and served as Auto until its labels exist. A value that is neither a language tag nor a language name (or the literal `custom`) is rejected with `422`. Affects only the progress labels, never the assistant's answers.

**`context_strategy`** string optional · Defaults to `auto`

Sets the overall thread context management strategy. Values: `full`, `off`, `auto`, `saver`.

**`max_tool_calls`** integer optional

Maximum number of built-in tool calls allowed per response.

**`parallel_tool_calls`** boolean optional

Whether the assistant can execute multiple tool calls simultaneously.

**`access_mode`** string optional

Access control for the assistant. One of `private`, `organization`, `public`.

**`temperature`** number optional

Controls randomness in responses (0.0 to 1.0).

**`max_completion_tokens`** integer optional

Maximum number of tokens to generate in the completion.

**`is_active`** boolean optional

Whether the assistant is active and available for use.

**`api_enabled`** boolean optional

Whether the assistant is accessible via API.

**`access_departments`** array optional

List of department IDs that can access this assistant.

**`access_users`** array optional

List of user IDs that can access this assistant.

**`allowed_model_providers`** array optional

List of allowed AI model providers for this assistant.

**`assistant_metadata`** object optional

Custom metadata for the assistant as key-value pairs.

**`context_window`** integer optional

Maximum context window size in tokens.

**`editable_by_roles`** array optional

List of role IDs that can edit this assistant.

**`editable_by_users`** array optional

List of user IDs that can edit this assistant.

**`frequency_penalty`** number optional

Penalty for token frequency (-2.0 to 2.0). Reduces repetition.

**`icon_data`** string optional

Base64-encoded icon image data.

**`icon_id`** string optional

ID of a predefined icon from the icon library.

**`icon_type`** string optional

Type of icon: `emoji`, `image`, or `library`.

**`instructions_thread_id`** string optional

Thread ID containing instruction templates.

**`is_default`** boolean optional

Whether this is the default assistant for the organization.

**`logit_bias`** object optional

**Deprecated and non-functional.** No model provider honors `logit_bias` on the conversation path, so it has no effect. Sending a non-empty value returns a `422 INVALID_REQUEST` error. Omit this field.

**`memory_enabled`** boolean optional

Whether the assistant can remember context across conversations.

**`moderation_enabled`** boolean optional

Stored and returned as set. No content moderation is applied today: nothing in the backend reads this flag, so `true` and `false` produce the same model behaviour. Omit to leave it unchanged.

**`output_mode`** string optional

Output format mode: `text`, `json`, or `structured`.

**`skin_mode`** string optional

Deprecated: every assistant uses the one skin catalog, so this is always `v2`. Any value sent (`legacy`, `beta` or `v2`) is accepted and stored as `v2`; responses return `v2`.

**`presence_penalty`** number optional

Penalty for token presence (-2.0 to 2.0). Encourages topic diversity.

**`preset_prompts`** array optional

List of preset prompt IDs for quick access.

**`public_enabled`** boolean optional

Whether the assistant is publicly accessible.

**`reasoning`** object optional

Reasoning configuration for advanced models. See reasoning schema.

**`response_format`** string optional

Expected response format: `text`, `json_object`, or `json_schema`.

**`rule_ids`** array optional

List of rule IDs to apply to this assistant.

**`safety_level`** string optional

Stored and returned as set. Does NOT gate model output today: nothing in the backend reads this value, so `low`, `medium` and `high` produce the same model behaviour. Accepted values: `low`, `medium`, `high` — `strict` is not one of them and is refused with `422 VALIDATION_ERROR`. Omit to leave it unchanged.

**`seed`** integer optional

Random seed for deterministic outputs.

**`service_tier`** string optional

Processing tier for requests. Values: `auto`, `default`, `flex`, `priority`.

**`speed_tier`** string optional

The assistant's default speed tier id, from `GET /v1/models/speed-options` (for example `standard`, `priority` or `fast`). A turn that does not send its own `speed_tier` takes this value as its requested tier; a per-request `speed_tier` still overrides it. Send `null` to clear it, so the model's own default tier applies again; omit it to leave it unchanged. At most 32 characters.

**`stop_sequences`** array optional

List of sequences where the model will stop generating.

**`store_responses`** boolean optional

Whether to store assistant responses for analytics.

**`streaming`** boolean optional

Whether to enable streaming responses.

**`text_config`** object optional

Text generation configuration options.

**`top_logprobs`** integer optional

**Deprecated and non-functional.** Log probabilities are not returned on the conversation path, so this has no effect. Sending a non-zero value returns a `422 INVALID_REQUEST` error. Omit this field.

**`top_p`** number optional

Nucleus sampling threshold (0.0 to 1.0).

**`truncation`** boolean optional

Whether to truncate context if it exceeds limits.

**`vector_store_ids`** array optional

List of vector store IDs for knowledge retrieval.

**`personal_connector_attachments`** array optional

Personal connector credentials to attach, replacing the current set (the full desired state — a `credential_id` missing from the list is detached, not deleted). Each `credential_id` must be a connector credential owned by the assistant's creator. Pass an empty array to remove all attachments; omit the field to leave attachments unchanged.

**`visible_in_chat_to_users`** array optional

List of user IDs who can see this assistant in chat.

**`visible_to_roles`** array optional

List of role IDs that can view this assistant.

## Body parameters

**`delegate_to_whitelist`** array[string] optional

The delegate to whitelist.

**`skin_template_id`** string optional

The skin template id.

**`tool_approval_mode`** string optional

The tool approval mode.

**`voice_profile_id`** string optional

The voice profile id.

**`allowed_models`** object optional

The allowed models.

**`accept_delegations_from`** array[string] optional

The accept delegations from.

**`slice_ids`** array[string] optional

The slice ids.

**`knowledge_department_ids`** array[string] optional

Replaces the set of departments (`dept_*`) bound as a **live** knowledge source. The assistant searches whatever each bound department shares at the time of the question — a subscription, not a snapshot — so the ids are never expanded into `knowledge_store_ids` and the two lists coexist.

Omit the field to leave the current bindings unchanged; send `[]` to unbind every department. Only non-private, non-space-bound, active stores in the same organization resolve. Binding a department you do not belong to requires `manage_knowledge_slices`, `manage_access_control`, or owner-level permissions and otherwise returns `403 INSUFFICIENT_PERMISSIONS`; an unknown or inactive department id returns `422 DEPARTMENT_NOT_FOUND`. Maximum 100 ids.

**`advanced_settings_enabled`** boolean optional

The advanced settings enabled.

**`delegate_to_blacklist`** array[string] optional

The delegate to blacklist.

**`skill_ids`** array[string] optional

The skill ids.

**`knowledge_access_mode`** string optional

The knowledge access mode.

**`pinned`** boolean optional

Whether this assistant is pinned to the top of the assistant list.

**`image_operations`** string optional

Image operations mode: `auto`, `manual`, or `off`.

**`behavior_attachments_enabled`** boolean optional

Whether file attachments are enabled in the assistant behavior.

**`icon_name`** string optional

Display name for the icon.

**`prompt_cache_enabled`** boolean optional · Defaults to `true`

Enable prompt caching for this assistant (default true). Set false to stop sending a prompt cache key for this assistant.

**`grant_department_access`** array optional

Per-department access grants. Treated as the desired state — departments missing from the list have their grants revoked.

## Returns

Returns a JSON response indicating success or failure.

## Access & Permissions

Assistant access resolves to one of four levels — `none` < `view` < `edit` < `owner`.
Updating an assistant requires at least **edit** access, but the sharing/ACL fields are
**owner-only** (see the callout below).

| Level | Granted to |
|  --- | --- |
| **owner** | The creator (`created_by`), anyone with the `override_all_permissions` capability, or a holder of an `admin`-level access grant on this assistant. |
| **edit** | A user in `editable_by_users` (or the `"*"` wildcard, for org members), a role in `editable_by_roles`, the org-wide `manage_assistants` capability, or a `write`-level access grant on this assistant. |
| **view** | `access_mode` is `public`; or `access_mode` is `organization` and the caller is an org member; or the caller is listed in `access_users` / `access_departments` / `visible_to_roles` (all require org membership); or a `read`-level access grant. |
| **none** | Anyone else — the request is rejected with `403`. |


**This endpoint (`PUT`) requires `edit`.** Content fields (`name`, `description`,
`instructions`, `default_model_key`, tools, sampling parameters, etc.) can be changed by any
`edit`-level caller.

> ### Sharing fields are owner-only
Changing **who can see or edit** an assistant is restricted to the **owner** (the creator or
a holder of `override_all_permissions`). An `edit`-level caller who is *not* the owner — for
example someone listed in `editable_by_users` — may change content, but the request is
rejected with `403 INSUFFICIENT_PERMISSIONS` if it includes **any** of these owner-only
fields:
`access_mode`, `access_users`, `access_departments`, `grant_department_access`,
`editable_by_users`, `editable_by_roles`, `visible_to_roles`, `visible_in_chat_to_users`
**Recommendation:** when you are not the owner, send a **partial update that omits every
sharing field**. Sending back a full assistant object (including sharing fields you did not
intend to change) will be rejected even if their values are unchanged — the check is on
*presence* of the field in the request body, not on whether the value differs. The `403`
response lists the offending fields in `error.details.fields`.


For the full access model — how each level is granted, the field reference, and common
sharing patterns — see [Assistant Access Management](/docs/api-reference/assistants/access-management).

Update Name

```bash
curl https://api.aitronos.com/v1/assistants/asst_abc123 \
  -X PUT \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Assistant Name"
  }'
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

assistant = client.assistants.update_assistant(
    assistant_id="asst_abc123",
    organization_id="org_12345",
    name="Updated Assistant",
)
print(assistant)
```


```python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.put(
    "https://api.aitronos.com/v1/assistants/asst_abc123",
    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
    json={"name": "Updated Assistant Name"},
)

assistant = response.json()
```


```javascript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/assistants/asst_abc123', {
  method: 'PUT',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Updated Assistant Name'
  })
});

const assistant = await response.json();
```

Update Tools

```bash
curl https://api.aitronos.com/v1/assistants/asst_abc123 \
  -X PUT \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      {
        "type": "web_search",
        "search_context_size": "large"
      },
      {
        "type": "code_interpreter"
      },
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          }
        }
      }
    ]
  }'
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

assistant = client.assistants.update_assistant(
    assistant_id="asst_abc123",
    organization_id="org_12345",
    name="Updated Assistant",
)
print(assistant)
```


```python
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.put(
    "https://api.aitronos.com/v1/assistants/asst_abc123",
    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
    json={
        "tools": [
            {"type": "web_search", "search_context_size": "large"},
            {"type": "code_interpreter"},
            {
                "type": "function",
                "name": "get_weather",
                "description": "Get current weather",
                "parameters": {
                    "type": "object",
                    "properties": {"location": {"type": "string"}},
                },
            },
        ]
    },
)

assistant = response.json()
```


```javascript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/assistants/asst_abc123', {
  method: 'PUT',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tools: [
      {
        type: 'web_search',
        'search_context_size': 'large'
      },
      {
        type: 'code_interpreter'
      },
      {
        type: 'function',
        name: 'get_weather',
        description: 'Get current weather',
        parameters: {
          type: 'object',
          properties: {
            location: { type: 'string' }
          }
        }
      }
    ]
  })
});

const assistant = await response.json();
```

**Response:**

200 OK

```json
{
  "message": "Operation successful",
  "data": {}
}
```

422 Validation Error

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input should be 'low', 'medium' or 'high'",
    "system_message": "Request validation failed",
    "type": "validation_error",
    "status": 422,
    "details": {
      "fields": [
        {
          "field": "safety_level",
          "message": "Input should be 'low', 'medium' or 'high'",
          "type": "literal_error"
        }
      ]
    },
    "trace_id": "req_xyz789",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

401 Unauthorized

```json
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Please sign in to continue.",
    "system_message": "Authentication required. Provide either x-api-key, api-key, X-API-Key, or API-Key header, or Bearer ***",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

403 Forbidden

```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to perform this action.",
    "system_message": "You don't have permission to access this assistant",
    "type": "authorization_error",
    "status": 403,
    "details": {
      "assistant_id": "asst_abc123",
      "required_level": "edit"
    },
    "trace_id": "req_def456",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

404 Not Found

```json
{
  "success": false,
  "error": {
    "code": "ASSISTANT_NOT_FOUND",
    "message": "The requested assistant could not be found.",
    "system_message": "Assistant not found",
    "type": "client_error",
    "status": 404,
    "details": {
      "assistant_id": "asst_abc123"
    },
    "trace_id": "req_mno345",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

429 Rate Limit

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait a moment and try again.",
    "system_message": "Rate limit exceeded for endpoint",
    "type": "rate_limit_error",
    "status": 429,
    "details": {
      "retry_after": 60,
      "limit": 100,
      "remaining": 0,
      "reset_at": "2025-11-11T10:31:00Z"
    },
    "trace_id": "req_ghi789",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

500 Server Error

```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong. Please try again later.",
    "system_message": "An unexpected error occurred",
    "type": "server_error",
    "status": 500,
    "details": {},
    "trace_id": "req_jkl012",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

## Response

**Returns**

The updated [Assistant object](/docs/api-reference/objects/assistant-object) with all configuration details.

200 OK

```json
{
  "id": "asst_abc123",
  "name": "Updated Assistant Name",
  "description": "AI assistant for research and analysis",
  "default_model_key": "ftg-3.0",
  "instructions": "You are a research assistant that helps find and analyze information.",
  "tools": [
    {
      "type": "web_search",
      "search_context_size": "large"
    },
    {
      "type": "code_interpreter"
    },
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        }
      }
    }
  ],
  "access_mode": "private",
  "is_active": true,
  "temperature": 0.3,
  "max_completion_tokens": 4000,
  "created_at": 1731318600,
  "updated_at": 1731318600,
  "organization_id": "org_abc123",
  "created_by": "user_abc123"
}
```

Errors

```json
{
  "success": false,
  "error": {
    "code": "ASSISTANT_NOT_FOUND",
    "message": "The requested assistant could not be found.",
    "system_message": "Assistant not found",
    "type": "client_error",
    "status": 404,
    "details": {
      "assistant_id": "asst_abc123"
    },
    "trace_id": "trace_abc123",
    "timestamp": "2025-11-11T10:30:00Z"
  }
}
```

## Related Resources

- [Assistant Access Management](/docs/api-reference/assistants/access-management) — Full access model and sharing fields
- [Create Assistant](/docs/api-reference/assistants/create)
- [Retrieve Assistant](/docs/api-reference/assistants/retrieve)
- [Delete Assistant](/docs/api-reference/assistants/delete)
- [List Assistants](/docs/api-reference/assistants/list)