Backboard JavaScript SDK

A developer-friendly JavaScript SDK for the Backboard API. Build conversational AI applications with persistent memory and intelligent document processing.

> New to Backboard? We include $5 in free credits to get you started and support 1,800+ LLMs across major providers.

New in v1.4.11

- List threads for an assistant: client.listThreadsForAssistant(assistantId) (maps to GET /assistants/{assistant_id}/threads)

Installation

``bash
npm install backboard-sdk
`

Or with yarn:

`bash
yarn add backboard-sdk
`

$3


This package now ships first-class TypeScript types. Simply install and import; typings are included with the published package. No separate @types install is required.

Quick Start

`javascript
import { BackboardClient } from 'backboard-sdk';

// Initialize the client
const client = new BackboardClient({
apiKey: 'your_api_key_here'
});

// Create an assistant
const assistant = await client.createAssistant({
name: 'Support Bot',
system_prompt: 'You are a helpful customer support assistant'
});

// Create a conversation thread
const thread = await client.createThread(assistant.assistantId);

// Send a message
const response = await client.addMessage(thread.threadId, {
content: 'Hello! Can you help me with my account?',
llm_provider: 'openai',
model_name: 'gpt-4o'
});

console.log(response.content);
`

$3


Types are bundled; you can rely on autocompletion and type checking:
`ts
import { BackboardClient, MessageRole } from 'backboard-sdk';

const client = new BackboardClient({ apiKey: process.env.BACKBOARD_API_KEY! });
const thread = await client.createThread('assistant-id');
const resp = await client.addMessage(thread.threadId, { content: 'Ping?', stream: false });

if (resp.role === MessageRole.ASSISTANT) {
console.log(resp.content);
}
`

Features

$3

- Persistent Memory: Store and retrieve information across conversations
- Automatic Context: Enable memory to automatically search and use relevant context
- Manual Management: Full control with add, update, delete, and list operations
- Memory Modes: Auto (search + write), Readonly (search only), or off

$3

- Create, list, get, update, and delete assistants
- Configure custom tools and capabilities
- Upload documents for assistant-level context

$3

- Create conversation threads under assistants
- Maintain persistent conversation history
- Support for message attachments

$3

- Upload documents to assistants or threads
- Automatic processing and indexing for RAG
- Support for PDF, Office files, text, and more
- Real-time processing status tracking

$3

- Send messages with optional file attachments
- Streaming and non-streaming responses
- Tool calling support
- Custom LLM provider and model selection

API Reference

$3

`javascript
import { BackboardClient } from 'backboard-sdk';

const client = new BackboardClient({
apiKey: 'your_api_key'
});
`

$3

`javascript
// Create assistant
const assistant = await client.createAssistant({
name: 'My Assistant',
system_prompt: 'System prompt that guides your assistant',
tools: [toolDefinition], // Optional
// Embedding configuration (optional - defaults to OpenAI text-embedding-3-large with 3072 dims)
embedding_provider: 'cohere', // Optional: openai, google, cohere, etc.
embedding_model_name: 'embed-english-v3.0', // Optional
embedding_dims: 1024 // Optional
});

// List assistants
const assistants = await client.listAssistants({ skip: 0, limit: 100 });

// Get assistant
const assistant = await client.getAssistant(assistantId);

// Update assistant
const assistant = await client.updateAssistant(assistantId, {
name: 'New Name',
system_prompt: 'Updated system prompt'
});

// Delete assistant
const result = await client.deleteAssistant(assistantId);
`

$3

`javascript
// Create thread
const thread = await client.createThread(assistantId);

// List threads for a specific assistant
const assistantThreads = await client.listThreadsForAssistant(assistantId, { skip: 0, limit: 100 });

// List threads
const threads = await client.listThreads({ skip: 0, limit: 100 });

// Get thread with messages
const thread = await client.getThread(threadId);

// Delete thread
const result = await client.deleteThread(threadId);
`

$3

`javascript
// Send message
const response = await client.addMessage(threadId, {
content: 'Your message here',
files: ['path/to/file.pdf'], // Optional attachments
llm_provider: 'openai', // Optional
model_name: 'gpt-4o', // Optional
stream: false, // Set to true for streaming
memory: 'Auto', // Optional: "Auto", "Readonly", or "off" (default)
role: 'user' // Optional: "user" (default) or "assistant"
});

// Streaming messages
const stream = await client.addMessage(threadId, {
content: 'Hello',
stream: true
});

for await (const chunk of stream) {
if (chunk.type === 'content_streaming') {
process.stdout.write(chunk.content || '');
}
}

// Import conversation history (add assistant messages without LLM invocation)
await client.addMessage(threadId, {
content: 'This was the assistant\'s previous response',
role: 'assistant' // No LLM invocation when role is "assistant"
});
`

$3

`javascript
// Add a memory
await client.addMemory(assistantId, {
content: 'User prefers JavaScript programming',
metadata: { category: 'preference' }
});

// Get all memories
const memories = await client.getMemories(assistantId);
for (const memory of memories.memories) {
console.log(${memory.id}: ${memory.content});
}

// Get specific memory
const memory = await client.getMemory(assistantId, memoryId);

// Update memory
await client.updateMemory(assistantId, memoryId, {
content: 'Updated content'
});

// Delete memory
await client.deleteMemory(assistantId, memoryId);

// Get memory stats
const stats = await client.getMemoryStats(assistantId);
console.log(Total memories: ${stats.totalMemories});

// Use memory in conversation
const response = await client.addMessage(threadId, {
content: 'What do you know about me?',
memory: 'Auto' // Enable memory search and automatic updates
});
`




$3

#### Tool Definitions
`javascript
// Use plain JSON objects (no verbose SDK classes needed!)
const tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name"}
},
"required": ["location"]
}
}
}
];

const assistant = await client.createAssistant({
name: 'Weather Assistant',
system_prompt: 'You are a helpful weather assistant',
tools: tools
});
`

#### Tool Call Handling
`javascript
// Enhanced object-oriented access with automatic JSON parsing
const response = await client.addMessage(threadId, {
content: "What's the weather in San Francisco?"
});

if (response.status === 'REQUIRES_ACTION' && response.toolCalls) {
const toolOutputs = [];

// Process each tool call
for (const tc of response.toolCalls) {
if (tc.function.name === 'get_current_weather') {
// Get parsed arguments (required parameters are guaranteed by API)
const args = tc.function.parsedArguments;
const location = args.location;

// Execute your function and format the output
const weatherData = {
temperature: '68°F',
condition: 'Sunny',
location: location
};

toolOutputs.push({
tool_call_id: tc.id,
output: JSON.stringify(weatherData)
});
}
}

// Submit the tool outputs back to continue the conversation
const finalResponse = await client.submitToolOutputs(
threadId,
response.runId,
toolOutputs
);

console.log(finalResponse.content);
}
`

$3

`javascript
// Upload document to assistant
const document = await client.uploadDocumentToAssistant(
assistantId,
'path/to/document.pdf'
);

// Upload document to thread
const document = await client.uploadDocumentToThread(
threadId,
'path/to/document.pdf'
);

// List assistant documents
const documents = await client.listAssistantDocuments(assistantId);

// List thread documents
const documents = await client.listThreadDocuments(threadId);

// Get document status
const document = await client.getDocumentStatus(documentId);

// Delete document
const result = await client.deleteDocument(documentId);
`

Error Handling

The SDK includes comprehensive error handling:

`javascript
import {
BackboardAPIError,
BackboardValidationError,
BackboardNotFoundError,
BackboardRateLimitError,
BackboardServerError
} from 'backboard-sdk';

try {
const assistant = await client.getAssistant('invalid_id');
} catch (error) {
if (error instanceof BackboardNotFoundError) {
console.log('Assistant not found');
} else if (error instanceof BackboardValidationError) {
console.log(Validation error: ${error.message});
} else if (error instanceof BackboardAPIError) {
console.log(API error: ${error.message});
}
}
`

Advanced Tool Example

Here's a more comprehensive tool definition example:

`javascript
const weatherTool = {
type: 'function',
function: {
name: 'get_weather',
description: 'Get current weather for a location',
parameters: {
type: 'object',
properties: {
location: {
type: 'string',
description: 'The city and state, e.g. San Francisco, CA'
},
unit: {
type: 'string',
enum: ['celsius', 'fahrenheit'],
description: 'Temperature unit'
}
},
required: ['location']
}
}
};

const assistant = await client.createAssistant({
name: 'Weather Assistant',
system_prompt: 'You are an AI assistant that can check weather information',
tools: [weatherTool]
});

// Handle tool calls with the new simplified approach
const response = await client.addMessage(threadId, {
content: "What's the weather in San Francisco?"
});

if (response.toolCalls) {
for (const tc of response.toolCalls) {
if (tc.function.name === 'get_weather') {
const { location, unit } = tc.function.parsedArguments;
const weather = await getWeatherData(location, unit);

await client.submitToolOutputs(threadId, response.runId, [{
tool_call_id: tc.id,
output: JSON.stringify(weather)
}]);
}
}
}
`

Supported File Types

The SDK supports uploading the following file types:
- PDF files (.pdf)
- Microsoft Office files (.docx, .xlsx, .pptx, .doc, .xls, .ppt)
- Text files (.txt, .csv, .md, .markdown)
- Code files (.py, .js, .html, .css, .xml)
- JSON files (.json, .jsonl)

Requirements

- Node.js 16.0.0 or higher
- ES modules support
- TypeScript users: npm run build emits dist/ with .d.ts files

Local Development

`bash


install deps

npm install

build TypeScript -> dist/ (runs on publish via npm prepare)

npm run build

lint/tests (if present)

npm run lint
npm test
``

License

MIT License - see LICENSE file for details.

Support

- Documentation: https://app.backboard.io/docs
- Email: support@backboard.io