Assistant Create API
Create a new Assistant programmatically
Assistant Create API
Create a new 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.
Creates a new Assistant in your workspace programmatically. The created assistant can be used via the chat completions endpoint or accessed through the Odeus UI.
Requires an API key with the
AGENT_APIscope. Created Assistants are automatically shared with the API key for use in chat completions.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the Assistant (1-80 characters) |
description | string | No | Description of what the Assistant does (max 500 chars) |
emoji | string | No | Emoji icon for the Assistant (e.g., "🤖") |
instruction | string | No | System prompt/instructions for the Assistant (max 40000 chars) |
inputType | string | No | Input type: "PROMPT" or "STRUCTURED" (default: "PROMPT") |
model | string | No | Model identifier (deployment name from the Models API) |
creativity | number | No | Temperature between 0-1 (default: 0.3) |
conversationStarters | string[] | No | Array of suggested prompts to help users get started |
actions | array | No | Array of action objects for custom integrations |
inputFields | array | No | Array of form field definitions (for STRUCTURED input type) |
attachments | string[] | No | Array of attachment UUIDs to include with the Assistant |
webSearch | boolean | No | Enable web search capability (default: false) |
imageGeneration | boolean | No | Enable image generation capability (default: false) |
dataAnalyst | boolean | No | Enable code interpreter capability (default: false) |
canvas | boolean | No | Enable canvas capability (default: false) |
extendedThinking | boolean | No | Enable extended thinking mode (default: false) |
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 (default: true)
Only actions from integrations enabled in your workspace can be used.
Input Fields Configuration
When using inputType: "STRUCTURED", you can define form fields in the inputFields array:
| Field | Type | Required | Description |
|---|---|---|---|
slug | string | Yes | Unique identifier for the field |
type | string | Yes | Field type (see supported types below) |
label | string | Yes | Display label for the field |
description | string | No | Help text for the field |
required | boolean | No | Whether the field is required (default: false) |
order | number | Yes | Display order (0-indexed) |
options | string[] | No | Options for SELECT type fields |
fileTypes | string[] | No | Allowed file types for FILE type fields |
emailDomain | string | No | Allowed email domain for EMAIL type fields |
Supported Field Types:
TEXT- Single line text inputMULTI_LINE_TEXT- Multi-line text areaNUMBER- Numeric inputCHECKBOX- Boolean checkboxFILE- File uploadSELECT- Dropdown selectionDATE- Date pickerEMAIL- Email address
Obtaining Attachment IDs
To include attachments with your Assistant, first upload files using the Upload Attachment API. This will return attachment UUIDs that you can include in the attachments array.
Examples
Creating a Basic Assistant
const axios = require("axios");
async function createBasicAssistant() {
const response = await axios.post(
"https://api.odeus.ai/assistant/v1/create",
{
name: "Document Analyzer",
description: "Analyzes and summarizes documents",
emoji: "📄",
instruction: "You are a helpful Assistant that analyzes documents and provides clear summaries of key information.",
creativity: 0.5,
conversationStarters: [
"Summarize this document",
"What are the key points?",
"Extract action items"
],
dataAnalyst: true,
webSearch: false
},
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
}
);
console.log("Assistant created:", response.data.assistant.id);
}
Validation Rules
The API enforces several validation rules:
- Model - Must be in your workspace's active models list
- Actions - Must belong to integrations enabled in your workspace
- Attachments - Must exist in your workspace and not be deleted
- Permissions - Your API key must have the
createAssistantspermission - Name - Must be between 1-80 characters
- Description - Maximum 500 characters
- Instruction - Maximum 40000 characters
- Creativity - Must be between 0 and 1
Important Notes
Pre-selected OAuth connections are not supported via the API. Users must configure OAuth connections through the Odeus UI.
- Created Assistants are automatically shared with your API key for use in chat completions
- The API key creator becomes the owner and can manage the Assistant in the UI
- Attachments are bidirectionally linked to the Assistant
- The Assistant type is set to
AGENT(notWORKFLOWorPROJECT) createdByandworkspaceIdare automatically set from your API key
Response Format
Success Response (201 Created)
{
status: "success";
message: "Assistant created 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.post('https://api.odeus.ai/assistant/v1/create', ...);
} 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 - requires AGENT_API scope');
break;
case 404:
console.error('Resource not found (model, action, or attachment)');
break;
case 500:
console.error('Server error');
break;
}
}
}
Migrating to Agents API
The new Agents API offers improved compatibility with modern AI SDKs. The create endpoint has similar functionality with updated parameter names.
See the equivalent endpoint in the Agents API:
- Agent Create 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/create:
post:
tags:
- Assistant Build
summary: '[Deprecated] Creates a new assistant'
description: >-
This endpoint is deprecated. Please use /agent/v1/create for new
integrations. Creates a new assistant in your workspace
programmatically.
operationId: createAgent
requestBody:
required: true
content:
application/json:
examples:
basicAgent:
summary: Basic agent with minimal configuration
value:
name: Document Analyzer
description: Analyzes and summarizes documents
emoji: 📄
instruction: You are a helpful agent that analyzes documents.
creativity: 0.5
dataAnalyst: true
agentWithActions:
summary: Agent with actions and capabilities
value:
name: Email Agent
description: Helps manage and send emails
emoji: 📧
instruction: You are an email agent.
model: gpt-5-mini
creativity: 0.7
conversationStarters:
- Send an email to my team
- Draft a follow-up email
actions:
- actionId: action-uuid
requiresConfirmation: true
webSearch: true
structuredInputAgent:
summary: Agent with structured input fields
value:
name: Invoice Analyzer
description: Analyzes invoices
emoji: 🧾
instruction: You are an invoice analysis agent.
inputType: STRUCTURED
inputFields:
- slug: customer_name
type: TEXT
label: Customer Name
description: Enter customer name
required: true
order: 0
options: []
- slug: invoice_date
type: DATE
label: Invoice Date
required: true
order: 1
options: []
dataAnalyst: true
schema:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 255
description: Name of the agent
description:
type: string
maxLength: 256
description: Description of what the agent does
emoji:
type: string
description: Emoji icon for the agent (e.g., "🤖")
instruction:
type: string
maxLength: 16384
description: System prompt/instructions for the agent
inputType:
type: string
enum:
- PROMPT
- STRUCTURED
default: PROMPT
description: 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
default: 0.3
description: Temperature for response generation
conversationStarters:
type: array
items:
type: string
description: Array of suggested prompts to help users get started
actions:
type: array
items:
type: object
required:
- actionId
properties:
actionId:
type: string
format: uuid
description: UUID of the action from an enabled integration
requiresConfirmation:
type: boolean
default: false
description: Whether to require user confirmation before executing
description: Array of action objects for custom integrations
inputFields:
type: array
items:
type: object
required:
- slug
- type
- label
- 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
default: false
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
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 to include with the agent
webSearch:
type: boolean
default: false
description: Enable web search capability
imageGeneration:
type: boolean
default: false
description: Enable image generation capability
dataAnalyst:
type: boolean
default: false
description: Enable code interpreter capability
canvas:
type: boolean
default: false
description: Enable canvas capability
responses:
'201':
description: Agent created successfully
content:
application/json:
schema:
type: object
required:
- status
- message
- agent
properties:
status:
type: string
enum:
- success
message:
type: string
example: Assistant created 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 - requires AGENT_API scope
content:
application/json:
schema:
type: object
properties:
message:
type: string
'404':
description: Resource not found (model, action, or 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"