> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assistant Update API

> Update an existing Assistant programmatically

<Warning>
  **The Assistants API will be deprecated on 30 April.**

  For new projects, we recommend using the [Agents API](/en/developer/agents-api/agent-update). The Agents API provides native Vercel AI SDK compatibility and removes custom transformations.

  See the [migration guide](/en/developer/assistants-api/assistant-to-agent-migration) to learn about the differences.
</Warning>

Updates an existing Assistant in your workspace. Only the fields you provide will be updated, allowing for partial updates without affecting other configuration.

<Info>
  Requires an API key with the `AGENT_API` scope and access to the Assistant you want to update.
</Info>

## Update Behavior

The update endpoint uses partial update semantics with specific behavior for different field types:

* **Partial updates** - Only fields provided in the request are updated; omitted fields remain unchanged
* **Array fields replace** - `actions`, `inputFields`, `conversationStarters`, and `attachments` completely replace existing values when provided
* **Empty arrays** - Send `[]` to remove all actions/fields/attachments
* **Null handling** - Send `null` for `emoji` to clear it. For `description` and `instruction`, send an empty string `""` to clear them
* **Unchanged fields** - Fields not included in the request retain their current values

## Request Parameters

Set any of the parameters below to overwrite the assistant's current settings. Fields you omit stay unchanged. Only `assistantId` is required.

| Parameter              | Type      | Required | Description                                    |
| ---------------------- | --------- | -------- | ---------------------------------------------- |
| `assistantId`          | string    | Yes      | UUID of the assistant to update                |
| `name`                 | string    | No       | Assistant name (1-80 characters)               |
| `description`          | string    | No       | Description (max 500 chars, `""` to clear)     |
| `emoji`                | string    | No       | Emoji icon (null to clear)                     |
| `instruction`          | string    | No       | System prompt (max 40000 chars, `""` to clear) |
| `model`                | string    | No       | Model UUID                                     |
| `creativity`           | number    | No       | Temperature between 0 and 1                    |
| `conversationStarters` | string\[] | No       | Suggested prompts (replaces existing)          |
| `actions`              | array     | No       | Actions (replaces existing)                    |
| `inputFields`          | array     | No       | Form fields (replaces existing)                |
| `attachments`          | string\[] | No       | Attachment UUIDs (replaces existing)           |
| `webSearch`            | boolean   | No       | Enable web search                              |
| `imageGeneration`      | boolean   | No       | Enable image generation                        |
| `dataAnalyst`          | boolean   | No       | Enable code interpreter                        |
| `canvas`               | boolean   | No       | Enable canvas                                  |
| `extendedThinking`     | boolean   | No       | Enable extended thinking mode                  |

<Warning>
  Array fields (`actions`, `inputFields`, `conversationStarters`, `attachments`) are **replaced entirely**, not merged. Always provide the complete desired array, including any existing items you want to keep.
</Warning>

### Actions Configuration

Each action in the `actions` array should contain:

* `actionId` (required) - UUID of the action from an enabled integration
* `requiresConfirmation` (optional) - Whether to require user confirmation before executing

### Input Fields Configuration

For `inputFields` array structure, see the [Create Assistant API](/en/developer/assistants-api/assistant-create) documentation.

## Examples

### Updating Basic Properties

```javascript theme={null}
const axios = require("axios");

async function updateAssistantName() {
  const response = await axios.patch(
    "https://api.langdock.com/assistant/v1/update",
    {
      assistantId: "550e8400-e29b-41d4-a716-446655440000",
      name: "Advanced Document Analyzer",
      description: "Analyzes documents with enhanced capabilities",
      creativity: 0.7
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Assistant updated:", response.data.message);
}
```

## Validation Rules

The API enforces several validation rules:

* **Assistant access** - Your API key must have access to the assistant
* **Workspace match** - Assistant must belong to the same workspace as your API key
* **Model** - If provided, must be in your workspace's active models list
* **Actions** - If provided, must belong to integrations enabled in your workspace
* **Attachments** - If provided, must exist in your workspace and not be deleted
* **Name** - If provided, must be between 1-80 characters
* **Description** - If provided, maximum 500 characters
* **Instruction** - If provided, maximum 40000 characters
* **Creativity** - If provided, must be between 0 and 1

## Response Format

### Success Response (200 OK)

```typescript theme={null}
{
  status: "success";
  message: "Assistant updated successfully";
  assistant: {
    id: string;
    name: string;
    description: string;
    instruction: string;
    emojiIcon: string;
    model: string;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    codeInterpreterEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      slug: string;
      type: string;
      label: string;
      description: string;
      required: boolean;
      order: number;
      options: string[];
      fileTypes: string[] | null;
      emailDomain: string | null;
    }>;
    attachments: string[];
    createdAt: string;
    updatedAt: string;
  };
}
```

## Error Handling

```typescript theme={null}
try {
  const response = await axios.patch('https://api.langdock.com/assistant/v1/update', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters:', error.response.data.message);
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('Insufficient permissions - no access to this Assistant');
        break;
      case 404:
        console.error('Assistant not found or resource not found (model, action, attachment)');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}
```

## Best Practices

<Info>
  **Preserving existing values**: When updating array fields like `actions` or `attachments`, always include existing items you want to keep, as the entire array is replaced.
</Info>

1. **Fetch before update** - If you need to preserve existing array values, fetch the current Assistant configuration first
2. **Incremental updates** - Update only the fields that need to change
3. **Validate attachments** - Ensure attachment UUIDs are valid before including them
4. **Test actions** - Verify actions belong to enabled integrations before updating
5. **Handle errors gracefully** - Implement proper error handling for validation failures

## Migrating to Agents API

The new Agents API offers improved compatibility with modern AI SDKs. The update endpoint has similar functionality with updated parameter names.

See the equivalent endpoint in the Agents API:

* [Agent Update API](/en/developer/agents-api/agent-update) - Uses `agentId` instead of `assistantId`

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml PATCH /assistant/v1/update
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
security:
  - bearerAuth: []
paths:
  /assistant/v1/update:
    patch:
      tags:
        - Assistant Build
      summary: '[Deprecated] Updates an existing assistant'
      description: >-
        This endpoint is deprecated. Please use /agent/v1/update for new
        integrations. Updates an existing assistant in your workspace. Only
        provided fields will be updated.
      operationId: updateAgent
      requestBody:
        required: true
        content:
          application/json:
            examples:
              updateBasicProperties:
                summary: Update name and description
                value:
                  assistantId: 550e8400-e29b-41d4-a716-446655440000
                  name: Advanced Document Analyzer
                  description: Analyzes documents with enhanced capabilities
                  creativity: 0.7
              enableCapabilities:
                summary: Enable web search and data analyst
                value:
                  assistantId: 550e8400-e29b-41d4-a716-446655440000
                  webSearch: true
                  dataAnalyst: true
                  conversationStarters:
                    - Search the web for recent news
                    - Analyze this data
              updateActions:
                summary: Replace actions array
                value:
                  assistantId: 550e8400-e29b-41d4-a716-446655440000
                  actions:
                    - actionId: action-uuid-1
                      requiresConfirmation: true
                    - actionId: action-uuid-2
                      requiresConfirmation: false
              clearFields:
                summary: Clear optional fields with null
                value:
                  assistantId: 550e8400-e29b-41d4-a716-446655440000
                  description: null
                  emoji: null
            schema:
              type: object
              required:
                - assistantId
              properties:
                assistantId:
                  type: string
                  format: uuid
                  description: UUID of the agent to update
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Updated name
                description:
                  type: string
                  maxLength: 256
                  nullable: true
                  description: Updated description (null to clear)
                emoji:
                  type: string
                  nullable: true
                  description: Updated emoji icon (null to clear)
                instruction:
                  type: string
                  maxLength: 16384
                  nullable: true
                  description: Updated system prompt (null to clear)
                inputType:
                  type: string
                  enum:
                    - PROMPT
                    - STRUCTURED
                  description: Updated input type for the agent
                model:
                  type: string
                  description: Model ID to use (see Models for Agent API)
                creativity:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: Updated temperature
                conversationStarters:
                  type: array
                  items:
                    type: string
                  description: Updated array of suggested prompts (replaces existing)
                actions:
                  type: array
                  items:
                    type: object
                    required:
                      - actionId
                    properties:
                      actionId:
                        type: string
                        format: uuid
                      requiresConfirmation:
                        type: boolean
                        default: false
                  description: Updated array of actions (replaces existing)
                inputFields:
                  type: array
                  items:
                    type: object
                    required:
                      - slug
                      - type
                      - label
                      - order
                    properties:
                      slug:
                        type: string
                      type:
                        type: string
                        enum:
                          - TEXT
                          - MULTI_LINE_TEXT
                          - NUMBER
                          - CHECKBOX
                          - FILE
                          - SELECT
                          - DATE
                      label:
                        type: string
                      description:
                        type: string
                      required:
                        type: boolean
                        default: false
                      order:
                        type: integer
                        minimum: 0
                      options:
                        type: array
                        items:
                          type: string
                      fileTypes:
                        type: array
                        items:
                          type: string
                  description: Updated array of form fields (replaces existing)
                attachments:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Updated array of attachment UUIDs (replaces existing)
                webSearch:
                  type: boolean
                  description: Updated web search capability setting
                imageGeneration:
                  type: boolean
                  description: Updated image generation capability setting
                dataAnalyst:
                  type: boolean
                  description: Updated code interpreter capability setting
                canvas:
                  type: boolean
                  description: Updated canvas capability setting
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - agent
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                    example: Assistant updated successfully
                  assistant:
                    $ref: '#/components/schemas/AssistantDetails'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: object
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '403':
          description: Insufficient permissions - no access to this agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Agent not found or resource not found (model, action, attachment)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
      deprecated: true
components:
  schemas:
    AssistantDetails:
      type: object
      required:
        - id
        - name
        - emojiIcon
        - model
        - temperature
        - inputType
        - webSearchEnabled
        - imageGenerationEnabled
        - codeInterpreterEnabled
        - canvasEnabled
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the agent
        name:
          type: string
          description: Name of the agent
        description:
          type: string
          nullable: true
          description: Description of what the agent does
        instruction:
          type: string
          nullable: true
          description: System prompt/instructions for the agent
        emojiIcon:
          type: string
          nullable: true
          description: Emoji icon for the agent
        model:
          type: string
          description: Model ID to use (see Models for Agent API)
        temperature:
          type: number
          minimum: 0
          maximum: 1
          description: Temperature/creativity setting for response generation
        conversationStarters:
          type: array
          items:
            type: string
          description: Array of suggested prompts to help users get started
        inputType:
          type: string
          enum:
            - PROMPT
            - STRUCTURED
          description: Input type for the agent
        webSearchEnabled:
          type: boolean
          description: Whether web search capability is enabled
        imageGenerationEnabled:
          type: boolean
          description: Whether image generation capability is enabled
        codeInterpreterEnabled:
          type: boolean
          description: Whether code interpreter/data analyst capability is enabled
        canvasEnabled:
          type: boolean
          description: Whether canvas capability is enabled
        extendedThinking:
          type: boolean
          description: >-
            Whether extended thinking is enabled. Only supported on models that
            expose this capability; enabling it on an unsupported model returns
            a 400 error.
        actions:
          type: array
          items:
            type: object
            required:
              - actionId
              - requiresConfirmation
            properties:
              actionId:
                type: string
                format: uuid
                description: UUID of the action from an enabled integration
              requiresConfirmation:
                type: boolean
                description: Whether user confirmation is required before executing
          description: Array of action objects for custom integrations
        inputFields:
          type: array
          items:
            type: object
            required:
              - slug
              - type
              - label
              - required
              - order
            properties:
              slug:
                type: string
                description: Unique identifier for the field
              type:
                type: string
                enum:
                  - TEXT
                  - MULTI_LINE_TEXT
                  - NUMBER
                  - CHECKBOX
                  - FILE
                  - SELECT
                  - DATE
                description: Field type
              label:
                type: string
                description: Display label for the field
              description:
                type: string
                description: Help text for the field
              required:
                type: boolean
                description: Whether the field is required
              order:
                type: integer
                minimum: 0
                description: Display order (0-indexed)
              options:
                type: array
                items:
                  type: string
                description: Options for SELECT type fields
              fileTypes:
                type: array
                items:
                  type: string
                nullable: true
                description: Allowed file types for FILE type fields
          description: Array of form field definitions (for STRUCTURED input type)
        attachments:
          type: array
          items:
            type: string
            format: uuid
          description: Array of attachment UUIDs associated with the agent
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the agent was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the agent was last updated
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````