Backboard API home pagelight logo
  1. Core Concepts
  2. Assistant profiles

​
What this is

An assistant is not a single chat. It is the profile your AI runs under: a name, default instructions, optional tools, uploaded docs (RAG), memory behavior, and embedding settings. You create an assistant once, then attach many conversation threads to it.

If you only need a quick reply with no saved setup, you can skip creating an assistant and use send_message / sendMessage—the API can create a default assistant for you. When you care about branding, memory across users, shared docs, or stable defaults, you create your own assistant and pass assistant_id on messages.

​
What lives on an assistant

IdeaWhat it means
Who the AI isDefault instructions (system_prompt), tools, and retrieval depth (tok_k)
Long-term memoryMemories are scoped to the assistant—reuse assistant_id so recall works across threads
Documents (RAG)Upload docs at the assistant level so every thread under that assistant can search them
EmbeddingsSet once at creation (embedding_*). Cannot be changed later

​
Key properties

PropertyTypeDescription
assistant_iduuidUnique identifier (returned on creation)
namestringHuman-readable name (1–255 chars, required)
system_promptstringInstructions that define the assistant’s behavior
toolsarrayOptional tools the assistant can use (function calling, etc.)
tok_kintegerNumber of document chunks retrieved per query (1–100, default 10)
custom_fact_extraction_promptstringCustom prompt for memory fact extraction. Uses default if omitted
custom_update_memory_promptstringCustom prompt for memory update decisions (add/update/delete). Uses default if omitted
embedding_providerstringEmbedding provider for RAG & memory (openai, google, cohere, etc.)
embedding_model_namestringEmbedding model name (e.g. text-embedding-3-large)
embedding_dimsintegerEmbedding dimensions (e.g. 3072 for OpenAI large)
created_atdatetimeTimestamp when the assistant was created

​
Create an assistant

import requests

response = requests.post(
    "https://app.backboard.io/api/assistants",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Technical Support",
        "system_prompt": "You are a concise technical support assistant.",
        "tok_k": 15,
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "search_kb",
                    "description": "Search the product knowledge base",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "query": {"type": "string", "description": "Search query"}
                        },
                        "required": ["query"]
                    }
                }
            }
        ]
    }
)
assistant = response.json()
print(assistant["assistant_id"])

​
Update an assistant

All fields are optional on update. tools replaces the existing list entirely. Embedding config cannot be changed after creation.

requests.put(
    f"https://app.backboard.io/api/assistants/{assistant_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "system_prompt": "Updated instructions here",
        "tok_k": 20,
        "custom_fact_extraction_prompt": "Extract only personal preferences and technical choices."
    }
)

​
Custom memory prompts

You can override the default fact-extraction and memory-update prompts per assistant. This is useful for controlling exactly what gets saved to memory and how updates are handled.

requests.put(
    f"https://app.backboard.io/api/assistants/{assistant_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "custom_fact_extraction_prompt": "Extract only technical preferences and project details.",
        "custom_update_memory_prompt": "Only update memories when the user explicitly corrects previous information."
    }
)

Set to an empty string to clear a custom prompt and revert to the default.

​
Embedding configuration

When creating an assistant, you can configure the embedding model used for document retrieval (RAG) and memory operations. Defaults to OpenAI text-embedding-3-large with 3072 dimensions.

{
    "name": "My Assistant",
    "embedding_provider": "openai",
    "embedding_model_name": "text-embedding-3-large",
    "embedding_dims": 3072
}

The embedding model cannot be changed after the assistant is created. Choose carefully based on your needs.

​
List & Delete

ParameterTypeDefaultRangeDescription
skipinteger00–10 000Number of records to skip
limitinteger1001–200Maximum number of records to return
# List all assistants (limit: 1–200, skip: 0–10 000)
assistants = requests.get(
    "https://app.backboard.io/api/assistants",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"skip": 0, "limit": 50}
).json()

# Delete an assistant (also deletes all threads & documents)
requests.delete(
    f"https://app.backboard.io/api/assistants/{assistant_id}",
    headers={"X-API-Key": "YOUR_API_KEY"}
)

​
Related