> This page is for Alfa (Preview).

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alfa.boosted.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server.

# Source overrides

> **Warning**
>
> 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:

| Field                     | Type               | Description                                                                                                                                                                  |
| ------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update_default_settings` | boolean (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_search`              | string (optional)  | Control web search results. Allowed values: `"all_sources"` `"off"` Default: `null`                                                                                          |
| `web_scraping`            | string (optional)  | Control web scraping capabilities. *Only applicable to agent building.* Allowed values: `"all_sources"` `"off"` Default: `null`                                              |
| `filings`                 | string (optional)  | Control access to company filings (SEC, EDGAR, SEDAR+). Allowed values: `"all_sources"` `"off"` Default: `null`                                                              |
| `earnings`                | string (optional)  | Control access to earnings reports. Allowed values: `"all_sources"` `"off"` Default: `null`                                                                                  |
| `news`                    | string (optional)  | Control access to news content. Allowed values: `"all_sources"` `"off"` Default: `null`                                                                                      |

> **Info**
>
> 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.

**`send_with_overrides.py`**

```python title="send_with_overrides.py"
import os
import json
import requests

BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]

def auth_headers():
    return {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/x-www-form-urlencoded"
    }

def send_message_with_overrides(thread_id: str, message: str, source_config: dict) -> dict:
    # Convert the source config dictionary to a JSON string
    source_overrides_json = json.dumps(source_config)
    
    resp = requests.post(
        f"{BASE_URL}/v2/threads/{thread_id}/messages",
        headers=auth_headers(),
        data={
            "message": message,
            "source_overrides": source_overrides_json
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

# Example: Temporary override for web-only research
source_config = {
    "update_default_settings": False,  # Don't change thread defaults
    "web_search": "all_sources",
    "web_scraping": "all_sources",
    "filings": "off",
    "earnings": "off",
    "news": "off",
}

response = send_message_with_overrides(
    thread_id="thread_abc123",
    message="What are the latest trends in AI technology?",
    source_config=source_config
)
```

**`send_with_overrides.sh`**

```bash title="send_with_overrides.sh"
curl -X POST https://sandbox.api.boosted.ai/v2/threads/<thread_id>/messages \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "message=What are the latest trends in AI technology?" \
     -d 'source_overrides={"update_default_settings":false,"web_search":"all_sources","web_scraping":"all_sources","filings":"off","earnings":"off","news":"off"}'
```

## 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`**

```python title="update_defaults.py"
# This will update the user's default thread message data source settings
source_config = {
    "update_default_settings": True,
    "web_search": "all_sources",
    "news": "all_sources",
}

send_message_with_overrides(
    thread_id="thread_abc123",
    message="What's happening with tech stocks today?",
    source_config=source_config
)

```

> **Warning**
>
> When `source_overrides` is unspecified, it will use the user's default thread message data source settings.

## FAQ

#### Do source overrides affect streaming?

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.

#### What's the difference between temporary and permanent overrides?

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.