# How the OpenBB Router Command System Processes Incoming Requests: A Complete Technical Guide

> Learn how the OpenBB router command system processes incoming requests. Discover its four-stage pipeline, FastAPI integration, and dependency injection for seamless execution.

- Repository: [OpenBB/OpenBB](https://github.com/OpenBB-finance/OpenBB)
- Tags: internals
- Published: 2026-03-06

---

**The OpenBB router command system processes incoming HTTP requests through a four-stage pipeline that automatically converts decorated Python functions into FastAPI endpoints, injecting provider dependencies and standard parameters before FastAPI handles the request-response cycle.**

The OpenBB router command system serves as the backbone of the OpenBB Platform, transforming data provider functions into fully documented REST API endpoints. Built on top of FastAPI, this system in the OpenBB-finance/OpenBB repository enables automatic endpoint generation through Python decorators, eliminating boilerplate code while maintaining type safety and OpenAPI compliance.

## The Four-Stage Processing Pipeline

The OpenBB router command system handles request processing through four distinct architectural stages, each implemented in [`openbb_platform/core/openbb_core/app/router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/router.py).

### Stage 1: Command Registration via the `@router.command` Decorator

Every data provider function becomes an HTTP endpoint through the `@router.command(...)` decorator, defined in lines 87-129 of [`router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/router.py). When applied to a function, this decorator:

- Collects metadata including `model`, `widget_config`, and `examples`
- Builds the FastAPI route by calling `api_router.add_api_route`
- Stores the endpoint in the internal `Router._api_router` registry

The decorator automatically derives the URL path from the function name (defaulting to `/{func.__name__}`) unless overridden via the `path` parameter.

### Stage 2: Signature Completion and Dependency Injection

Before FastAPI registers the route, the `SignatureInspector.complete` method (lines 31-84 in [`router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/router.py)) examines and augments the function signature. This stage injects three critical dependency types when a `model` argument is supplied:

- **`provider_choices`** → `ProviderInterface().model_providers[model]`
- **`standard_params`** → `ProviderInterface().params[model]["standard"]`
- **`extra_params`** → `ProviderInterface().params[model]["extra"]`

The method also replaces the return annotation with the concrete `OBBject` subclass matching the specified model, ensuring proper response serialization.

### Stage 3: FastAPI Request Handling and Execution

Once the route is registered, FastAPI assumes control of the request lifecycle. When an HTTP request arrives at the defined path:

1. FastAPI resolves the `Depends()` injections created during signature completion
2. The framework calls the original provider function with the injected `provider_choices`, `standard_params`, and `extra_params`
3. The function returns an `OBBject` (or list of `OBBject` instances)
4. FastAPI serializes the response using the `response_model` derived from the function's return annotation

This stage requires no manual intervention from the developer, as the OpenBB router command system has already configured all FastAPI-specific parameters during registration.

### Stage 4: Routing Hierarchy and Extension Discovery

The system supports nested routing through `Router.include_router` (lines 73-86 in [`router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/router.py)), which recursively nests `Router` objects and records them in `Router._routers`. At application startup, `RouterLoader.from_extensions()` (lines 18-27) walks through every extension listed in `ExtensionLoader().core_objects` and constructs the complete route tree.

This hierarchical approach enables the OpenBB router command system to organize endpoints logically (e.g., `/equity/price/`) while maintaining automatic discovery across all installed extensions.

## Practical Implementation: Creating Custom Router Commands

To implement a new endpoint in the OpenBB router command system, developers create a router file within their extension:

```python

# openbb_platform/extensions/equity/openbb_equity/price/price_router.py

from openbb_core.app.router import Router
from openbb_core.app.provider_interface import (
    ProviderChoices,
    StandardParams,
    ExtraParams,
)
from openbb_core.app.model.obbject import OBBject

router = Router(prefix="/price", description="Equity price endpoints")

@router.command(
    model="stock",
    examples=[{"ticker": "AAPL"}],
    widget_config={"height": 400},
)
def get_price(
    ticker: str,
    provider_choices: ProviderChoices,
    standard_params: StandardParams,
    extra_params: ExtraParams,
) -> OBBject:
    """Return price data for a single ticker."""
    return provider_choices.get_price(ticker, standard_params, extra_params)

```

When the application initializes, `RouterLoader` processes this module, invokes `router.include_router`, and registers the endpoint at `/price/get_price`. The decorator automatically generates the following FastAPI route configuration:

```python
api_router.add_api_route(
    path="/get_price",
    endpoint=get_price,
    methods=["GET"],
    response_model=OBBject[PriceResult],
    openapi_extra={
        "model": "stock",
        "widget_config": {"height": 400},
        "examples": [{"ticker": "AAPL"}],
    },
)

```

To inspect the complete command mapping at runtime, use the `CommandMap` utility:

```python
from openbb_core.app.router import CommandMap

cmd_map = CommandMap()
endpoint = cmd_map.get_command("/price/get_price")
print(endpoint)  # <function get_price ...>

```

## Key Source Files and Architecture

The OpenBB router command system is implemented across several critical files in the `openbb_platform/core/openbb_core/app/` directory:

| File | Role | Key Components |
|------|------|----------------|
| [`router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/router.py) | Core router implementation | `Router` class, `@command` decorator (lines 87-129), `SignatureInspector.complete` (lines 31-84), `Router.include_router` (lines 73-86), `RouterLoader.from_extensions` (lines 18-27) |
| [`provider_interface.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/provider_interface.py) | Dependency injection interfaces | `ProviderChoices`, `StandardParams`, `ExtraParams` classes |
| [`extension_loader.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/extension_loader.py) | Extension discovery | `ExtensionLoader` class that identifies core objects for router registration |
| [`model/obbject.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/model/obbject.py) | Response modeling | `OBBject` class used as return type for all commands |

Extension developers implement commands in files following the pattern `openbb_platform/extensions/<extension_name>/openbb_<extension_name>/*_router.py`, such as [`openbb_platform/extensions/equity/openbb_equity/price/price_router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/equity/openbb_equity/price/price_router.py).

## Summary

The OpenBB router command system transforms Python functions into HTTP endpoints through a sophisticated four-stage pipeline:

- **Registration**: The `@router.command` decorator in [`router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/router.py) (lines 87-129) captures metadata and registers routes with FastAPI's `add_api_route`
- **Signature Completion**: `SignatureInspector.complete` (lines 31-84) injects provider dependencies (`ProviderChoices`, `StandardParams`, `ExtraParams`) and sets the `OBBject` response model
- **Request Handling**: FastAPI resolves dependencies, executes the provider function, and serializes the `OBBject` response automatically
- **Hierarchy Management**: `RouterLoader.from_extensions` (lines 18-27) and `include_router` (lines 73-86) build nested route trees from extension modules

This architecture enables plug-and-play API development where data providers simply decorate functions to expose them as fully documented, dependency-injected endpoints.

## Frequently Asked Questions

### How does the OpenBB router command system differ from standard FastAPI routing?

Unlike standard FastAPI routing where developers manually define routes using `@app.get()` or `router.add_api_route()`, the OpenBB router command system uses a higher-level `@router.command` decorator that automatically handles dependency injection, response model binding, and OpenAPI metadata generation. The system inspects function signatures and injects provider-specific dependencies (`ProviderChoices`, `StandardParams`, `ExtraParams`) without requiring manual `Depends()` declarations in the endpoint function.

### What is the purpose of the SignatureInspector in the OpenBB router?

The `SignatureInspector.complete` method, located in [`openbb_platform/core/openbb_core/app/router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/router.py) (lines 31-84), serves as the bridge between provider functions and FastAPI's dependency injection system. It examines the function signature before route registration and automatically injects three critical dependency types when a `model` is specified: `provider_choices` for selecting data sources, `standard_params` for common query parameters, and `extra_params` for provider-specific options. It also ensures the return type is properly wrapped in an `OBBject` generic for consistent API responses.

### How are provider dependencies injected into router commands?

Provider dependencies are injected through FastAPI's `Depends()` mechanism, but the OpenBB router command system automates this through the `SignatureInspector`. When a command is registered with a `model` parameter (e.g., `@router.command(model="stock")`), the system looks up the model's requirements in `ProviderInterface` and injects `ProviderChoices`, `StandardParams`, and `ExtraParams` as hidden dependencies. When a request arrives, FastAPI resolves these dependencies by instantiating the appropriate provider classes and parameter validators before calling the endpoint function.

### Can I use the OpenBB router system without the rest of the OpenBB platform?

While the OpenBB router command system is designed as an integral component of the OpenBB Platform, the core routing logic in [`openbb_platform/core/openbb_core/app/router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/router.py) is relatively self-contained and depends primarily on FastAPI. However, to leverage the full automatic dependency injection capabilities (specifically the `ProviderChoices`, `StandardParams`, and `ExtraParams` injections), you would need to implement the `ProviderInterface` and `ExtensionLoader` components that define how models map to providers. For basic routing without provider abstraction, standard FastAPI routers would be more appropriate than extracting the OpenBB system.