Getting StartedThreads

Source overrides

Control data sources on a per-message basis using source overrides.

This API is currently in Preview.

Overview

Source overrides allow you to limit which data sources Alfa uses when processing a specific message, with the option to permanently change the user’s default thread message data source settings.

Available source settings

The source overrides object supports the following fields:

FieldTypeDescription
update_default_settingsboolean (optional)If true, updates the user’s default thread message data source settings with the specified values below. If false, applies only to the current message.
Default: false
web_searchstring (optional)Control web search results.
Allowed values: “all_sources” “off”
Default: null
web_scrapingstring (optional)Control web scraping capabilities. Only applicable to agent building.
Allowed values: “all_sources” “off”
Default: null
filingsstring (optional)Control access to company filings (SEC, EDGAR, SEDAR+).
Allowed values: “all_sources” “off”
Default: null
earningsstring (optional)Control access to earnings reports.
Allowed values: “all_sources” “off”
Default: null
newsstring (optional)Control access to news content.
Allowed values: “all_sources” “off”
Default: null

If you don’t specify a value for a particular source in the override, the thread will use the user’s existing default setting for that source.

Send a message with source overrides

The source_overrides parameter must be a JSON string, not a JSON object. Convert your settings dictionary to a JSON string before including it in the request body.

1import os
2import json
3import requests
4
5BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
6ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
7
8def auth_headers():
9    return {
10        "Authorization": f"Bearer {ACCESS_TOKEN}",
11        "Content-Type": "application/x-www-form-urlencoded"
12    }
13
14def send_message_with_overrides(thread_id: str, message: str, source_config: dict) -> dict:
15    # Convert the source config dictionary to a JSON string
16    source_overrides_json = json.dumps(source_config)
17    
18    resp = requests.post(
19        f"{BASE_URL}/v2/threads/{thread_id}/messages",
20        headers=auth_headers(),
21        data={
22            "message": message,
23            "source_overrides": source_overrides_json
24        },
25        timeout=30,
26    )
27    resp.raise_for_status()
28    return resp.json()
29
30# Example: Temporary override for web-only research
31source_config = {
32    "update_default_settings": False,  # Don't change thread defaults
33    "web_search": "all_sources",
34    "web_scraping": "all_sources",
35    "filings": "off",
36    "earnings": "off",
37    "news": "off",
38}
39
40response = send_message_with_overrides(
41    thread_id="thread_abc123",
42    message="What are the latest trends in AI technology?",
43    source_config=source_config
44)

Update thread defaults

Set update_default_settings: true to permanently update the user’s thread message data source settings. Future messages from this user will now inherit these settings.

update_defaults.py
1# This will update the user's default thread message data source settings
2source_config = {
3    "update_default_settings": True,
4    "web_search": "all_sources",
5    "news": "all_sources",
6}
7
8send_message_with_overrides(
9    thread_id="thread_abc123",
10    message="What's happening with tech stocks today?",
11    source_config=source_config
12)

When source_overrides is unspecified, it will use the user’s default thread message data source settings.

FAQ

No. Source overrides only control which data sources Alfa uses for research. They do not affect how responses are delivered via SSE or gRPC streaming.

Temporary overrides (update_default_settings: false) apply only to the current message, while permanent overrides (update_default_settings: true) update the user’s default settings for all future messages, akin to making a settings change. Use temporary overrides when you need different sources for a single query, and permanent overrides when you want to change the user’s thread message sourcing behavior going forward.