API Reference

Agents

Create and configure AI agents for your applications. Define prompts, configure models, assign tools, and manage settings all through the API.

Overview

What You Can Do:

  • Create agents with custom prompts and descriptions
  • Configure model settings (temperature, max tokens, etc.)
  • Assign tools (web search, calculator, custom tools)
  • Manage guest limits and rate limiting
  • Track analytics and usage statistics
  • Organize agents by namespace

Agent Structure:

  • Prompts - Identity, rules, and guidelines
  • Settings - Model config, switches, tools, limits
  • Analytics - Usage stats, sessions, token tracking
  • Users - End-user management and limits

API Usage

Create Agent

Create a new AI agent with prompts and optional settings. Use namespace to organize agents by workspace or application.

import { OblienClient } from 'oblien';
import { OblienAgents } from 'oblien/agents';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const agents = new OblienAgents(client);

const agent = await agents.create({
  name: 'Support Agent',
  description: 'Customer support AI assistant',
  namespace: 'production',
  prompts: {
    identity: 'You are a helpful customer support agent.',
    rules: 'Always be professional and clear.',
    guidelines: 'Provide actionable solutions to customer problems.'
  },
  collectionIds: ['col-123'],
  settings: {
    model: 'oblien-master',
    temperature: 0.7,
    max_tokens: 2000
  }
});

console.log('Agent created:', agent.agentId);
const response = await fetch('https://api.oblien.com/ai/agents/create', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Support Agent',
    description: 'Customer support AI assistant',
    namespace: 'production',
    prompts: {
      identity: 'You are a helpful customer support agent.',
      rules: 'Always be professional and clear.',
      guidelines: 'Provide actionable solutions to customer problems.'
    },
    collectionIds: ['col-123'],
    settings: {
      model: 'oblien-master',
      temperature: 0.7,
      max_tokens: 2000
    }
  })
});

const agent = await response.json();
console.log('Agent created:', agent.agentId);
curl -X POST https://api.oblien.com/ai/agents/create \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Customer support AI assistant",
    "namespace": "production",
    "prompts": {
      "identity": "You are a helpful customer support agent.",
      "rules": "Always be professional and clear.",
      "guidelines": "Provide actionable solutions to customer problems."
    },
    "collectionIds": ["col-123"],
    "settings": {
      "model": "oblien-master",
      "temperature": 0.7,
      "max_tokens": 2000
    }
  }'

Response:

{
  "agentId": "agent-abc123",
  "name": "Support Agent",
  "description": "Customer support AI assistant",
  "namespace": "production",
  "createdAt": "2024-01-15T10:00:00Z"
}

List Agents

Get all agents for your account. Filter by namespace to get agents for a specific workspace.

const result = await agents.list({
  namespace: 'production',
  limit: 50,
  offset: 0
});

console.log('Agents:', result.agents);
console.log('Has more:', result.has_more);
const response = await fetch('https://api.oblien.com/ai/agents/list?namespace=production&limit=50&offset=0', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const result = await response.json();
console.log('Agents:', result.agents);
curl -X GET "https://api.oblien.com/ai/agents/list?namespace=production&limit=50&offset=0" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "agents": [
    {
      "agent_id": "agent-abc123",
      "agent_name": "Support Agent",
      "agent_description": "Customer support AI assistant",
      "namespace": "production",
      "created_at": "2024-01-15T10:00:00Z",
      "collections": []
    }
  ],
  "has_more": false
}

Get Agent

Get agent details. Optionally specify a section to get only specific parts (e.g., 'prompts').

// Get full agent
const agent = await agents.get('agent-abc123');
console.log(agent);

// Get specific section
const prompts = await agents.get('agent-abc123', 'prompts');
console.log(prompts);
// Get full agent
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const agent = await response.json();
console.log(agent);

// Get specific section
const promptsResponse = await fetch('https://api.oblien.com/ai/agents/agent-abc123/prompts', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const prompts = await promptsResponse.json();
console.log(prompts);
# Get full agent
curl -X GET "https://api.oblien.com/ai/agents/agent-abc123" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

# Get specific section
curl -X GET "https://api.oblien.com/ai/agents/agent-abc123/prompts" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "agent": {
    "agent_id": "agent-abc123",
    "agent_name": "Support Agent",
    "agent_description": "Customer support AI assistant",
    "namespace": "production",
    "prompts": {
      "identity": "You are a helpful customer support agent.",
      "rules": "Always be professional and clear.",
      "guidelines": "Provide actionable solutions to customer problems."
    },
    "settings": {
      "model": "oblien-master",
      "temperature": 0.7,
      "max_tokens": 2000,
      "enable_memory": true,
      "allow_thinking": true
    },
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Update Agent

Update agent name, description, or prompts. Settings are updated separately through the settings endpoints.

const updated = await agents.update('agent-abc123', {
  name: 'Updated Support Agent',
  description: 'Updated description',
  prompts: {
    identity: 'You are an expert support agent.',
    rules: 'Be helpful and concise.'
  }
});

console.log('Agent updated:', updated);
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123', {
  method: 'PUT',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Updated Support Agent',
    description: 'Updated description',
    prompts: {
      identity: 'You are an expert support agent.',
      rules: 'Be helpful and concise.'
    }
  })
});

const updated = await response.json();
console.log('Agent updated:', updated);
curl -X PUT https://api.oblien.com/ai/agents/agent-abc123 \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Support Agent",
    "description": "Updated description",
    "prompts": {
      "identity": "You are an expert support agent.",
      "rules": "Be helpful and concise."
    }
  }'

Response:

{
  "success": true,
  "agentId": "agent-abc123",
  "message": "Agent updated successfully"
}

Delete Agent

Delete an agent. Optionally provide namespace for validation.

const result = await agents.delete('agent-abc123', {
  namespace: 'production'
});

console.log('Agent deleted:', result);
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123', {
  method: 'DELETE',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    namespace: 'production'
  })
});

const result = await response.json();
console.log('Agent deleted:', result);
curl -X DELETE https://api.oblien.com/ai/agents/agent-abc123 \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "production"
  }'

Response:

{
  "success": true,
  "message": "Agent deleted successfully"
}

Search Agents

Search agents by name or description.

const results = await agents.search('support', {
  namespace: 'production',
  limit: 20
});

console.log('Search results:', results.agents);
const response = await fetch('https://api.oblien.com/ai/agents/search?q=support&namespace=production&limit=20', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const results = await response.json();
console.log('Search results:', results.agents);
curl -X GET "https://api.oblien.com/ai/agents/search?q=support&namespace=production&limit=20" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "agents": [
    {
      "agent_id": "agent-abc123",
      "agent_name": "Support Agent",
      "agent_description": "Customer support AI assistant",
      "namespace": "production"
    }
  ]
}

Settings Management

Agent settings control how your agent behaves, what capabilities it has, and how it manages resources. Settings are organized into 5 sections, each with its own endpoint and validation.

Access Settings:

const agent = agents.agent('agent-abc123');
const settings = agent.settings;

1. Switches (Boolean Toggles)

Control agent features with boolean switches. These settings enable or disable core capabilities.

Available Switches:

  • enable_memory - Enable conversation memory. When enabled, the agent remembers previous messages in the conversation.
  • allow_thinking - Allow thinking process. Enables the agent to show its reasoning process before responding.
  • allow_images - Allow image uploads. Users can upload image files for the agent to process.
  • allow_videos - Allow video uploads. Users can upload video files for the agent to process.
  • allow_audio - Allow audio uploads. Users can upload audio files for the agent to process.
  • allow_documents - Allow document uploads. Users can upload PDF, DOCX, and other document files.
  • allow_built_in - Allow built-in tools. Enables system-provided tools (web search, calculator, etc.).

Default Values:

  • enable_memory: true (enabled by default)
  • allow_thinking: true (enabled by default)
  • allow_images: false
  • allow_videos: false
  • allow_audio: false
  • allow_documents: false
  • allow_built_in: false

Update Switches

Update boolean toggles for agent features.

const agent = agents.agent('agent-abc123');

await agent.settings.updateSwitches({
  enable_memory: true,
  allow_thinking: true,
  allow_images: true,
  allow_videos: false,
  allow_audio: false,
  allow_documents: true,
  allow_built_in: true
});

console.log('Switches updated');
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/switches', {
  method: 'PUT',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    enable_memory: true,
    allow_thinking: true,
    allow_images: true,
    allow_videos: false,
    allow_audio: false,
    allow_documents: true,
    allow_built_in: true
  })
});

const result = await response.json();
console.log('Switches updated:', result);
curl -X PUT https://api.oblien.com/ai/agents/agent-abc123/switches \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_memory": true,
    "allow_thinking": true,
    "allow_images": true,
    "allow_videos": false,
    "allow_audio": false,
    "allow_documents": true,
    "allow_built_in": true
  }'

Response:

{
  "success": true,
  "message": "Switches updated successfully"
}

2. Model Configuration

Control the AI model behavior and response generation. These settings affect how the agent generates responses.

Available Settings:

  • model (string) - Model name to use. Options:
    • oblien-master - Most powerful model, best for complex tasks
    • oblien-light - Fast and efficient, best for simple tasks
  • temperature (number, 0-2, default: 1) - Controls randomness in responses. Lower values (0-0.5) make responses more focused and deterministic. Higher values (1-2) make responses more creative and varied.
  • max_tokens (number, 1-200000, default: 2000) - Maximum number of tokens in the response. Higher values allow longer responses but consume more credits.
  • top_p (number, 0-1, default: 1) - Nucleus sampling parameter. Controls diversity by considering only tokens with cumulative probability up to this value.

Recommendations:

  • Use oblien-master for complex reasoning, analysis, and creative tasks
  • Use oblien-light for simple Q&A, quick responses, and cost-sensitive applications
  • Set temperature to 0.7-0.9 for balanced responses
  • Set temperature to 0.3-0.5 for factual, consistent responses
  • Set max_tokens based on expected response length (1000-2000 for most use cases)

Update Model Configuration

Configure the AI model settings.

const agent = agents.agent('agent-abc123');

await agent.settings.updateModelConfig({
  model: 'oblien-master',
  temperature: 0.7,
  max_tokens: 2000,
  top_p: 0.9
});

console.log('Model config updated');
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/model-config', {
  method: 'PUT',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'oblien-master',
    temperature: 0.7,
    max_tokens: 2000,
    top_p: 0.9
  })
});

const result = await response.json();
console.log('Model config updated:', result);
curl -X PUT https://api.oblien.com/ai/agents/agent-abc123/model-config \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "oblien-master",
    "temperature": 0.7,
    "max_tokens": 2000,
    "top_p": 0.9
  }'

Response:

{
  "success": true,
  "message": "Model configuration updated successfully"
}

3. Tools Assignment

Assign tools to your agent to extend its capabilities. Tools allow agents to perform actions like web search, file operations, calculations, and custom integrations.

Before Assigning Tools:

  1. Browse available tools using the Tools API
  2. Validate tool IDs to ensure they exist
  3. Assign validated tools to your agent

Tool Limits:

  • Maximum 100 tools per agent
  • Tools must be validated before assignment
  • Invalid tool IDs will be rejected

See Tools Documentation for:

  • Listing available tools
  • Creating custom tools
  • Validating tool IDs
  • Tool types and categories

Update Tools

Assign tools to your agent. Tools must be validated first using the Tools API.

const agent = agents.agent('agent-abc123');

// First, browse and validate tools (see Tools API)
import { OblienTools } from 'oblien/tools';
const tools = new OblienTools(client);

const validation = await tools.validate(['web-search', 'calculator']);
if (validation.valid) {
  await agent.settings.updateTools(validation.validIds);
  console.log('Tools updated');
} else {
  console.error('Invalid tools:', validation.invalidIds);
}
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/tools', {
  method: 'PUT',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tools: ['web-search', 'calculator', 'file-read']
  })
});

const result = await response.json();
console.log('Tools updated:', result);
curl -X PUT https://api.oblien.com/ai/agents/agent-abc123/tools \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": ["web-search", "calculator", "file-read"]
  }'

Response:

{
  "success": true,
  "message": "Tools updated successfully"
}

4. Guest Limits

Configure rate limiting for anonymous/guest users. These limits prevent abuse and control resource usage for unauthenticated users.

Available Limits:

  • enabled (boolean) - Enable or disable guest limits. When disabled, no limits are enforced.
  • max_requests_per_minute (number, 1-1000) - Maximum API requests per minute per guest.
  • max_messages_per_hour (number, 1-10000) - Maximum chat messages per hour per guest.
  • max_messages_per_day (number, 1-50000) - Maximum chat messages per day per guest.
  • max_total_tokens_per_day (number, 1000-10000000) - Maximum total tokens (input + output) per day per guest.
  • max_input_tokens_per_day (number, 1000-10000000) - Maximum input tokens per day per guest.
  • max_output_tokens_per_day (number, 1000-10000000) - Maximum output tokens per day per guest.

Default Limits (when enabled):

  • 100K tokens per day
  • 50 messages per day
  • 20 messages per hour

Best Practices:

  • Set reasonable limits based on your use case
  • Monitor guest usage to adjust limits
  • Use token limits to control costs
  • Combine message and token limits for better control

Update Guest Limits

Configure rate limits for guest users.

const agent = agents.agent('agent-abc123');

await agent.settings.updateGuestLimits({
  enabled: true,
  max_requests_per_minute: 60,
  max_messages_per_hour: 100,
  max_messages_per_day: 1000,
  max_total_tokens_per_day: 50000,
  max_input_tokens_per_day: 25000,
  max_output_tokens_per_day: 25000
});

console.log('Guest limits updated');
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/guest-limits', {
  method: 'PUT',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    enabled: true,
    max_requests_per_minute: 60,
    max_messages_per_hour: 100,
    max_messages_per_day: 1000,
    max_total_tokens_per_day: 50000,
    max_input_tokens_per_day: 25000,
    max_output_tokens_per_day: 25000
  })
});

const result = await response.json();
console.log('Guest limits updated:', result);
curl -X PUT https://api.oblien.com/ai/agents/agent-abc123/guest-limits \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "max_requests_per_minute": 60,
    "max_messages_per_hour": 100,
    "max_messages_per_day": 1000,
    "max_total_tokens_per_day": 50000,
    "max_input_tokens_per_day": 25000,
    "max_output_tokens_per_day": 25000
  }'

Response:

{
  "success": true,
  "message": "Guest limits updated successfully"
}

5. Context Settings

Manage conversation history and context memory. Context includes conversation history, uploaded files, memory variables, and action queues.

Available Settings:

  • max_history_messages (number, default: 50) - Maximum number of conversation messages to keep in context. Older messages are removed when this limit is reached.
  • history_token_limit (number, default: 4000) - Maximum tokens for conversation history. When exceeded, older messages are summarized or removed.
  • summarize_history_on_token_limit (boolean) - Automatically summarize old conversations when token limit is reached. Helps maintain context while reducing token usage.
  • keep_files_in_context (boolean) - Keep uploaded files in context across messages. When disabled, files are removed after processing.
  • keep_memory_variables (boolean, default: true) - Persist memory variables across conversations. Memory variables store user preferences and session data.
  • keep_action_queue (boolean, default: true) - Maintain pending operations between requests. Action queue stores operations that need to be completed.
  • latest_file_version_only (boolean, default: true) - Keep only the latest version of files in context. Reduces token usage for frequently updated files.
  • workspace_type (string) - Workspace type for file operations. Options: none, project, sandbox.

Context Management: Context is the agent's working memory. It includes:

  • Conversation History - Previous messages between user and agent
  • Uploaded Files - Files uploaded by users and their content
  • Memory Variables - Persistent data like user preferences
  • Action Queue - Pending operations waiting to be executed

Token Optimization:

  • Use max_history_messages to limit message count
  • Use history_token_limit to limit token usage
  • Enable summarize_history_on_token_limit to maintain context while reducing tokens
  • Set latest_file_version_only to true for frequently updated files

Update Context Settings

Configure conversation history and context limits.

const agent = agents.agent('agent-abc123');

await agent.settings.updateContext({
  max_history_messages: 50,
  history_token_limit: 4000,
  summarize_history_on_token_limit: true,
  keep_files_in_context: false,
  keep_memory_variables: true,
  keep_action_queue: true,
  latest_file_version_only: true,
  workspace_type: 'none'
});

console.log('Context settings updated');
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/context', {
  method: 'PUT',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    max_history_messages: 50,
    history_token_limit: 4000,
    summarize_history_on_token_limit: true,
    keep_files_in_context: false,
    keep_memory_variables: true,
    keep_action_queue: true,
    latest_file_version_only: true,
    workspace_type: 'none'
  })
});

const result = await response.json();
console.log('Context settings updated:', result);
curl -X PUT https://api.oblien.com/ai/agents/agent-abc123/context \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "max_history_messages": 50,
    "history_token_limit": 4000,
    "summarize_history_on_token_limit": true,
    "keep_files_in_context": false,
    "keep_memory_variables": true,
    "keep_action_queue": true,
    "latest_file_version_only": true,
    "workspace_type": "none"
  }'

Response:

{
  "success": true,
  "message": "Context settings updated successfully"
}

Analytics & Monitoring

Get Agent Overview

Get analytics and usage statistics for an agent.

const agent = agents.agent('agent-abc123');

const overview = await agent.getOverview({
  days: 7
});

console.log('Total chats:', overview.analytics.total_chats);
console.log('Total messages:', overview.analytics.total_messages);
console.log('Total tokens:', overview.analytics.total_tokens);
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/overview?days=7', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const overview = await response.json();
console.log('Analytics:', overview.analytics);
curl -X GET "https://api.oblien.com/ai/agents/agent-abc123/overview?days=7" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "analytics": {
    "total_chats": 1847,
    "total_messages": 12453,
    "total_tokens": 3847291,
    "total_apps": 5,
    "usage_data": [
      {
        "date": "2024-01-15",
        "chats": 145,
        "messages": 980
      },
      {
        "date": "2024-01-16",
        "chats": 178,
        "messages": 1205
      }
    ]
  }
}

Get Agent Sessions

Get all sessions for an agent with filtering and pagination.

const agent = agents.agent('agent-abc123');

const sessions = await agent.getSessions({
  limit: 50,
  offset: 0,
  search: 'user-123',
  sortBy: 'created_at',
  sortOrder: 'desc'
});

console.log('Sessions:', sessions.sessions);
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/sessions?limit=50&offset=0&search=user-123&sortBy=created_at&sortOrder=desc', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const sessions = await response.json();
console.log('Sessions:', sessions.sessions);
curl -X GET "https://api.oblien.com/ai/agents/agent-abc123/sessions?limit=50&offset=0&search=user-123&sortBy=created_at&sortOrder=desc" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "sessions": [
    {
      "sessionId": "session-abc123",
      "endUserId": "user-789",
      "namespace": "production",
      "createdAt": "2024-01-15T10:00:00Z",
      "lastActiveAt": "2024-01-15T11:30:00Z"
    }
  ],
  "has_more": false
}

Get Platform Stats

Get platform-wide statistics across all agents.

const stats = await agents.getStats();
console.log('Platform stats:', stats);
const response = await fetch('https://api.oblien.com/ai/agents/stats', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const stats = await response.json();
console.log('Platform stats:', stats);
curl -X GET "https://api.oblien.com/ai/agents/stats" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "stats": {
    "total_agents": 42,
    "total_sessions": 12500,
    "total_messages": 85000,
    "total_tokens": 25000000
  }
}

User Management

Get Agent Users

Get all users who have interacted with an agent.

const agent = agents.agent('agent-abc123');

const users = await agent.getUsers({
  limit: 50,
  offset: 0
});

console.log('Users:', users);
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/users?limit=50&offset=0', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const users = await response.json();
console.log('Users:', users);
curl -X GET "https://api.oblien.com/ai/agents/agent-abc123/users?limit=50&offset=0" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "users": [
    {
      "userId": "user-789",
      "namespace": "production",
      "totalSessions": 15,
      "totalMessages": 120,
      "totalTokens": 45000,
      "lastActiveAt": "2024-01-15T11:30:00Z"
    }
  ]
}

Get Agent User

Get details for a specific user.

const agent = agents.agent('agent-abc123');

const user = await agent.getUser('user-789');
console.log('User details:', user);
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/users/user-789', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const user = await response.json();
console.log('User details:', user);
curl -X GET "https://api.oblien.com/ai/agents/agent-abc123/users/user-789" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "user": {
    "userId": "user-789",
    "namespace": "production",
    "totalSessions": 15,
    "totalMessages": 120,
    "totalTokens": 45000,
    "lastActiveAt": "2024-01-15T11:30:00Z",
    "limits": {
      "maxMessagesPerDay": 1000,
      "maxTokensPerDay": 50000
    }
  }
}

Reset User Limits

Reset rate limits for a specific user.

const agent = agents.agent('agent-abc123');

const result = await agent.resetUserLimits('user-789');
console.log('Limits reset:', result);
const response = await fetch('https://api.oblien.com/ai/agents/agent-abc123/users/user-789/reset-limits', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const result = await response.json();
console.log('Limits reset:', result);
curl -X POST "https://api.oblien.com/ai/agents/agent-abc123/users/user-789/reset-limits" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "message": "User limits reset successfully"
}

Best Practices

Agent Creation:

  • Use descriptive names and clear prompts
  • Organize agents by namespace (workspace, app, environment)
  • Set appropriate model settings for your use case
  • Enable memory and thinking for complex conversations

Settings Management:

  • Configure guest limits to prevent abuse
  • Use Tools API to browse and validate tools before assigning
  • Set context limits to manage token usage
  • Test model configurations before production
  • Enable memory and thinking for complex conversations

Analytics:

  • Monitor agent usage regularly
  • Track token consumption per agent
  • Review user activity and limits
  • Use platform stats for capacity planning

Next Steps

  • Tools - Browse and create tools for your agents
  • Sessions - Create chat sessions for your agents
  • Credits - Manage billing and quotas
  • SDK Setup - Complete SDK documentation

API Reference

Complete reference for the Oblien API

Credits & Billing

Complete credits system with two-level quota management for namespace and end users

On this page

Agents
Overview
API Usage
Create Agent
List Agents
Get Agent
Update Agent
Delete Agent
Search Agents
Settings Management
1. Switches (Boolean Toggles)
Update Switches
2. Model Configuration
Update Model Configuration
3. Tools Assignment
Update Tools
4. Guest Limits
Update Guest Limits
5. Context Settings
Update Context Settings
Analytics & Monitoring
Get Agent Overview
Get Agent Sessions
Get Platform Stats
User Management
Get Agent Users
Get Agent User
Reset User Limits
Best Practices
Next Steps