- Getting Started
- Architecture
Getting Started
Architecture
How messages, threads, and assistants stack together in Backboard.
The diagram reads outside-in (assistant wraps threads). Below we explain inside-out: what one message is, then what a thread is, then what an assistant is.
The four things you need to know
1. Message — one turn
A message is a single exchange in a thread. There are three types:
| Role | Created by | What it is |
|---|---|---|
user | You | What the user said |
assistant | The model | The model’s reply (or a tool call request) |
tool | You | The result of executing a tool |
When you call POST /threads/messages, you are always sending one new message (and asking for the assistant’s reply).
2. Thread — one conversation
A thread is a ordered list of messages — one chat. Pass thread_id on the next call and the model sees the full history.
Every thread belongs to exactly one assistant. You can open many threads under the same assistant (for example one thread per end-user).
3. Assistant — your AI’s profile
An assistant sits above threads. It holds everything that makes your AI yours: a name, default instructions (system_prompt), tools, and embedding settings for memory and document search.
Memory and documents uploaded at the assistant level are shared across every thread under that assistant.
4. Memory & Documents — what sticks around
- Memory — facts extracted from conversations (e.g. “User prefers dark mode”). Stored per assistant, recalled across threads.
- Documents — files for RAG. Upload to the assistant (all threads) or to one thread (this chat only).
How a request works
- You send a message (
POST /threads/messages). - Backboard attaches it to the right thread (existing
thread_id, or a new thread). - That thread’s assistant supplies defaults, shared memory, and shared docs.
- History + context go to the LLM; the reply is saved as new messages on the same thread.
That’s it.
Quick reference
| Thing | What it is | Shared across threads? |
|---|---|---|
| Message | One turn in a conversation | — |
| Thread | One conversation (ordered messages) | — |
| Assistant | AI profile (instructions, tools, embeddings) | — |
| Memory | Facts extracted from conversations | Yes — under that assistant |
| Documents (assistant) | Uploaded files for RAG | Yes — under that assistant |
| Documents (thread) | Uploaded files for this chat only | No |