Skip to main content
GET
/
agents
/
{agentId}
Get Agent
curl --request GET \
  --url https://api.example.com/agents/{agentId}
{
  "success": true,
  "data": {
    "data.agentId": "<string>",
    "data.name": "<string>",
    "data.status": "<string>",
    "data.bio": "<string>",
    "data.lore": [
      {}
    ],
    "data.topics": [
      {}
    ],
    "data.adjectives": [
      {}
    ],
    "data.style": {},
    "data.settings": {},
    "data.plugins": [
      {}
    ],
    "data.enabled": true,
    "data.createdAt": 123,
    "data.updatedAt": 123
  }
}

Endpoint

GET /agents/{agentId}
Retrieves detailed information about a specific agent, including its character configuration, status, and runtime settings.

Request

Path Parameters

agentId
string
required
Unique identifier (UUID) of the agent to retrieve

Headers

Authorization
string
Bearer token for authentication (if required)

Response

success
boolean
required
Indicates if the request was successful
data
object
required
Agent details
data.agentId
string
required
Unique identifier for the agent (UUID)
data.name
string
required
Name of the agent’s character
data.status
string
required
Current status: active or inactive
data.bio
string
Biography or description of the agent
data.lore
array
Background story elements
data.topics
array
Topics the agent is knowledgeable about
data.adjectives
array
Personality adjectives
data.style
object
Communication style settings
data.settings
object
Agent configuration settings
data.plugins
array
Enabled plugins
data.enabled
boolean
Whether the agent is enabled
data.createdAt
number
Unix timestamp when the agent was created
data.updatedAt
number
Unix timestamp when the agent was last updated

Examples

Basic Request

curl -X GET http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json"

With Authentication

curl -X GET http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

Success Response

{
  "success": true,
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Alice",
    "status": "active",
    "bio": "A helpful AI assistant specializing in customer support",
    "lore": [
      "Has extensive training in customer service",
      "Specializes in resolving user issues quickly",
      "Known for empathy and understanding"
    ],
    "topics": [
      "customer support",
      "product knowledge",
      "troubleshooting"
    ],
    "adjectives": [
      "helpful",
      "patient",
      "knowledgeable",
      "friendly"
    ],
    "style": {
      "all": [
        "Be concise and clear",
        "Show empathy for user concerns",
        "Provide actionable solutions"
      ],
      "chat": [
        "Use a warm, conversational tone",
        "Ask clarifying questions when needed"
      ]
    },
    "settings": {
      "model": "gpt-4",
      "embeddingModel": "text-embedding-3-small"
    },
    "plugins": ["bootstrap"],
    "enabled": true,
    "createdAt": 1709510400000,
    "updatedAt": 1709596800000
  }
}

Code Examples

JavaScript/Node.js

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`http://localhost:3000/agents/${agentId}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const { success, data } = await response.json();

if (success) {
  console.log(`Agent: ${data.name}`);
  console.log(`Status: ${data.status}`);
  console.log(`Bio: ${data.bio}`);
}

Python

import requests

agent_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(f'http://localhost:3000/agents/{agent_id}')
data = response.json()

if data['success']:
    agent = data['data']
    print(f"Agent: {agent['name']}")
    print(f"Status: {agent['status']}")
    print(f"Bio: {agent['bio']}")

TypeScript

interface Agent {
  agentId: string;
  name: string;
  status: 'active' | 'inactive';
  bio?: string;
  lore?: string[];
  topics?: string[];
  adjectives?: string[];
  style?: {
    all?: string[];
    chat?: string[];
    post?: string[];
  };
  settings?: Record<string, any>;
  plugins?: string[];
  enabled?: boolean;
  createdAt?: number;
  updatedAt?: number;
}

interface GetAgentResponse {
  success: boolean;
  data: Agent;
}

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`http://localhost:3000/agents/${agentId}`);
const { success, data }: GetAgentResponse = await response.json();

if (success) {
  console.log(`Agent: ${data.name}`);
}

Error Responses

404 Not Found

{
  "success": false,
  "error": "Agent not found"
}

400 Bad Request

{
  "success": false,
  "error": "Invalid agent ID format"
}

500 Internal Server Error

{
  "success": false,
  "error": "Failed to retrieve agent"
}

Next Steps

Update Agent

Modify agent configuration

Start Agent

Start the agent’s runtime

Send Message

Interact with the agent

Delete Agent

Remove the agent

Build docs developers (and LLMs) love