> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boostgpt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Core SDK API Reference

> Complete reference for all Core SDK methods

## Constructor

```javascript theme={null}
const client = new BoostGPT({
  key: string,           // Required: API key
  project_id: string     // Required: Project ID
});
```

***

## Bot Management

### createBot()

Create a new AI bot.

```javascript theme={null}
await client.createBot({
  name: 'Bot Name',
  model: 'gpt-5.1',
  instruction: 'System instruction',
  max_reply_tokens: 1000,
  reasoning_mode: 'auto',
  status: 'active'
});
```

<ParamField path="name" type="string" required>
  Display name for your bot
</ParamField>

<ParamField path="model" type="string" required>
  AI model to use: `gpt-5.1`, `gpt-5-mini`, `claude-3.7-sonnet`, `gemini-2.0-flash`, etc.
</ParamField>

<ParamField path="instruction" type="string" required>
  System instruction guiding the AI's behavior
</ParamField>

<ParamField path="max_reply_tokens" type="number" default="1000">
  Maximum tokens in AI responses
</ParamField>

<ParamField path="reasoning_mode" type="string">
  Reasoning mode: `auto`, `standard`, `agent`
</ParamField>

<ParamField path="status" type="string" default="active">
  Bot status: `active` or `inactive`
</ParamField>

***

### fetchBot()

Get a bot's configuration.

```javascript theme={null}
await client.fetchBot(bot_id);
```

<ParamField path="bot_id" type="string" required>
  ID of the bot to fetch
</ParamField>

***

### fetchBots()

Get all bots in a project (paginated).

```javascript theme={null}
await client.fetchBots({
  page: 1,
  per_page: 10
});
```

<ParamField path="page" type="number" default="1">
  Page number
</ParamField>

<ParamField path="per_page" type="number" default="10">
  Items per page
</ParamField>

***

### updateBot()

Update a bot's configuration.

```javascript theme={null}
await client.updateBot({
  bot_id: 'bot-123',
  name: 'Updated Name',
  model: 'gpt-5.1',
  instruction: 'New instruction',
  max_reply_tokens: 1500,
  reasoning_mode: 'agent',
  status: 'active'
});
```

All parameters same as `createBot()`, plus:

<ParamField path="bot_id" type="string" required>
  ID of the bot to update
</ParamField>

***

### resetBot()

Delete all training data from a bot.

```javascript theme={null}
await client.resetBot(bot_id);
```

<Warning>
  This permanently deletes all training sources and cannot be undone.
</Warning>

***

### deleteBot()

Delete a bot permanently.

```javascript theme={null}
await client.deleteBot(bot_id);
```

<Warning>
  This permanently deletes the bot, its training data, and chat history.
</Warning>

***

## Chat Operations

### chat()

Send a message and get an AI response.

```javascript theme={null}
await client.chat({
  bot_id: 'bot-123',
  message: 'Hello!',
  chat_id: 'user-456',
  stream: false,
  memory: true,
  model: 'gpt-5.1',
  provider_key: 'optional-key',
  provider_host: 'http://localhost:11434', // For Ollama
  instruction: 'Optional override',
  source_ids: ['source1', 'source2'],
  reasoning_mode: 'agent',
  max_reply_tokens: 1000
});
```

<ParamField path="bot_id" type="string" required>
  ID of the bot to chat with
</ParamField>

<ParamField path="message" type="string" required>
  User's message
</ParamField>

<ParamField path="chat_id" type="string">
  Unique ID for conversation continuity
</ParamField>

<ParamField path="stream" type="boolean" default="false">
  Enable streaming responses
</ParamField>

<ParamField path="memory" type="boolean" default="true">
  Use agent's training data/memory
</ParamField>

<ParamField path="model" type="string">
  Override bot's default model
</ParamField>

<ParamField path="provider_key" type="string">
  Use your own API key (BYOK)
</ParamField>

<ParamField path="provider_host" type="string">
  Provider host URL (required for Ollama)
</ParamField>

<ParamField path="instruction" type="string">
  Override bot's default instruction
</ParamField>

<ParamField path="source_ids" type="array">
  Limit knowledge to specific sources
</ParamField>

<ParamField path="reasoning_mode" type="string">
  Override reasoning mode: `auto`, `standard`, `agent`
</ParamField>

<ParamField path="max_reply_tokens" type="number">
  Override bot's default token limit
</ParamField>

<ParamField path="chat_mode" type="string" default="ask">
  Chat mode: `ask` for normal chat, `edit` for agent-powered code editing, `plan` for conversational planning before tool execution. Edit mode routes through the agent reasoning pipeline to make targeted file changes. Plan mode proposes a step-by-step plan for review before executing. Both `edit` and `plan` require workspace to be enabled — if disabled, requests fall back to `ask`.
</ParamField>

**Response:**

```javascript theme={null}
{
  err: null,
  response: {
    chat: {
      reply: "AI response text",
      // ... other fields
    }
  }
}
```

***

### fetchChat()

Get chat history for a conversation.

```javascript theme={null}
await client.fetchChat({
  bot_id: 'bot-123',
  chat_id: 'user-456',
  page: 1,
  per_page: 20
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="chat_id" type="string" required>
  Chat/conversation ID
</ParamField>

<ParamField path="page" type="number" default="1">
  Page number
</ParamField>

<ParamField path="per_page" type="number" default="20">
  Messages per page
</ParamField>

***

### fetchChats()

Get all chats for a bot.

```javascript theme={null}
await client.fetchChats({
  bot_id: 'bot-123',
  page: 1,
  per_page: 10
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="page" type="number" default="1">
  Page number
</ParamField>

<ParamField path="per_page" type="number" default="10">
  Chats per page
</ParamField>

***

### deleteChat()

Delete a chat history.

```javascript theme={null}
await client.deleteChat({
  chat_id: 'user-456',
  bot_id: 'bot-123'
});
```

<ParamField path="chat_id" type="string" required>
  Chat ID to delete
</ParamField>

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### executeTool()

Execute tool calls for a chat.

```javascript theme={null}
await client.executeTool({
  bot_id: 'bot-123',
  chat_id: 'chat-456',
  tool_calls: [
    {
      tool_name: 'calculator',
      parameters: { operation: 'add', a: 5, b: 3 }
    }
  ]
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="chat_id" type="string" required>
  Chat ID
</ParamField>

<ParamField path="tool_calls" type="array" required>
  Array of tool call objects with `tool_name` and `parameters`
</ParamField>

***

### voteMessage()

Vote on a message (upvote/downvote).

```javascript theme={null}
await client.voteMessage({
  bot_id: 'bot-123',
  message_id: 'msg-456',
  voter_id: 'user-789',
  voter_type: 'member',
  vote_type: 'upvote' // or 'downvote'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="message_id" type="string" required>
  Message ID to vote on
</ParamField>

<ParamField path="voter_id" type="string" required>
  ID of the user voting
</ParamField>

<ParamField path="voter_type" type="string" required>
  Type of voter (e.g., 'member')
</ParamField>

<ParamField path="vote_type" type="string" required>
  Vote type: 'upvote' or 'downvote'
</ParamField>

***

### fetchVoteStatus()

Get the vote status for a message.

```javascript theme={null}
await client.fetchVoteStatus({
  bot_id: 'bot-123',
  message_id: 'msg-456',
  voter_id: 'user-789',
  voter_type: 'member'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="message_id" type="string" required>
  Message ID
</ParamField>

<ParamField path="voter_id" type="string" required>
  Voter ID
</ParamField>

<ParamField path="voter_type" type="string" required>
  Voter type
</ParamField>

***

### deleteMessage()

Delete a specific message.

```javascript theme={null}
await client.deleteMessage({
  bot_id: 'bot-123',
  chat_id: 'chat-456',
  message_id: 'msg-789'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="chat_id" type="string" required>
  Chat ID
</ParamField>

<ParamField path="message_id" type="string" required>
  Message ID to delete
</ParamField>

***

## Training & Sources

### startTraining()

Add training data to a bot.

```javascript theme={null}
await client.startTraining({
  bot_id: 'bot-123',
  type: 'text',
  source: 'Your training content here'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="type" type="string" default="text">
  Source type: `text`, `website`, `file`, `webpage`
</ParamField>

<ParamField path="source" type="string | array" required>
  * `text`: String content
  * `website`: String URL to crawl
  * `file`: Array of file paths
  * `webpage`: Array of URLs
</ParamField>

**Response:**

Training is queued and returns status:

```javascript theme={null}
{
  err: null,
  response: {
    id: 'source_xyz789',
    bot_id: 'bot_abc123',
    source: 'Training content...',
    type: 'text',
    status: 'processing', // 'processing', 'success', or 'failed'
    tokens: 150,
    created_at: '2025-01-01T12:00:00Z'
    // For website, file, webpage types:
    // links: ['https://example.com/page1', ...]
  }
}
```

***

### fetchTraining()

Get a specific training source.

```javascript theme={null}
await client.fetchTraining({
  source_id: 'source-123',
  bot_id: 'bot-123'
});
```

***

### fetchTrainings()

Get all training sources for a bot.

```javascript theme={null}
await client.fetchTrainings({
  bot_id: 'bot-123',
  page: 1,
  per_page: 10
});
```

***

### updateTraining()

Update a training source.

```javascript theme={null}
await client.updateTraining({
  source_id: 'source-123',
  bot_id: 'bot-123',
  type: 'text',
  source: 'Updated content'
});
```

Returns same format as `startTraining()` with status, tokens, and links.

***

### deleteTraining()

Delete a training source.

```javascript theme={null}
await client.deleteTraining({
  source_id: 'source-123',
  bot_id: 'bot-123'
});
```

***

## Search

### search()

Search the bot's knowledge base.

```javascript theme={null}
await client.search({
  bot_id: 'bot-123',
  keywords: 'search query',
  source_ids: ['source1', 'source2']
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

<ParamField path="keywords" type="string" required>
  Search query
</ParamField>

<ParamField path="source_ids" type="array">
  Limit search to specific sources
</ParamField>

***

## Subscribers

### fetchSubscribers()

Get all subscribers for your project.

```javascript theme={null}
await client.fetchSubscribers({
  page: 1,
  per_page: 10
});
```

<ParamField path="page" type="number" default="1">
  Page number
</ParamField>

<ParamField path="per_page" type="number" default="10">
  Subscribers per page
</ParamField>

***

## Analytics & Statistics

### fetchVoteStats()

Get voting statistics for a bot.

```javascript theme={null}
await client.fetchVoteStats({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchSummaryStats()

Get summary statistics for a bot.

```javascript theme={null}
await client.fetchSummaryStats({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchDashboardStats()

Get dashboard statistics for a bot.

```javascript theme={null}
await client.fetchDashboardStats({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchToolUsageStats()

Get tool usage statistics for a bot.

```javascript theme={null}
await client.fetchToolUsageStats({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchWorkflowStats()

Get workflow statistics for a bot.

```javascript theme={null}
await client.fetchWorkflowStats({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchPerformanceMetrics()

Get performance metrics for a bot.

```javascript theme={null}
await client.fetchPerformanceMetrics({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchBehaviorStats()

Get user behavior statistics for a bot.

```javascript theme={null}
await client.fetchBehaviorStats({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchErrorAnalysis()

Get error analysis for a bot.

```javascript theme={null}
await client.fetchErrorAnalysis({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

### fetchReasoningSummary()

Get reasoning summary statistics for a bot.

```javascript theme={null}
await client.fetchReasoningSummary({
  bot_id: 'bot-123'
});
```

<ParamField path="bot_id" type="string" required>
  Bot ID
</ParamField>

***

## Error Handling

All methods return a consistent response format:

```javascript theme={null}
const result = await client.createBot({ name: 'My Bot' });

if (result.err) {
  // Handle error
  console.error('Error:', result.err.message);
} else {
  // Use response
  console.log('Success:', result.response);
}
```

Common error codes:

* **401** - Invalid API key
* **403** - Insufficient permissions
* **404** - Resource not found
* **429** - Rate limit exceeded
* **500** - Server error

***

## Complete Example

```javascript theme={null}
import 'dotenv/config';
import { BoostGPT } from 'boostgpt';

const client = new BoostGPT({
  key: process.env.BOOSTGPT_API_KEY,
  project_id: process.env.BOOSTGPT_PROJECT_ID
});

// Create bot
const botResult = await client.createBot({
  name: 'Support Bot',
  model: 'gpt-5-mini',
  instruction: 'You are a helpful support agent'
});

if (botResult.err) {
  console.error('Error:', botResult.err);
  process.exit(1);
}

const botId = botResult.response.id;

// Add training data
await client.startTraining({
  bot_id: botId,
  type: 'text',
  source: 'Our product helps developers build AI agents...'
});

// Chat with bot
const chatResult = await client.chat({
  bot_id: botId,
  message: 'What does your product do?',
  chat_id: 'user-123'
});

console.log('Bot:', chatResult.response);
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Router SDK" icon="split" href="/sdk/router/installation">
    Deploy bots to multiple channels
  </Card>

  <Card title="REST API" icon="braces" href="/api-reference/introduction">
    Direct API access
  </Card>

  <Card title="Examples" icon="lightbulb" href="/examples/use-cases">
    Real-world implementations
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
    Common issues
  </Card>
</CardGroup>