Agent Get API

Retrieve details of an existing agent

⚠️ Using our API via a dedicated deployment? Just replace api.odeus.ai with your deployment's base URL: <deployment-url>/api/public

This is the new Agents API with native Vercel AI SDK compatibility. If you're using the legacy Assistants API, see the migration guide.

Returns the agent's active (published) version. If the agent has never been published, returns the current draft instead.

Retrieves the complete configuration and details of an existing agent in your workspace.

Requires an API key with the AGENT_API scope and access to the agent you want to retrieve.

Query Parameters

Parameter	Type	Required	Description
agentId	string	Yes	UUID of the agent to retrieve

Examples

Basic Retrieval

const axios = require("axios");

async function getAgent() {
  const response = await axios.get(
    "https://api.odeus.ai/agent/v1/get",
    {
      params: {
        agentId: "550e8400-e29b-41d4-a716-446655440000"
      },
      headers: {
        Authorization: "Bearer YOUR_API_KEY"
      }
    }
  );

  console.log("Agent details:", response.data.agent);
}

Validation Rules

The API enforces the following validation rules:

• Agent access - Your API key must have access to the agent
• Workspace match - Agent must belong to the same workspace as your API key

Response Format

Success Response (200 OK)

{
  status: "success";
  agent: {
    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/agent/v1/get', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid agent ID format');
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('Insufficient permissions - no access to this agent');
        break;
      case 404:
        console.error('Agent not found');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

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:
  /agent/v1/get:
    get:
      tags:
        - Agent Build
      summary: Retrieves details of an existing agent
      description: Retrieves the complete configuration and details of an existing agent.
      operationId: getAgentV2
      parameters:
        - name: agentId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Agent retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  agent:
                    $ref: '#/components/schemas/Assistant'
components:
  schemas:
    Assistant:
      type: object
      required:
        - name
        - instructions
      properties:
        name:
          type: string
          maxLength: 64
        description:
          type: string
          maxLength: 256
        instructions:
          type: string
          maxLength: 16384
        temperature:
          type: number
          minimum: 0
          maximum: 1
        model:
          type: string
          maxLength: 64
        capabilities:
          type: object
          properties:
            webSearch:
              type: boolean
            dataAnalyst:
              type: boolean
            imageGeneration:
              type: boolean
        actions:
          type: array
          items: fcf0fd67-fd0e-4a00-b735-68e73c7eacb2
        vectorDb:
          type: array
          items: f0c033f7-804b-4122-8a48-a9c1f45fd570
        knowledgeFolderIds:
          type: array
          items:
            type: string
        attachmentIds:
          type: array
          items:
            type: string
            format: uuid
          description: Array of UUID strings identifying attachments for this message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"