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

Introduction

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.

Frequently asked questions about Backboard and its features.

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

SDK Overview

Create an assistant, thread, and send your first message — with model selection, memory, and web search.

First Message

Create, list, update, and delete assistants via the SDK.

Assistants

Define custom functions for your assistant to call. Handle tool call requests and submit outputs to continue the conversation.

Tool Calls

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

Documents

Enable persistent memory, use Memory Pro, and manage memories via the SDK.

Memory

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

Web Search

AI agents with specific instructions and capabilities

Threads

Send and receive messages in conversation threads

Messages

Monitor your credit balance and API usage

Billing & Usage

Enable your assistant to call custom functions and external APIs

Tool Calling

Enable real-time web search in conversations

Models

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

List Threads

Get Thread

Delete Thread

Add Message to Thread

List Thread Documents

Upload Document to Thread

Submit Tool Outputs

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

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}

# 1) Create assistant
response = requests.post(
    f"{BASE_URL}/assistants",
    json={"name": "Support Bot", "system_prompt": "After every response, pass a joke at the end of the response!"},
    headers=HEADERS,
)
assistant_id = response.json()["assistant_id"]

# 2) Create thread
response = requests.post(
    f"{BASE_URL}/assistants/{assistant_id}/threads",
    json={},
    headers=HEADERS,
)
thread_id = response.json()["thread_id"]

# 3) Send message
response = requests.post(
    f"{BASE_URL}/threads/{thread_id}/messages",
    headers=HEADERS,
    data={"content": "Tell me about Canada in detail.", "stream": "false", "memory": "Auto"},
)
print(response.json().get("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).

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.

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.

Add Message to Thread with Optional Attachments

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.

Introduction

Welcome to Backboard API

Base URL

Quick Example

Architecture Overview

Next Steps

Quickstart

Authentication

Core Concepts

API Reference

On this page

​Welcome to Backboard API

​Base URL

​Quick Example

​Architecture Overview

​Next Steps

Quickstart

Authentication

Core Concepts

API Reference

On this page

Welcome to Backboard API

Base URL

Quick Example

Architecture Overview

Next Steps