Send Message

​

Overview

POST /threads/messages is the primary endpoint for interacting with Backboard. Send a user message, get the assistant’s response. You can start a new conversation (omit thread_id) or continue an existing one (pass thread_id).

​

Request

​

Endpoint

POST https://app.backboard.io/api/threads/messages

​

Headers

​

Body parameters

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

​

Non-streaming response

When stream is false (or omitted), you receive a single JSON response after the model finishes.

import requests

headers = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

response = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "content": "What is machine learning?",
        "llm_provider": "openrouter",
        "model_name": "moonshotai/kimi-k2.6",
    },
)
result = response.json()

print("Reply:", result["content"])
print("Thread ID:", result["thread_id"])
print("Tokens:", result["total_tokens"])

​

Response object

​

Context usage

Every response includes a context_usage object:

​

Streaming response (SSE)

When stream=true, the response is a stream of Server-Sent Events. Each event is a JSON object on a data: line.

​

SSE event types

thread_id is present on run_ended and user_message, not on every event. If you need it elsewhere, carry it from the request or from the first event that includes it.

​

Early tool-call events

tool_call_start and tool_call_ready let you show a tool call in your UI — or begin executing it — before the model finishes its turn.

{"type": "tool_call_start", "run_id": "run_abc", "tool_call_id": "call_1", "name": "get_weather"}

{
  "type": "tool_call_ready",
  "run_id": "run_abc",
  "tool_call": {
    "id": "call_1",
    "type": "function",
    "function": {"name": "get_weather", "arguments": "{\"city\": \"Paris\"}"}
  }
}

When the provider streams a tool-call id, tool_call_start arrives before tool_call_ready. Some providers do not reveal an id until the arguments are complete — in that case tool_call_start is skipped, only tool_call_ready fires, and its tool_call.id is null. Each event fires at most once per call.

Tools that Backboard runs internally, such as document search, web search, and image generation, are never announced. You only see calls you will be asked to execute.

​

Usage and cost fields

run_ended and tool_submit_required both carry usage telemetry:

​

Example: handling SSE events

import json
import requests

headers = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

response = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "content": "Tell me a fun fact about space.",
        "stream": True,
    },
    stream=True,
)

for line in response.iter_lines():
    if not line:
        continue
    decoded = line.decode()
    if not decoded.startswith("data: "):
        continue

    event = json.loads(decoded[6:])
    event_type = event.get("type")

    if event_type == "content_streaming":
        print(event.get("content", ""), end="", flush=True)

    elif event_type == "reasoning_streaming":
        # Only present when thinking is enabled
        print(f"[thinking] {event.get('content', '')}", end="", flush=True)

    elif event_type == "reasoning_ended":
        print("\n--- reasoning done ---")

    elif event_type == "tool_submit_required":
        # The model wants you to call tools — see Tool Calling
        print(f"\nTool calls requested: {event.get('tool_calls')}")

    elif event_type == "run_ended":
        print(f"\nDone. Tokens: {event.get('total_tokens')}")

​

Choosing a model per message

Override the model on any message — you can switch freely within the same thread:

# Turn 1: use OpenAI
response_1 = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "content": "Explain quantum computing",
        "llm_provider": "openai",
        "model_name": "gpt-4o",
    },
).json()

# Turn 2: switch to Anthropic on the same thread
response_2 = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "thread_id": response_1["thread_id"],
        "content": "Now simplify that explanation",
        "llm_provider": "anthropic",
        "model_name": "claude-sonnet-4-20250514",
    },
).json()

​

OpenRouter options

Everything works with just llm_provider and model_name. OpenRouter is the one provider with an extra choice to make: it is a gateway, so it serves each model from several upstream providers — Together, Fireworks, DeepInfra and others — and each charges its own rate. By default it picks for you.

Add an optional openrouter object when you want a say in that pick:

response = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "content": "Summarize this thread",
        "llm_provider": "openrouter",
        "model_name": "deepseek/deepseek-chat-v3.1",
        "openrouter": {"sort": "price"},          # or pin one: {"providers": ["Together"]}
    },
).json()

GET /billing/models/providers?model={model_id} lists every upstream serving a model with its rates and uptime. Any upstream_provider value from there can go straight into providers.

​

With the SDKs

from backboard import BackboardClient

async with BackboardClient(api_key="YOUR_API_KEY") as client:
    response = await client.add_message(
        thread_id=thread_id,
        content="Summarize this thread",
        llm_provider="openrouter",
        model_name="moonshotai/kimi-k3",
        openrouter={"providers": ["together"], "allow_fallbacks": False},
    )

Pass the endpoint tag (baseten/fp8) rather than the display name when a provider serves several endpoints — the tag names one endpoint, and therefore one price.

​

Letting OpenRouter pick the model too

Set model_name to openrouter/auto and it chooses the model per prompt. You pay the standard rate of whatever it picks — there is no router fee.

{
  "llm_provider": "openrouter",
  "model_name": "openrouter/auto",
  "openrouter": {"cost_tier": "low"}
}

The response tells you what actually ran: resolved_model and upstream_provider appear alongside cost_usd.

​

What you are billed

The exact amount the serving upstream charged for your request — not an estimate, and for tool-using turns the sum of every leg. The rates shown in the model library are indicative, useful for choosing; the bill comes from the response.

​

Message with file attachments

Use multipart form-data to attach files inline with a message:

import requests

response = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    data={
        "content": "Summarize this document",
        "stream": "false",
    },
    files=[("files", open("report.pdf", "rb"))],
)
print(response.json()["content"])

​

Memory modes

​

JSON output mode

Set json_output=true to request a structured JSON response:

response = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "content": "List 3 planets as JSON with name and diameter_km fields",
        "json_output": True,
    },
).json()
print(response["content"])  # Valid JSON string

​

Voice (TTS & STT)

You can add voice capabilities to any message. Send audio for speech to text, get audio back for text to speech, or both at once.

See Voice (TTS & STT) for file uploads, speech output, and the live STT pipeline. Use Realtime Audio for a model that listens and speaks directly.

​

Thinking (reasoning)

Enable the model to reason step-by-step before answering:

response = requests.post(
    "https://app.backboard.io/api/threads/messages",
    headers=headers,
    json={
        "content": "Why can't you stop on a one-way street if you're walking?",
        "thinking": {"effort": "high"},
        "llm_provider": "openai",
        "model_name": "o3",
    },
).json()

print("Reasoning:", response["reasoning"])
print("Answer:", response["content"])

For supported fields per provider and streaming examples, see Thinking.

​

Related

• Add Message
• Submit Tool Outputs
• First Message (SDK) — send your first message with the SDK
• Tool Calling — handle tool call requests
• Web Search
• Thinking — reasoning configuration per provider
• Voice
• Realtime Audio
• Models — available models and providers