Assistant Update API
Update an existing Assistant programmatically
Assistant Update API
Update an existing Assistant programmatically
The Assistants API will be deprecated on 30 April.
For new projects, we recommend using the Agents API. The Agents API provides native Vercel AI SDK compatibility and removes custom transformations.
See the migration guide to learn about the differences.
Updates an existing Assistant in your workspace. Only the fields you provide will be updated, allowing for partial updates without affecting other configuration.
Requires an API key with the
AGENT_APIscope and access to the Assistant you want to update.
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, andattachmentscompletely replace existing values when provided - Empty arrays - Send
[]to remove all actions/fields/attachments - Null handling - Send
nullforemojito clear it. Fordescriptionandinstruction, 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 |
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.
Actions Configuration
Each action in the actions array should contain:
actionId(required) - UUID of the action from an enabled integrationrequiresConfirmation(optional) - Whether to require user confirmation before executing
Input Fields Configuration
For inputFields array structure, see the Create Assistant API documentation.
Examples
Updating Basic Properties
const axios = require("axios");
async function updateAssistantName() {
const response = await axios.patch(
"https://api.odeus.ai/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)
{
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
try {
const response = await axios.patch('https://api.odeus.ai/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
Preserving existing values: When updating array fields like
actionsorattachments, always include existing items you want to keep, as the entire array is replaced.
- Fetch before update - If you need to preserve existing array values, fetch the current Assistant configuration first
- Incremental updates - Update only the fields that need to change
- Validate attachments - Ensure attachment UUIDs are valid before including them
- Test actions - Verify actions belong to enabled integrations before updating
- 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 - Uses
agentIdinstead ofassistantId
Odeus 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.
OpenAPI
openapi: 3.0.0
info:
title: Odeus API
version: 3.0.0
servers:
- url: https://api.odeus.ai
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"