Assistant Get API
Retrieve details of an existing Assistant
Assistant Get API
Retrieve details of an existing Assistant
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.
Retrieves the complete configuration and details of an existing Assistant in your workspace.
Requires an API key with the
AGENT_APIscope and access to the Assistant you want to retrieve.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assistantId | string | Yes | UUID of the assistant to retrieve |
Examples
Basic Retrieval
const axios = require("axios");
async function getAssistant() {
const response = await axios.get(
"https://api.odeus.ai/assistant/v1/get",
{
params: {
assistantId: "550e8400-e29b-41d4-a716-446655440000"
},
headers: {
Authorization: "Bearer YOUR_API_KEY"
}
}
);
console.log("Assistant details:", response.data.assistant);
}
Validation Rules
The API enforces the following 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
Response Format
Success Response (200 OK)
{
status: "success";
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;
}>;
attachments: string[];
createdAt: string;
updatedAt: string;
};
}
Error Handling
try {
const response = await axios.get('https://api.odeus.ai/assistant/v1/get', ...);
} catch (error) {
if (error.response) {
switch (error.response.status) {
case 400:
console.error('Invalid Assistant ID format');
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');
break;
case 500:
console.error('Server error');
break;
}
}
}
Migrating to Agents API
The new Agents API offers improved compatibility with modern AI SDKs. The get endpoint has similar functionality with updated parameter names.
See the equivalent endpoint in the Agents API:
- Agent Get 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/get:
get:
tags:
- Assistant Build
summary: '[Deprecated] Retrieves details of an existing assistant'
description: >-
This endpoint is deprecated. Please use /agent/v1/get for new
integrations. Retrieves the complete configuration and details of an
existing assistant.
operationId: getAgent
parameters:
- name: assistantId
in: query
required: true
description: UUID of the agent to retrieve
schema:
type: string
format: uuid
responses:
'200':
description: Agent details retrieved successfully
content:
application/json:
schema:
type: object
required:
- status
- agent
properties:
status:
type: string
enum:
- success
assistant:
$ref: '#/components/schemas/AssistantDetails'
'400':
description: Invalid assistant ID format
content:
application/json:
schema:
type: object
properties:
message:
type: string
'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
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"