> ## Documentation Index
> Fetch the complete documentation index at: /docs/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-6-luna',
  instruction: 'System instruction',
  max_reply_tokens: 1000,
  top: 5,
  status: 'active'
});
```

**name** `string` *required*

Display name for your bot

**model** `string` *required*

AI model to use: `gpt-6-luna`, `gpt-6-sol`, `claude-haiku-4-5`, `gemini-3.5-flash`, etc. See [Model Comparison](/docs/providers/model-comparison.md) for the full catalogue.

**instruction** `string` *required*

System instruction guiding the AI's behavior

**max\_reply\_tokens** `number` (default: 1000)

Maximum tokens in AI responses

**reasoning\_mode** `string`

Reasoning mode: `auto`, `standard`, `agent`

**status** `string` (default: active)

Bot status: `active` or `inactive`

***

### fetchBot()

Get a bot's configuration.

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

**bot\_id** `string` *required*

ID of the bot to fetch

***

### fetchBots()

Get all bots in a project (paginated).

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

**page** `number` (default: 1)

Page number

**per\_page** `number` (default: 10)

Items per page

***

### updateBot()

Update a bot's configuration.

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

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

**bot\_id** `string` *required*

ID of the bot to update

***

### 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.

***

### 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.

***

## 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-6-luna',
  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
});
```

**bot\_id** `string` *required*

ID of the bot to chat with

**message** `string` *required*

User's message

**chat\_id** `string`

Unique ID for conversation continuity

**stream** `boolean` (default: false)

Enable streaming responses

**memory** `boolean` (default: true)

Use agent's training data/memory

**model** `string`

Override bot's default model

**provider\_key** `string`

Use your own API key (BYOK)

**provider\_host** `string`

Provider host URL (required for Ollama)

**instruction** `string`

Override bot's default instruction

**source\_ids** `array`

Limit knowledge to specific sources

**reasoning\_mode** `string`

Override reasoning mode: `auto`, `standard`, `agent`

**max\_reply\_tokens** `number`

Override bot's default token limit

**chat\_mode** `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`.

**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
});
```

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat/conversation ID

**page** `number` (default: 1)

Page number

**per\_page** `number` (default: 20)

Messages per page

***

### fetchChats()

Get all chats for a bot.

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

**bot\_id** `string` *required*

Bot ID

**page** `number` (default: 1)

Page number

**per\_page** `number` (default: 10)

Chats per page

***

### deleteChat()

Delete a chat history.

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

**chat\_id** `string` *required*

Chat ID to delete

**bot\_id** `string` *required*

Bot ID

***

### executeTool()

Run a tool the agent asked for, continuing the turn.

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

Every field of `execution_data` comes back on the `tool_approval_required` response — pass it
through rather than assembling it yourself.

A continuation resumes the turn that requested the tool, and inherits that turn's `memory`,
`source_ids`, `tags` and the chat's saved `chat_mode`. The parameters below are overrides — send one
only to change it.

> [!WARNING]
>
> Before 8.0.1 this method sent `tool_calls`, which the endpoint does not read, so every call
> returned 400. Upgrade if you are calling it.

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat ID

**execution\_data** `object` *required*

Must contain `executionId`, `toolName` and `parameters`; may also carry `serverLabel`,
`originalQuery` and `authenticatedTools`

**model** `string`

Model for the continuation. Defaults to the agent's own.

**instruction** `string`

System instruction for the continuation.

**chat\_mode** `string`

`ask`, `edit` or `plan`. Omit to keep the chat's saved mode.

**memory** `boolean`

Override whether the continuation may search the agent's knowledge. Omit to keep whatever the
turn was running with.

**source\_ids** `string[]`

Override the knowledge search scope. Omit to keep the turn's scope; send `[]` to clear it.

**tags** `string[]`

Override the tag scope. Omit to keep the turn's; send `[]` to clear it.

**stream** `boolean` (default: false)

Return an event stream instead of a single response.

***

### 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'
});
```

**bot\_id** `string` *required*

Bot ID

**message\_id** `string` *required*

Message ID to vote on

**voter\_id** `string` *required*

ID of the user voting

**voter\_type** `string` *required*

Type of voter (e.g., 'member')

**vote\_type** `string` *required*

Vote type: 'upvote' or 'downvote'

***

### 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'
});
```

**bot\_id** `string` *required*

Bot ID

**message\_id** `string` *required*

Message ID

**voter\_id** `string` *required*

Voter ID

**voter\_type** `string` *required*

Voter type

***

### deleteMessage()

Delete a specific message.

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

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat ID

**message\_id** `string` *required*

Message ID to delete

***

### fetchChatPlan()

The plan behind a builder conversation, if one is active.

```javascript theme={null}
const { response } = await client.fetchChatPlan({
  bot_id: 'bot-123',
  chat_id: 'chat-456'
});
```

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat ID

***

### cancelChatPlan()

Cancel that plan. There is no accept method on purpose: a plan is accepted through the agent's own review question inside the conversation.

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

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat ID

***

### fetchChatAgents()

The agents a conversation delegated to. Each carries its `label`, `task_name`, `role`, `model`, `status`, `steps_used`, `prompt_tokens`, `completion_tokens` and a 400-character head of its `result`.

```javascript theme={null}
// This turn's agents
const { response } = await client.fetchChatAgents({
  bot_id: 'bot-123',
  chat_id: 'chat-456'
});
// response.agents

// Every turn's, the way the dashboard's agent map shows them
const all = await client.fetchChatAgents({
  bot_id: 'bot-123',
  chat_id: 'chat-456',
  scope: 'chat'
});
// all.response.turns[].agents
```

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat ID

**scope** `string` (default: turn)

`turn` for the most recent delegating turn, `chat` for every turn

**root\_execution\_id** `string`

A specific turn, when `scope` is `turn`

***

### fetchChatAgent()

One agent in full: its brief (`input`), its report (`result` or `error`), and the tools it ran (`transcript`).

```javascript theme={null}
const { response } = await client.fetchChatAgent({
  bot_id: 'bot-123',
  chat_id: 'chat-456',
  agent_id: 'agent-uuid'
});
// response.agent.transcript → [{ name, gist, ok, head }]
```

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat ID

**agent\_id** `string` *required*

The agent's uuid, from `fetchChatAgents`

***

### deleteChatAgent()

Remove an agent's record. A running agent is stopped at its next decision boundary first. A later turn can no longer resume a deleted agent.

```javascript theme={null}
await client.deleteChatAgent({
  bot_id: 'bot-123',
  chat_id: 'chat-456',
  agent_id: 'agent-uuid'
});
```

**bot\_id** `string` *required*

Bot ID

**chat\_id** `string` *required*

Chat ID

**agent\_id** `string` *required*

The agent's uuid

***

## 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'
});
```

**bot\_id** `string` *required*

Bot ID

**type** `string` (default: text)

Source type: `text`, `website`, `file`, `webpage`

**source** `string | array` *required*

* `text`: String content
* `website`: String URL to crawl
* `file`: Array of file paths
* `webpage`: Array of URLs

**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',
  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']
});
```

**bot\_id** `string` *required*

Bot ID

**keywords** `string` *required*

Search query

**source\_ids** `array`

Limit search to specific sources

***

## Analytics & Statistics

### fetchVoteStats()

Get voting statistics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchSummaryStats()

Get summary statistics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchDashboardStats()

Get dashboard statistics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchToolUsageStats()

Get tool usage statistics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchWorkflowStats()

Get workflow statistics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchPerformanceMetrics()

Get performance metrics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchBehaviorStats()

Get user behavior statistics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchErrorAnalysis()

Get error analysis for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

### fetchReasoningSummary()

Get reasoning summary statistics for a bot.

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

**bot\_id** `string` *required*

Bot ID

***

## Widget

Both endpoints serve the embeddable chat widget. They are here so a backend can mint a signed
session or read the same configuration the widget reads.

### fetchWidgetConfig()

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

***

## Error Handling

Methods never throw. Every one returns `{ err, response }`, and `err` is set whenever the request
came back with a non-2xx status:

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

if (result.err) {
  console.error(result.err.message);   // what the server said
  console.error(result.err.status);    // 400, 403, 429, 500 …
  console.error(result.err.code);      // e.g. 'schedule_too_frequent', when the API sends one
} else {
  console.log(result.response);
}
```

On failure `response` is `null`, so there is no half-populated object to guard against.

Common statuses:

* **400** - Invalid request. `err.message` says what was wrong.
* **401** - Invalid API key
* **403** - Insufficient permissions, or a plan that does not include the feature
* **404** - Resource not found
* **429** - Rate limit exceeded
* **500** - Server error

> [!WARNING]
>
> **Changed in 8.0.0.** Earlier versions decided whether a request had failed by reading a field the
> API only populates in development, so against production `err` was always `null` and a failed call
> returned the error body as though it were data. If you have code inspecting `response.message` to
> detect failures, it can now check `err` instead.

For a streaming call — `chat({ stream: true })`, `subscribeChat`, `subscribeNotifications` —
`response` is the raw event stream rather than a parsed object; iterate it with `for await`.

***

## 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-6-luna',
  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

> [card] [Router SDK](/docs/sdk/router/installation.md)
>
> Deploy bots to multiple channels

> [card] [REST API](/docs/api-reference/introduction.md)
>
> Direct API access

> [card] [Examples](/docs/examples/use-cases.md)
>
> Real-world implementations

> [card] [Troubleshooting](/docs/developers/troubleshooting.md)
>
> Common issues


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.