### Get Asset Usage Example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Demonstrates retrieving an asset and accessing its properties.

```python
asset = await server.get_asset("example.com")
print(f"Type: {asset.type}")
print(f"Open ports: {asset.open_ports}")
```

--------------------------------

### Install BBOT Server

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Use uv or pipx to install the BBOT server package.

```bash
# install with uv (recommended)
uv tool install bbot-server

# or with pipx
pipx install bbot-server
```

--------------------------------

### Install from Source

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Clone the repository and synchronize dependencies for development.

```bash
git clone git@github.com:blacklanternsecurity/bbot-server.git && cd bbot-server
uv sync
```

--------------------------------

### API Request Example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Example of a GET request to the assets list endpoint using cURL.

```bash
curl -X GET "http://localhost:8807/v1/assets/list" \
  -H "X-API-Key: deadbeef-9b4d-4208-890c-4ce9ad3b4710"
```

--------------------------------

### List events examples

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Examples of streaming events with various filters.

```python
# Get all DNS events
async for event in server.events.list_events(type="DNS_NAME"):
    print(f"{event.host} -> {event.data}")

# Get events from specific domain
async for event in server.events.list_events(domain="example.com"):
    print(f"Event: {event.type}")

# Get events within time range
import time
yesterday = time.time() - (24 * 3600)
async for event in server.events.list_events(min_timestamp=yesterday):
    print(f"Recent event: {event}")
```

--------------------------------

### Start a New Scan

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/scans.md

Defines the signature for starting a scan and provides an example of initiating one.

```python
async def start_scan(
    target_id: str,
    preset_id: str,
    name: str = None,
    agent_id: UUID = None,
    seed_with_current_assets: bool = False
) -> Scan
```

```python
scan = await server.scans.start_scan(
    target_id="my_target",
    preset_id="subdomain-enum",
    name="scan_20240715"
)
print(f"Scan {scan.name} queued with ID {scan.id}")
```

--------------------------------

### Get Asset History Usage Example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Demonstrates retrieving and iterating through the activity history of an asset.

```python
history = await server.get_asset_history("192.168.1.1")
for activity in history:
    print(f"- {activity}")
```

--------------------------------

### Start Server Without Authentication

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Workaround command to start the server when authentication is incompatible with specific AI clients.

```bash
bbctl server start --no-authentication
```

--------------------------------

### Start BBOT Server

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Launch the server using Docker Compose.

```bash
# Start BBOT server using Docker Compose (pulls from Docker Hub)
bbctl server start
```

--------------------------------

### Insert event example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Example of creating and inserting a new event programmatically.

```python
from bbot.models.pydantic import Event

# Typically created by BBOT scanner, but can be inserted programmatically
event = Event(
    type="DNS_NAME",
    host="sub.example.com",
    data="sub.example.com",
    module="shodan",
    scan="SCAN:uuid"
)
await server.events.insert_event(event)
```

--------------------------------

### Retrieve a Preset

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example usage of the get_preset method.

```python
preset = await server.presets.get_preset("full-scan")
```

--------------------------------

### Count events examples

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Examples of counting events with and without filters.

```python
total = await server.events.count_events()
print(f"Total events: {total}")

from bbot_server.modules.events.events_models import EventsQuery
vuln_count = await server.events.count_events(
    EventsQuery(type="VULNERABILITY")
)
print(f"Vulnerabilities: {vuln_count}")
```

--------------------------------

### GET /presets/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Stream all presets.

```APIDOC
## GET /presets/list

### Description
Stream all presets.

### Method
GET

### Endpoint
/presets/list

### Response
#### Success Response (200)
- **Presets** (AsyncIterator) - Yields Preset objects
```

--------------------------------

### BBOTServer Usage Example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/bbotserver-interface.md

Demonstrates initializing both local and remote interfaces and performing basic operations.

```python
import asyncio
from bbot_server import BBOTServer

async def main():
    # Local interface - direct database access
    server = BBOTServer(interface="python")
    await server.setup()
    
    # Remote interface - HTTP API
    server = BBOTServer(interface="http", url="http://localhost:8807/v1/")
    await server.setup()
    
    # Use the interface
    hosts = await server.get_hosts()
    print(f"Found {len(hosts)} hosts")
    
    await server.cleanup()

asyncio.run(main())
```

--------------------------------

### Start Test Infrastructure

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/AGENTS.md

Commands to initialize MongoDB and Redis containers for the test environment.

```bash
# Start MongoDB (if not already running)
docker ps | grep -q mongo || docker run -d --name bbot-mongo --ulimit nofile=64000:64000 --rm -p 127.0.0.1:27017:27017 mongo

# Start Redis (if not already running)
docker ps | grep -q redis || docker run -d --name bbot-redis --rm -p 127.0.0.1:6379:6379 redis
```

--------------------------------

### Deploy with Helm

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Add the Helm repository and install the BBOT server chart.

```bash
# Add the Helm repo
helm repo add blacklanternsecurity https://blacklanternsecurity.github.io/bbot-server

# Install
helm install bbot blacklanternsecurity/bbot-server-helm
```

```bash
helm install bbot oci://registry-1.docker.io/blacklanternsecurity/bbot-server-helm
```

--------------------------------

### Start Server in Development Mode

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Use the --dev flag to build from source and enable live reloading.

```bash
# From the bbot-server repo root
bbctl server --dev start
```

--------------------------------

### Minimal Configuration Example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

A basic YAML configuration defining essential connectivity and storage settings.

```yaml
url: http://localhost:8807/v1/

auth_enabled: true
auth_header: X-API-Key
api_keys:
  - deadbeef-9b4d-4208-890c-4ce9ad3b4710

event_store:
  uri: mongodb://localhost:27017/bbot_server

asset_store:
  uri: mongodb://localhost:27017/bbot_server

user_store:
  uri: mongodb://localhost:27017/bbot_server

message_queue:
  uri: redis://localhost:6379/0
```

--------------------------------

### Complete Configuration Example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

A comprehensive YAML configuration including authentication, database, agent, CLI, and module-specific settings.

```yaml
# Server Configuration
url: http://localhost:8807/v1/

# Authentication
auth_enabled: true
auth_header: X-API-Key
api_keys:
  - deadbeef-9b4d-4208-890c-4ce9ad3b4710
  - 12345678-1234-5678-1234-567812345678

# Database Configuration
event_store:
  uri: mongodb://localhost:27017/bbot_server
  collection_prefix: ""

asset_store:
  uri: mongodb://localhost:27017/bbot_server
  collection_prefix: ""

user_store:
  uri: mongodb://localhost:27017/bbot_server
  collection_prefix: ""

# Message Queue
message_queue:
  uri: redis://localhost:6379/0

# Index Management
reconcile_indexes: true

# Agent Configuration
agent:
  base_preset:
    modules:
      - nmap
      - nuclei

# CLI Configuration
cli:
  http_timeout: 90
  tui_page_size: 25

# Module-Specific Configuration
modules:
  nmap:
    timeout: 60
    aggressive: true
  nuclei:
    severity: critical,high
```

--------------------------------

### Get event example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Retrieving a specific event by its UUID.

```python
event = await server.events.get_event("12345678-1234-5678-1234-567812345678")
print(f"Event type: {event.type}, Host: {event.host}")
```

--------------------------------

### Get Asset Detail Endpoint

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Endpoint definition and example for retrieving a single asset.

```http
GET /assets/{host}/detail
```

```bash
curl "http://localhost:8807/v1/assets/example.com/detail" \
  -H "X-API-Key: deadbeef..."
```

--------------------------------

### List Assets Usage Examples

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Demonstrates listing all assets, filtering by domain, and filtering by target ID.

```python
# List all assets
async for asset in server.assets.list_assets():
    print(f"Host: {asset.host}")

# Filter by domain
async for asset in server.assets.list_assets(domain="example.com"):
    print(f"Found subdomain: {asset.host}")

# Filter by target
async for asset in server.assets.list_assets(target_id="my_target"):
    print(f"Target asset: {asset.host}")
```

--------------------------------

### Initialize BBOT Server and Access Child Applets

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Instantiate the BBOTServer and use the setup method to access child applets like assets, scans, and targets.

```python
server = BBOTServer(interface="python")
await server.setup()

# Access child applets
await server.assets.get_hosts()
await server.scans.get_scan("scan_id")
await server.targets.create_target(...)
```

--------------------------------

### Retrieve a target

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example of fetching a target by its identifier.

```python
target = await server.targets.get_target("evilcorp")
print(f"Target scope: {target.target}")
```

--------------------------------

### GET /targets/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Stream all targets.

```APIDOC
## GET /targets/list

### Description
Stream all targets.

### Method
GET

### Endpoint
/targets/list

### Response
#### Success Response (200)
- **Target** (object) - Yields Target objects
```

--------------------------------

### Connect to Remote BBOT Server

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/bbotserver-interface.md

Example demonstrating how to initialize the BBOTServer with the HTTP interface and perform basic operations.

```python
import asyncio
from bbot_server import BBOTServer

async def main():
    # Connect to remote server
    server = BBOTServer(interface="http", url="http://192.168.1.100:8807/v1/")
    await server.setup()
    
    # All method calls are forwarded as HTTP requests with authentication
    assets = []
    async for asset in server.list_assets():
        assets.append(asset)
    
    print(f"Found {len(assets)} assets")
    
    await server.cleanup()

asyncio.run(main())
```

--------------------------------

### Start BBOT Server with Network Access

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Expose the BBOT Server to the network by binding to all interfaces.

```bash
bbctl server start --listen 0.0.0.0
```

--------------------------------

### Initiate Server-Side Scan

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Start a scan using previously defined presets and targets.

```bash
# start the scan
bbctl scan start --preset my_preset --target my_target --name "demonic_jimmy"
```

--------------------------------

### Stream All Presets

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example usage of the get_presets method to iterate through all available presets.

```python
async for preset in server.presets.get_presets():
    print(f"Preset: {preset.name}")
```

--------------------------------

### GET /scans/list_brief

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/scans.md

Get all scans in a brief format without full target and preset information.

```APIDOC
## GET /scans/list_brief

### Description
Get all scans in a brief format without full target and preset information (MCP-enabled).

### Method
GET

### Endpoint
/scans/list_brief

### Response
#### Success Response (200)
- **list[dict]** - Scans with only name, id, target.name, and preset.name fields
```

--------------------------------

### Stream all targets

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example of iterating through all targets and printing their scope size.

```python
async for target in server.targets.get_targets():
    print(f"{target.name}: {len(target.target)} hosts in scope")
```

--------------------------------

### GET /resource/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

List or stream resources from the server.

```APIDOC
## GET /resource/list

### Description
List or stream resources from the server.

### Method
GET

### Endpoint
/resource/list
```

--------------------------------

### Query events example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Advanced querying using an EventsQuery object.

```python
from bbot_server.modules.events.events_models import EventsQuery

query = EventsQuery(
    type="VULNERABILITY",
    fields=["type", "host", "data_json"]
)
async for event in server.events.query_events(query):
    print(f"Vulnerability on {event['host']}: {event['data_json']}")
```

--------------------------------

### BBOT Server Configuration File

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Examples of the YAML configuration file structure for API keys and server URLs.

```yaml
# ~/.config/bbot_server/config.yml

# list of API keys to be considered valid
api_keys:
  - deadbeef-9b4d-4208-890c-4ce9ad3b4710
```

```yaml
# ~/.config/bbot_server/config.yml
url: http://1.2.3.4:8807/v1/
api_keys:
  - deadbeef-9b4d-4208-890c-4ce9ad3b4710
```

--------------------------------

### Deploy BBOT Server via Helm

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Command to install the BBOT server chart using a custom values file.

```bash
helm install bbot oci://registry-1.docker.io/blacklanternsecurity/bbot-server-helm \
  -f values.yaml
```

--------------------------------

### Delete a Preset

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example usage of the delete_preset method.

```python
await server.presets.delete_preset("old-preset")
```

--------------------------------

### Handle BBOTServerError

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/errors.md

Example of catching and accessing details from a BBOTServerError.

```python
from bbot_server.errors import BBOTServerError

try:
    # some operation
    raise BBOTServerError("Something went wrong")
except BBOTServerError as e:
    print(f"Error: {e}")
    print(f"Details: {e.detail}")
```

--------------------------------

### Count Assets Usage Examples

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Demonstrates counting all assets and counting assets filtered by type.

```python
count = await server.count_assets()
print(f"Total assets: {count}")

# Count by type
from bbot_server.modules.assets.assets_models import AdvancedAssetQuery
query = AdvancedAssetQuery(query={"type": "IP_ADDRESS"})
ip_count = await server.count_assets(query)
print(f"IP addresses: {ip_count}")
```

--------------------------------

### GET /presets/get/{id}

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Retrieve a preset by ID or name.

```APIDOC
## GET /presets/get/{id}

### Description
Retrieve a preset by ID or name.

### Method
GET

### Endpoint
/presets/get/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - Preset ID or name

### Response
#### Success Response (200)
- **Preset** (object) - The preset object
```

--------------------------------

### Define BBOT Preset Format

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example structure for a BBOT preset configuration dictionary.

```python
{
    "name": "subdomain-enum",
    "description": "Find all subdomains",
    "include": ["subdomain-enum"],
    "modules": ["amass", "sublist3r"],
    "config": {
        "modules": {
            "virustotal": {
                "api_key": "your_key"
            }
        }
    }
}
```

--------------------------------

### Create a Scan Preset

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example usage of the create_preset method to define a full reconnaissance scan.

```python
preset = await server.presets.create_preset({
    "name": "full-scan",
    "description": "Complete reconnaissance scan",
    "include": ["subdomain-enum", "port-enum", "service-enum"],
    "config": {
        "modules": {
            "nmap": {
                "timeout": 60
            }
        }
    }
})
```

--------------------------------

### Query Assets Usage Example

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Demonstrates using AdvancedAssetQuery to filter assets by type and select specific fields.

```python
from bbot_server.modules.assets.assets_models import AdvancedAssetQuery

query = AdvancedAssetQuery(
    query={"type": "IP_ADDRESS"},
    fields=["host", "open_ports"],
    limit=100
)
async for asset in server.query_assets(query):
    print(asset)
```

--------------------------------

### Create a new target

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example usage of creating a target with specific scope and blacklist parameters.

```python
target = await server.targets.create_target(
    name="evilcorp",
    target=["evilcorp.com", "evilcorp.io"],
    blacklist=["internal.evilcorp.com"],
    description="Main evilcorp infrastructure"
)
print(f"Created target: {target.name} (ID: {target.id})")
```

--------------------------------

### Initialize BBOTServer with Configuration

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Create a server instance with custom configuration overrides.

```python
from bbot_server import BBOTServer

# Use config overrides
server = BBOTServer(
    interface="python",
    config={
        "url": "http://localhost:8807/v1/",
        "modules": {
            "nmap": {
                "timeout": 60
            }
        }
    }
)
await server.setup()
```

--------------------------------

### Launch the TUI

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Command to start the interactive Terminal User Interface dashboard.

```bash
bbctl ui
```

--------------------------------

### Update a Preset

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example usage of the update_preset method to modify an existing preset.

```python
updated = await server.presets.update_preset(
    "full-scan",
    {
        "name": "full-scan",
        "include": ["subdomain-enum", "port-enum", "service-enum", "vulnerability-enum"]
    }
)
```

--------------------------------

### GET /assets/{host}/detail

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Retrieve a single asset by its hostname or IP address.

```APIDOC
## GET /assets/{host}/detail

### Description
Retrieve a single asset by its hostname.

### Method
GET

### Endpoint
/assets/{host}/detail

### Parameters
#### Path Parameters
- **host** (str) - Required - The hostname or IP address to retrieve

### Response
#### Success Response (200)
- **Asset** (object) - The asset model
```

--------------------------------

### Initialize and Use BBOT Server

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/00-START-HERE.md

Demonstrates the basic lifecycle of the BBOT Server, including initialization, target creation, asset listing, and cleanup.

```python
import asyncio
from bbot_server import BBOTServer

async def main():
    # Initialize
    server = BBOTServer(interface="python")
    await server.setup()
    
    # Create a target
    target = await server.targets.create_target(
        name="evilcorp",
        target=["evilcorp.com"]
    )
    
    # List assets
    async for asset in server.assets.list_assets():
        print(f"Asset: {asset.host}")
    
    # Cleanup
    await server.cleanup()

asyncio.run(main())
```

--------------------------------

### Raise BBOTServerNotFoundError

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/errors.md

Usage example for raising a not found error when a database lookup fails.

```python
from bbot_server.errors import BBOTServerNotFoundError

async def get_asset(host: str):
    asset = await self.collection.find_one({"host": host})
    if not asset:
        raise BBOTServerNotFoundError(f"Asset {host} not found")
    return asset
```

--------------------------------

### Asynchronous Python Interface Usage

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/bbotserver-interface.md

Example of using the Python interface in asynchronous mode.

```python
import asyncio
from bbot_server import BBOTServer

async def main():
    server = BBOTServer(interface="python")
    await server.setup()
    
    hosts = await server.get_hosts()
    print(f"hosts: {hosts}")
    
    await server.cleanup()
```

--------------------------------

### Configure Basic Server Settings via Environment Variables

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Set core server URL and authentication parameters using environment variables.

```bash
# Server URL
export BBOT_SERVER_URL="http://localhost:8807/v1/"

# Authentication
export BBOT_SERVER_AUTH_ENABLED=true
export BBOT_SERVER_AUTH_HEADER="X-API-Key"
export BBOT_SERVER_API_KEY="deadbeef-9b4d-4208-890c-4ce9ad3b4710"
```

--------------------------------

### GET /assets/{host}/history

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Get the complete activity history for a specific asset.

```APIDOC
## GET /assets/{host}/history

### Description
Get the complete activity history for a specific asset (MCP-enabled).

### Method
GET

### Endpoint
/assets/{host}/history

### Parameters
#### Path Parameters
- **host** (str) - Required - The hostname or IP address

### Response
#### Success Response (200)
- **history** (list[str]) - Ordered list of activity descriptions for this asset
```

--------------------------------

### Get Brief Scan List

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/scans.md

Retrieves a list of scans with minimal information.

```python
async def get_scans_brief() -> list[dict]
```

```python
brief_scans = await server.scans.get_scans_brief()
for scan in brief_scans:
    print(f"{scan['name']} on target {scan['target']['name']}")
```

--------------------------------

### GET /assets/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Stream assets with optional filtering by domain, target, or limit.

```APIDOC
## GET /assets/list

### Description
Stream assets with optional filtering.

### Method
GET

### Endpoint
/assets/list

### Parameters
#### Query Parameters
- **domain** (string) - Optional - Filter by domain or subdomain
- **target_id** (string) - Optional - Filter by target ID or name
- **limit** (integer) - Optional - Limit number of results

### Response
#### Success Response (200)
- **data** (NDJSON) - Streaming JSON (Asset objects)
```

--------------------------------

### GET /assets/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Stream all assets with optional filtering by domain or target ID.

```APIDOC
## GET /assets/list

### Description
Stream all assets with optional filtering.

### Method
GET

### Endpoint
/assets/list

### Parameters
#### Query Parameters
- **domain** (str) - Optional - Filter assets by domain or subdomain.
- **target_id** (str) - Optional - Filter assets by target ID or name.
- **limit** (int) - Optional - Limit the number of assets returned.

### Response
#### Success Response (200)
- **Asset** (object) - Yields Asset objects as they are retrieved from the database
```

--------------------------------

### GET /agents/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/agents.md

Stream all registered agents.

```APIDOC
## GET /agents/list

### Description
Stream all agents.

### Method
GET

### Endpoint
/agents/list

### Response
#### Success Response (200)
- **Agent** (AsyncIterator) - Yields Agent objects
```

--------------------------------

### Get Activity Timeline for Asset with Python

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/activity.md

Retrieves the full activity history for a specific host and formats it into a list of dictionaries.

```python
async def get_asset_timeline(server, host):
    """Get complete activity history for an asset"""
    activities = []
    async for activity in server.activity.list_activities(host=host):
        activities.append({
            "time": activity.timestamp,
            "type": activity.type,
            "description": activity.description,
            "details": activity.detail
        })
    return activities
```

--------------------------------

### Initialize BBOT Server Interface

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Demonstrates how to initialize the BBOTServer for either local database access or remote HTTP API interaction.

```python
import asyncio
from bbot_server import BBOTServer

# Local interface (direct database access)
server = BBOTServer(interface="python")

# Remote interface (HTTP API)
server = BBOTServer(interface="http", url="http://localhost:8807/v1/")

async def main():
    await server.setup()
    # Use server...
    await server.cleanup()

asyncio.run(main())
```

--------------------------------

### GET /scans/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/scans.md

Stream all scans in the database.

```APIDOC
## GET /scans/list

### Description
Stream all scans in the database.

### Method
GET

### Endpoint
/scans/list

### Response
#### Success Response (200)
- **Scan** (AsyncIterator) - Yields Scan objects
```

--------------------------------

### GET /activity/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/activity.md

Stream activities with optional filtering by host, domain, type, or result limit.

```APIDOC
## GET /activity/list

### Description
Stream activities with optional filtering.

### Method
GET

### Endpoint
/activity/list

### Parameters
#### Query Parameters
- **host** (str) - Optional - Filter by specific hostname or IP
- **domain** (str) - Optional - Filter by domain or subdomain
- **type** (str) - Optional - Filter by activity type (e.g., "NEW_FINDING", "PORT_OPENED")
- **limit** (int) - Optional - Limit number of results

### Response
#### Success Response (200)
- **Activity** (AsyncIterator) - yields Activity objects
```

--------------------------------

### POST /presets/create

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Create a new BBOT preset.

```APIDOC
## POST /presets/create

### Description
Create a new BBOT preset.

### Method
POST

### Endpoint
/presets/create

### Request Body
- **name** (string) - Required - Preset name
- **description** (string) - Optional - Preset description
- **include** (array) - Optional - Included modules
- **config** (object) - Optional - Configuration settings

### Response
#### Success Response (200)
- **Preset object** (object) - The created preset object
```

--------------------------------

### Handle Asset Update Failures

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/errors.md

Example of performing a strict collection update with an upsert operation.

```python
# This will fail silently or create if not found (depending on upsert setting)
await self.strict_collection.update_one(
    {"host": host},
    {"$set": asset.model_dump()},
    upsert=True
)
```

--------------------------------

### Delete a target

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example of removing a target from the server.

```python
await server.targets.delete_target("old_target")
```

--------------------------------

### View Configuration File Locations

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Displays the standard paths for user and default configuration files.

```text
~/.config/bbot_server/config.yml    # User configuration (recommended)
/path/to/bbot_server/defaults.yml   # Package defaults (read-only)
```

--------------------------------

### Asynchronous BBOT Server Interaction

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Use this pattern for non-blocking operations. Requires an awaitable setup and asynchronous method calls.

```python
import asyncio
from bbot_server import BBOTServer

async def main():
    # talk directly to local MongoDB + Redis
    bbot_server = BBOTServer(interface="python")

    # or to a remote BBOT Server instance (config must contain a valid API key)
    bbot_server = BBOTServer(interface="http", url="http://bbot:8807/v1/")

    # one-time setup
    await bbot_server.setup()

    hosts = await bbot_server.get_hosts()
    print(f"hosts: {hosts}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### BBOT Server Initialization

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Demonstrates how to initialize the BBOT Server interface for either local Python access or remote HTTP API interaction.

```APIDOC
## Initialize BBOT Server Interface

### Description
Initializes the BBOT Server client to interact with the system via local database access or a remote HTTP API.

### Usage
```python
from bbot_server import BBOTServer

# Local interface
server = BBOTServer(interface="python")

# Remote interface
server = BBOTServer(interface="http", url="http://localhost:8807/v1/")
```
```

--------------------------------

### Get event signature

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Signature for the get_event method.

```python
async def get_event(uuid: str) -> Event
```

--------------------------------

### POST /presets/create

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Create a new scan preset.

```APIDOC
## POST /presets/create

### Description
Create a new scan preset.

### Method
POST

### Endpoint
/presets/create

### Request Body
- **preset** (dict) - Required - BBOT preset configuration (include, modules, config, etc.)

### Response
#### Success Response (200)
- **Preset** (object) - The created preset object
```

--------------------------------

### Register an Agent

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/agents.md

Creates a new agent instance on the server during startup.

```python
# Agent registers itself on startup
agent = await server.agents.create_agent(
    name="my-agent",
    description="Scanning agent"
)
```

--------------------------------

### Get Finding

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Retrieve a specific finding by its unique ID.

```http
GET /findings/get
```

--------------------------------

### Start Scan Endpoint

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Endpoint to create and queue a new scan. Requires a JSON body with target and preset identifiers.

```http
POST /scans/start
```

```json
{
  "target_id": "my_target",
  "preset_id": "subdomain-enum",
  "name": "scan_name",
  "agent_id": "uuid",
  "seed_with_current_assets": false
}
```

```bash
curl -X POST "http://localhost:8807/v1/scans/start" \
  -H "X-API-Key: deadbeef..." \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "evilcorp",
    "preset_id": "full-scan",
    "name": "recon_2024"
  }'
```

--------------------------------

### GET /events/list

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Stream events with optional filtering criteria.

```APIDOC
## GET /events/list

### Description
Stream events with optional filtering.

### Method
GET

### Endpoint
/events/list

### Parameters
#### Query Parameters
- **type** (str) - Optional - Filter by event type
- **host** (str) - Optional - Filter by exact hostname or IP address
- **domain** (str) - Optional - Filter by domain or subdomain
- **scan** (str) - Optional - Filter by BBOT scan ID
- **min_timestamp** (float) - Optional - Filter by minimum timestamp
- **max_timestamp** (float) - Optional - Filter by maximum timestamp
- **active** (bool) - Optional - Include non-archived events (Default: True)
- **archived** (bool) - Optional - Include archived events (Default: False)

### Response
#### Success Response (200)
- **events** (AsyncIterator[Event]) - Yields Event objects
```

--------------------------------

### POST /scans/start

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/scans.md

Create and queue a new scan for execution.

```APIDOC
## POST /scans/start

### Description
Create and queue a new scan for execution.

### Method
POST

### Endpoint
/scans/start

### Parameters
#### Request Body
- **target_id** (str) - Required - Target ID or name to scan
- **preset_id** (str) - Required - Preset ID or name containing scan configuration
- **name** (str) - Optional - Human-readable scan name (must be unique). If not provided, a random name is generated.
- **agent_id** (UUID) - Optional - Specific agent to run the scan. If None, any ready agent can claim it.
- **seed_with_current_assets** (bool) - Optional - If True, seed the scan with all currently known hosts matching the target

### Response
#### Success Response (200)
- **Scan** (object) - The newly created scan object with status "QUEUED"
```

--------------------------------

### GET /scans/queued

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/scans.md

List all scans waiting to be assigned to an agent.

```APIDOC
## GET /scans/queued

### Description
List all scans waiting to be assigned to an agent.

### Method
GET

### Endpoint
/scans/queued

### Response
#### Success Response (200)
- **list[Scan]** - Scans with status "QUEUED", ordered by creation time (oldest first)
```

--------------------------------

### GET /findings/get

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/findings.md

Retrieve a single finding by its unique ID.

```APIDOC
## GET /findings/get

### Description
Retrieve a single finding by its ID.

### Method
GET

### Endpoint
/findings/get

### Parameters
#### Query Parameters
- **id** (str) - Required - The finding ID

### Response
#### Success Response (200)
- **Finding** (object) - The finding object
```

--------------------------------

### Track Host Lifecycle with Python

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/activity.md

Parses activity descriptions to build a structured timeline of host discovery, ports, technologies, and findings.

```python
async def get_host_discovery_info(server, host):
    """Get detailed discovery timeline for a host"""
    timeline = {
        "host": host,
        "discovered": None,
        "ports_opened": [],
        "technologies": [],
        "findings": []
    }
    
    async for activity in server.activity.list_activities(host=host):
        if "discovered" in activity.description.lower():
            timeline["discovered"] = activity.created
        elif "port" in activity.description.lower():
            timeline["ports_opened"].append({
                "time": activity.created,
                "description": activity.description
            })
        elif "technology" in activity.description.lower():
            timeline["technologies"].append(activity.detail)
        elif "finding" in activity.description.lower():
            timeline["findings"].append(activity.detail)
    
    return timeline
```

--------------------------------

### server.agents.execute_agent_command

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/agents.md

Sends a command to a specific agent, such as starting a scan.

```APIDOC
## server.agents.execute_agent_command

### Description
Assigns a command to a ready agent.

### Parameters
- **agent_id** (UUID) - Required - Unique agent identifier
- **command** (str) - Required - Command to execute (e.g., "start_scan")
- **scan_id** (str) - Optional - ID of the scan to execute
- **preset** (str) - Optional - Scan preset configuration
```

--------------------------------

### Update an existing target

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Example of updating the blacklist for a specific target.

```python
from bbot_server.modules.targets.targets_models import CreateTarget

updated = await server.targets.update_target(
    "evilcorp",
    CreateTarget(
        blacklist=["internal.evilcorp.com", "staging.evilcorp.com"]
    )
)
```

--------------------------------

### Deploy BBOT Server with Docker

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Configure the server container using environment variables for connectivity and authentication.

```bash
docker run \
  -e BBOT_SERVER_URL="http://bbot-server:8807/v1/" \
  -e BBOT_SERVER_AUTH_ENABLED=true \
  -e BBOT_SERVER_AUTH_HEADER="X-API-Key" \
  -e BBOT_SERVER_API_KEY="deadbeef-9b4d-4208-890c-4ce9ad3b4710" \
  -e BBOT_SERVER_EVENT_STORE__URI="mongodb://mongo:27017/bbot_server" \
  -e BBOT_SERVER_ASSET_STORE__URI="mongodb://mongo:27017/bbot_server" \
  -e BBOT_SERVER_USER_STORE__URI="mongodb://mongo:27017/bbot_server" \
  -e BBOT_SERVER_MESSAGE_QUEUE__URI="redis://redis:6379/0" \
  blacklanternsecurity/bbot-server
```

--------------------------------

### BBOTServer SDK Workflow

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/bbotserver-interface.md

Demonstrates the standard lifecycle of a BBOT scan, including target creation, preset configuration, scan initiation, and asset retrieval.

```APIDOC
## BBOTServer SDK Workflow

### Description
This workflow demonstrates how to initialize the BBOTServer, create targets and presets, start a scan, and query discovered assets using the Python SDK.

### Usage
```python
import asyncio
from bbot_server import BBOTServer

# Initialize
server = BBOTServer(interface="python")
await server.setup()

# Create target
target = await server.targets.create_target(name="example_target", target=["example.com"])

# Create preset
preset = await server.presets.create_preset(name="example_preset", preset={"modules": ["nmap"], "config": {}})

# Start scan
scan = await server.scans.start_scan(target_id=str(target.id), preset_id=str(preset.id), name="example_scan")

# Query assets
hosts = await server.get_hosts(target_id=str(target.id))
```
```

--------------------------------

### Count Agents

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Get the total number of agents as a JSON integer.

```http
POST /agents/count
```

--------------------------------

### Configure BBOT Server via Environment Variables

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Set server configuration using environment variables with double underscore delimiters for nested fields.

```bash
# Server URL
export BBOT_SERVER_URL="http://localhost:8807/v1/"

# Authentication
export BBOT_SERVER_AUTH_ENABLED=true
export BBOT_SERVER_AUTH_HEADER="X-API-Key"
export BBOT_SERVER_API_KEY="deadbeef-9b4d-4208-890c-4ce9ad3b4710"

# Database URIs (nested configs)
export BBOT_SERVER_EVENT_STORE__URI="mongodb://localhost:27017/bbot_server"
export BBOT_SERVER_ASSET_STORE__URI="mongodb://localhost:27017/bbot_server"
export BBOT_SERVER_USER_STORE__URI="mongodb://localhost:27017/bbot_server"

# Message Queue URI
export BBOT_SERVER_MESSAGE_QUEUE__URI="redis://localhost:6379/0"

# Agent configuration
export BBOT_SERVER_AGENT__BASE_PRESET='{"modules": ["nmap"]}'

# CLI configuration
export BBOT_SERVER_CLI__HTTP_TIMEOUT=90

# Module-specific configuration (double-nested)
export BBOT_SERVER_MODULES__SOME_MODULE__SOME_OPTION="value"
```

--------------------------------

### Get Severity Counts

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Retrieve findings grouped by severity level.

```http
GET /findings/stats_by_severity
```

--------------------------------

### Get Preset Endpoint

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Retrieves a specific preset by its ID or name.

```http
GET /presets/get/{id}
```

--------------------------------

### Get Target Endpoint

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Retrieves a specific target by its ID or name.

```http
GET /targets/get/{id}
```

--------------------------------

### GET /resource/get/{id}

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Retrieve a single resource by its unique identifier.

```APIDOC
## GET /resource/get/{id}

### Description
Retrieve a single resource by its unique identifier.

### Method
GET

### Endpoint
/resource/get/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the resource.
```

--------------------------------

### GET /targets/get/{id}

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Retrieve a single target by ID or name.

```APIDOC
## GET /targets/get/{id}

### Description
Retrieve a single target by ID or name.

### Method
GET

### Endpoint
/targets/get/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - Target ID or name

### Response
#### Success Response (200)
- **Target** (object) - The target object
```

--------------------------------

### Manage Configuration via CLI

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Commands to view and edit the user configuration file.

```bash
# View current configuration
cat ~/.config/bbot_server/config.yml

# Edit configuration
nano ~/.config/bbot_server/config.yml
```

--------------------------------

### GET /events/get/{uuid}

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/events.md

Retrieve a single event by its unique identifier.

```APIDOC
## GET /events/get/{uuid}

### Description
Retrieve a single event by its UUID.

### Method
GET

### Endpoint
/events/get/{uuid}

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The event's UUID

### Response
#### Success Response (200)
- **event** (Event) - The event object
```

--------------------------------

### GET /scans/get/{id}

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/scans.md

Retrieve a single scan by ID or name.

```APIDOC
## GET /scans/get/{id}

### Description
Retrieve a single scan by ID or name.

### Method
GET

### Endpoint
/scans/get/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - Scan ID (SCAN:uuid format) or scan name

### Response
#### Success Response (200)
- **Scan** (object) - The scan object
```

--------------------------------

### run_reconnaissance

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Demonstrates the workflow for defining a target, creating a scan preset, initiating a scan, and monitoring activity logs.

```APIDOC
## Method: run_reconnaissance(server)

### Description
Executes a full reconnaissance workflow by creating a target, defining a scan preset, starting the scan, and tailing activity logs.

### Parameters
- **server** (object) - The BBOT server instance.

### Usage Example
```python
await run_reconnaissance(server)
```
```

--------------------------------

### List Assets Endpoint

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Endpoint definition and example for listing assets with filtering.

```http
GET /assets/list
```

```bash
curl "http://localhost:8807/v1/assets/list?domain=example.com" \
  -H "X-API-Key: deadbeef..."
```

--------------------------------

### Execute BBOT Scan with Server Output

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/README.md

Run a scan using the server output configuration file.

```bash
# Start a BBOT scan, sending output to BBOT server
bbot -t evilcorp.com -p subdomain-enum ./bbot-server.yml
```

--------------------------------

### Manage API Keys via CLI

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Use bbctl commands to add, list, or revoke API keys.

```bash
# Generate and add a new API key
bbctl server apikey add

# List all API keys
bbctl server apikey list

# Revoke an API key
bbctl server apikey delete deadbeef-9b4d-4208-890c-4ce9ad3b4710
```

--------------------------------

### Configure Nested Settings via Environment Variables

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Use double underscores to define nested configuration fields for databases, queues, and module-specific settings.

```bash
# Database URIs (nested configs use __ delimiter)
export BBOT_SERVER_EVENT_STORE__URI="mongodb://localhost:27017/bbot_server"
export BBOT_SERVER_ASSET_STORE__URI="mongodb://localhost:27017/bbot_server"
export BBOT_SERVER_USER_STORE__URI="mongodb://localhost:27017/bbot_server"

# Message Queue
export BBOT_SERVER_MESSAGE_QUEUE__URI="redis://localhost:6379/0"

# Agent Configuration
export BBOT_SERVER_AGENT__BASE_PRESET='{"modules": ["nmap"]}'

# CLI Configuration
export BBOT_SERVER_CLI__HTTP_TIMEOUT=90
export BBOT_SERVER_CLI__TUI_PAGE_SIZE=25

# Module-Specific Configuration
export BBOT_SERVER_MODULES__NMAP__TIMEOUT=60
export BBOT_SERVER_MODULES__NUCLEI__SEVERITY="critical,high"
```

--------------------------------

### Get Agent

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Retrieve details for a specific agent using its ID or name.

```http
GET /agents/get/{id}
```

--------------------------------

### Get Queued Scans Endpoint

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

List all scans currently waiting for assignment.

```http
GET /scans/queued
```

--------------------------------

### POST /resource/create

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Create a new resource on the server.

```APIDOC
## POST /resource/create

### Description
Create a new resource on the server.

### Method
POST

### Endpoint
/resource/create
```

--------------------------------

### Get Event Endpoint

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Retrieves a single event object by its unique UUID.

```http
GET /events/get/{uuid}
```

--------------------------------

### Load and Access Configuration in Python

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/configuration.md

Access configuration values and validate API keys using the BBOT_SERVER_CONFIG object.

```python
from bbot_server.config import BBOT_SERVER_CONFIG as bbcfg

# Access configuration values
url = bbcfg.url
api_keys = bbcfg.get_api_keys()
api_key = bbcfg.get_api_key()

# Check if a key is valid
is_valid, message = bbcfg.check_api_key("some-uuid-string")
```

--------------------------------

### GET /agents/online

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/agents.md

Retrieve all currently connected agents, with an optional status filter.

```APIDOC
## GET /agents/online

### Description
Get all currently connected agents with optional status filter.

### Method
GET

### Endpoint
/agents/online

### Parameters
#### Query Parameters
- **status** (str) - Optional - Filter by agent status (READY, RUNNING, IDLE, OFFLINE)

### Response
#### Success Response (200)
- **agents** (list) - List of agents that are currently connected
```

--------------------------------

### Run Reconnaissance Workflow

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Defines a target, configures a scan preset, initiates the scan, and monitors real-time activity.

```python
async def run_reconnaissance(server):
    # 1. Define scope
    target = await server.targets.create_target(
        name="evilcorp",
        target=["evilcorp.com"],
        blacklist=["internal.evilcorp.com"]
    )
    
    # 2. Create scan configuration
    preset = await server.presets.create_preset({
        "name": "full-enum",
        "include": ["subdomain-enum", "port-enum"],
        "config": {"modules": {"nmap": {"timeout": 60}}}
    })
    
    # 3. Start scan
    scan = await server.scans.start_scan(
        target_id=str(target.id),
        preset_id=str(preset.id),
        name="recon_2024"
    )
    
    # 4. Monitor progress
    async for activity in server.activity.tail_activities():
        print(f"[{activity.type}] {activity.description}")
```

--------------------------------

### GET /agents/get/{id}

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/agents.md

Retrieve a single agent by its unique ID or name.

```APIDOC
## GET /agents/get/{id}

### Description
Retrieve a single agent by ID or name.

### Method
GET

### Endpoint
/agents/get/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - Agent ID (UUID) or name

### Response
#### Success Response (200)
- **Agent** (object) - The agent object
```

--------------------------------

### Get Asset History Method Signature

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/assets.md

Defines the signature for the get_asset_history method.

```python
async def get_asset_history(host: str) -> list[str]
```

--------------------------------

### BBOTServer HTTP Interface Initialization

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/bbotserver-interface.md

Describes how to initialize the BBOTServer client using the HTTP interface to connect to a remote server.

```APIDOC
## HTTP Interface Initialization

### Description
The HTTP interface connects to a remote BBOT Server instance via its REST API, forwarding all method calls as HTTP requests.

### Constructor Parameters
- **url** (str) - Required - The base URL of the BBOT Server REST API (e.g., "http://localhost:8807/v1/")
- **kwargs** (dict) - Optional - Additional configuration options

### Authentication
The interface automatically includes an `X-API-Key` header in all requests, retrieved from the local configuration file (`~/.config/bbot_server/config.yml`).
```

--------------------------------

### server.presets.create_preset

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/targets-presets.md

Creates a new preset configuration on the server.

```APIDOC
## server.presets.create_preset

### Description
Registers a new preset configuration.

### Parameters
- **preset_data** (dict) - Required - The dictionary containing the preset configuration, including name, includes, and config settings.

### Returns
- **preset** (Preset) - The created preset object.
```

--------------------------------

### List assets with filters

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/api-reference/README.md

Use simple keyword arguments to filter asset listings.

```python
# List with filters
async for asset in server.assets.list_assets(
    domain="example.com",
    target_id="my_target",
    limit=100
):
    print(asset.host)
```

--------------------------------

### Create Agent

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Register a new agent by providing a name and description.

```http
POST /agents/create
```

```json
{
  "name": "agent-1",
  "description": "Primary scanning agent"
}
```

--------------------------------

### NDJSON Streaming Format

Source: https://github.com/blacklanternsecurity/bbot-server/blob/stable/_autodocs/endpoints.md

Example of the newline-delimited JSON format returned by streaming endpoints.

```json
{"item": 1}\n
{"item": 2}\n
{"item": 3}\n
```