Explore the Backboard SDK with detailed examples for tool calls, documents, memory, streaming, and thinking.

SDK Overview

API Reference

Dashboard

X-API-Key

Backboard API

Get API Key

Index

Get started with Backboard API in under 5 minutes

Quickstart

Learn how to authenticate your API requests

Authentication

Navigate the Backboard.io dashboard to track usage, manage assistants, and explore the platform's features.

How messages, threads, and assistants stack together in Backboard.

Architecture

Frequently asked questions about Backboard and its features.

Send your first message in one call — no assistant or thread setup needed.

First Message

Use thread_id to keep chat history in one place. Use assistant_id when you want the same AI profile (and memory) across multiple chats.

Continuing conversations

Use the SDK to create, list, update, and delete assistants—the saved AI profiles your threads attach to.

Create & update assistants

Define custom functions for your assistant to call, handle tool call requests, and submit outputs.

Tool Calls

Use the built-in image generation tool from the SDK and handle generated images in streaming responses.

Image Tool

Upload, list, poll, and delete documents. Query their contents with RAG.

Documents

Enable persistent memory so your assistant remembers facts across conversations. Manage memories programmatically.

Memory

Enable real-time web search in conversations via the SDK.

Web Search

Enable step-by-step reasoning in conversations via the SDK

Thinking (Reasoning)

Add Speech to Text and Text to Speech to any SDK message

Voice (TTS & STT)

Stream live microphone audio to Backboard with the SDK and get transcripts, LLM replies, and TTS audio back over a single WebSocket.

Realtime Voice (WebSocket)

Each assistant is your AI’s saved identity—instructions, tools, documents, memory, and embeddings—in one place.

Assistant profiles

One thread is one ongoing chat—message history, tool calls, and context—stays together until you delete it.

Conversation threads

How to send a message, stream the response, and understand every field in the request and response.

Send Message

Monitor your credit balance and API usage

Billing & Usage

How tool calling works: define tools, handle requests, submit outputs, and loop for multi-round calls.

Tool Calling

How Backboard handles text-to-image and image-to-image generation inside a normal conversation.

Enable real-time web search in conversations

Enable models to reason step-by-step before answering

Add Speech to Text and Text to Speech to any message

Stream live microphone audio to Backboard and get transcripts, LLM replies, and TTS audio back on a single WebSocket.

Models

Let your users log in or sign up using a Backboard account

SSO (Single Sign On)

Create Assistant

List Assistants

Get Assistant

Update Assistant

Delete Assistant

Create Thread for Assistant

List Threads for Assistant

List Assistant Documents

Upload Document to Assistant

Submit Tool Outputs

List Threads

Get Thread

Delete Thread

List Thread Documents

Upload Document to Thread

Add Message to Thread (Legacy)

Submit Tool Outputs (Legacy)

Get Document Status

Delete Document

List Memories

Search through stored memories using semantic or keyword-based queries

Search Memories

Add Memory

Get Memory

Update Memory

Delete Memory

Get Memory Operation Status

List Models

Get Model

List Providers

List Models by Provider

List Embedding Models

List Embedding Providers

Get Embedding Model

Retrieve recent usage events and billing activity for your account

Get Recent Usage

Assistant

AssistantCreate

AssistantDeleteResponse

AssistantUpdate

AttachmentInfo

Body_upload_document_to_assistant_assistants__assistant_id__documents_post

Body_upload_document_to_thread_threads__thread_id__documents_post

CreditWallet

DocumentDeleteResponse

DocumentRead

DocumentStatus

DocumentStatusResponse

Schema specifically for reading embedding model information.

EmbeddingModelRead

Response schema for listing embedding models.

EmbeddingModelsListResponse

FunctionDefinition

HTTPValidationError

Schema for listing memories with optional pagination

MemoriesListResponse

MemoryCreate

MemoryDeleteResponse

MemoryOperationStatusResponse

Schema for memory responses from backboard_memory

MemoryResponse

MemorySearchRequest

MemorySearchResponse

Schema for a single memory search result (no metadata, used in search responses)

MemorySearchResultItem

MemoryUpdate

Response for message operations - includes content at top level for easy access

MessageResponse

MessageRole

MessageStatus

MessageWithAttachments

Schema for reading model information including pricing.

ModelRead

ModelsListResponse

PaginatedUsageSummaryResponse

PaginationMeta

ProvidersListResponse

RetrievedMemory

SubmitToolOutputsRequest

Submit tool outputs. thread_id in body, run_id auto-resolved from latest REQUIRES_ACTION message.

SubmitToolOutputsSimpleRequest

Thread

ThreadCreateForAssistant

ThreadDeleteResponse

ToolDefinition

ToolOutput

ToolOutputsResponse

ToolParameterProperties

ToolParameters

Slim projection returned by GET /billing/usage/recent.

UsageEventSummary

ValidationError


# Welcome to Backboard API

Build conversational AI applications with persistent memory and intelligent document processing.

## Endpoint URL
```
https://app.backboard.io/api
```

## API Architecture

Understanding the core concepts of Backboard API will help you build powerful conversational AI applications.

### **Assistant**
An **Assistant** is an AI agent with specific instructions and capabilities. Think of it as a specialized AI persona that you configure once and use across multiple conversations.

**Key Properties:**
- `assistant_id` - Unique identifier for the assistant
- `name` - Human-readable name for your assistant
- `system_prompt` - Instructions that define the assistant's behavior and personality
- `llm_provider` - AI provider (e.g., "openai", "anthropic", "google")
- `model_name` - Specific model to use (e.g., "gpt-4o", "claude-3-5-sonnet-20241022")
- `tools` - Optional tools the assistant can use (web search, function calling, etc.)
- `embedding_provider` & `embedding_model_name` - Models used for RAG and memory operations

**Use Cases:**
- Customer support bot with specific product knowledge
- Code review assistant with particular coding standards
- Research assistant with domain expertise

---

### **Thread**
A **Thread** represents a persistent conversation session. It maintains the full context and history of messages between a user and an assistant.

**Key Properties:**
- `thread_id` - Unique identifier for the conversation thread
- `assistant_id` - The assistant associated with this thread
- Messages are automatically stored and retrieved within the thread

**Important Notes:**
- Threads maintain conversation history across multiple API calls
- Each thread is tied to a specific assistant
- You can have multiple threads per assistant (e.g., different users or topics)
- Threads persist indefinitely unless explicitly deleted

**Example Flow:**
```
User creates Thread A → sends messages → conversation is saved
Days later → same Thread A → assistant remembers full context
```

---

### **Message**
A **Message** is a single interaction within a thread - either from the user or the assistant's response.

**Key Properties:**
- `content` - The text content of the message
- `role` - Either "user" or "assistant"
- `thread_id` - Which thread this message belongs to
- `stream` - Whether to stream the response (true/false)
- `memory` - Memory mode: "Auto", "On", "Off" (controls persistent memory features)

**Streaming vs Non-Streaming:**
- **Non-streaming**: Wait for the complete response (simpler, use for batch processing)
- **Streaming**: Receive response in real-time chunks (better UX for chat interfaces)

---

### **Document**
**Documents** are files you upload to provide context to your assistant. They can be attached at the assistant level (available to all threads) or thread level (specific conversation only).

**Key Properties:**
- `document_id` - Unique identifier for the document
- `filename` - Original filename
- `status` - Processing status: "processing", "completed", "error"
- `assistant_id` or `thread_id` - Where the document is attached

**Supported Formats:**
- PDF documents
- Text files (.txt, .md)
- Microsoft Office (.docx, .xlsx, .pptx)
- CSV and JSON files
- Source code files

**Processing Pipeline:**
1. Upload document via API
2. Backboard chunks and indexes the content
3. Status changes from "processing" to "completed"
4. Document content is available for RAG (Retrieval-Augmented Generation)

---

### **Memory**
**Memory** is an advanced feature that enables assistants to remember facts, preferences, and context across conversations and even across different threads.

**Memory Modes:**
- **"Off"**: No persistent memory, only uses conversation history
- **"On"**: Explicitly saves and retrieves memories for context
- **"Auto"**: Intelligently determines when to use memory (recommended)

**How It Works:**
- Automatically extracts key facts from conversations
- Stores them in a semantic knowledge base
- Retrieves relevant memories for future messages
- Works across different threads with the same assistant

**Example:**
```
Thread 1: User mentions "I prefer Python over JavaScript"
Thread 2 (days later): Assistant remembers this preference
```

---

## Typical Workflow

Here's how these components work together:

```
1. Create an Assistant
   └─ Define behavior, choose model, configure tools
   
2. Create a Thread (per conversation/user)
   └─ Links to the assistant you created
   
3. Upload Documents (optional)
   └─ Attach to assistant (all threads) or specific thread
   
4. Send Messages
   └─ User messages → Assistant responses
   └─ Conversation history is automatically maintained
   
5. Memory (optional)
   └─ Enable with memory="Auto" to persist learnings
```

---

## Core Features

### **Persistent Conversations**
Create conversation threads that maintain context across multiple messages and support file attachments.

### **Intelligent Document Processing**
Upload and process documents (PDF, text, Office files) with automatic chunking and indexing for retrieval.

### **AI Assistants**
Create specialized assistants with custom instructions, document access, and tool capabilities.

## Quickstart

```python
import requests

API_KEY = "your_api_key"
BASE_URL = "https://app.backboard.io/api"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Send a message — thread and assistant auto-created
response = requests.post(
    f"{BASE_URL}/threads/messages",
    json={"content": "Tell me about Canada in detail.", "stream": false, "memory": "Auto"},
    headers=HEADERS,
)
result = response.json()
print(result["content"])
print(f"thread_id: {result['thread_id']}")
print(f"assistant_id: {result['assistant_id']}")

# Continue the conversation
response = requests.post(
    f"{BASE_URL}/threads/messages",
    json={"content": "What is its population?", "thread_id": result["thread_id"], "stream": false},
    headers=HEADERS,
)
print(response.json()["content"])
```

---

Explore the **Assistants**, **Threads**, and **Documents** sections in the sidebar.
    

List all assistants belonging to the authenticated user.

Create a new assistant for the authenticated user. Optionally configure embedding model for RAG (defaults to OpenAI text-embedding-3-large with 3072 dimensions).

Get the status of a memory add/update/delete operation by operation_id.

Permanently delete an assistant and all its associated threads and documents.

Retrieve a specific assistant by its UUID.

Update an assistant's attributes, including its name, description, and tools. Note: The 'tools' field will replace the existing list of tools. Embedding model cannot be changed after creation.

List all documents associated with a specific assistant.

Upload a document to be associated with a specific assistant (shared context for its threads). Supported file types: **Documents** (.pdf, .doc, .docx, .ppt, .pptx, .xls, .xlsx), **Text/Data** (.txt, .csv, .md, .markdown, .json, .jsonl, .xml), **Code** (.py, .js, .ts, .jsx, .tsx, .html, .css, .cpp, .c, .h, .java, .go, .rs, .rb, .php, .sql), **Images** (.png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff, .tif).

Delete all memories for an assistant from both database and vector store.

List memories for an assistant with optional server-side pagination.

Add a new memory directly for a specific assistant (manual creation from UI).

Search memories for a specific assistant using a query string.

Delete a specific memory from both database and vector store.

Update a specific memory in both database and vector store.

List all threads under a specific assistant for the authenticated user.

Create a new empty conversation thread under a specific assistant. Use the message endpoints to add messages to the thread.

Minimal usage summary for the billing page.
Returns totals for the selected time window:
- total_spending_usd
- token_usage_usd
- reads_count, reads_cost_usd
- writes_count, writes_cost_usd

Delete a document by ID across assistant, thread, or message scope.

Get the processing status and details of a specific document.

Get a list of all available models with their specifications and pricing information.

Get a list of all available embedding models with their specifications.

Get a list of all unique embedding model providers available in the system.

Get detailed information about a specific embedding model by its name.

Get all models from a specific provider, including pricing information.

Get a list of all unique model providers available in the system.

Get detailed information about a specific model by its name, including pricing.

List all threads for the currently authenticated user.

Send a message — the recommended entry-point for all integrations. Omit thread_id to auto-create a new thread (and default assistant). Pass thread_id to continue an existing conversation. Pass assistant_id to pin new threads to a specific assistant, sharing its memory, documents, and stored configuration.

Submit tool outputs for a thread in a single JSON call — no path parameters, no run_id. The server resolves the run from the latest REQUIRES_ACTION assistant message on the thread. Body: {thread_id, tool_outputs: [{tool_call_id, output}], stream?}. For explicit run-pinning or per-run tool overrides, use the original POST /threads/{thread_id}/runs/{run_id}/submit-tool-outputs.

Permanently delete a thread and all its associated messages.

Retrieve a specific thread by its UUID, including all its messages.

List all documents associated with a specific thread.

Upload a document to be associated with a specific thread and processed for RAG. Supported file types: **Documents** (.pdf, .doc, .docx, .ppt, .pptx, .xls, .xlsx), **Text/Data** (.txt, .csv, .md, .markdown, .json, .jsonl, .xml), **Code** (.py, .js, .ts, .jsx, .tsx, .html, .css, .cpp, .c, .h, .java, .go, .rs, .rb, .php, .sql), **Images** (.png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff, .tif).

Add a user message to an existing thread with optional file attachments. Accepts both JSON (application/json) and form-data (multipart/form-data) payloads. Use JSON for text-only messages; use form-data when uploading file attachments. Can send text only, attachments only, or both. Documents must be indexed before further messages are allowed. To choose a model, set llm_provider and model_name. If omitted, defaults are llm_provider=openai and model_name=gpt-4o. Set memory='Auto' for Memory Lite (default). Set memory_pro='Auto' for Memory Pro (higher accuracy, higher cost). Only one can be used at a time. Supported attachment types: .pdf, .doc(x), .ppt(x), .xls(x), .txt, .csv, .md, .json(l), .xml, .py, .js, .ts, .jsx, .tsx, .html, .css, .cpp, .c, .h, .java, .go, .rs, .rb, .php, .sql, .png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff, .tif. See the Model Library page in the dashboard (model-library page) for a current list of supported models and providers.

Mark a run as cancelled. Idempotent: cancelling a run that is already finished or already cancelled returns 200. Useful when the client gives up on a streaming response (e.g. Ctrl+C).

Submit the outputs of tool calls that an assistant message previously requested. This will continue the run. If stream=true, returns a Server-Sent Events stream.

SDK Overview

Getting Started

Installation

Python

JavaScript/TypeScript

SDK Guides

First Message

Continuing conversations

Create & update assistants

Tool Calls

Documents

Memory

Web Search

Thinking

Streaming vs Non-Streaming

Language Support

On this page

​Getting Started

​Installation

Python

JavaScript/TypeScript

​SDK Guides

First Message

Continuing conversations

Create & update assistants

Tool Calls

Documents

Memory

Web Search

Thinking

​Streaming vs Non-Streaming

​Language Support

On this page

Getting Started

Installation

SDK Guides

Streaming vs Non-Streaming

Language Support