Features API — CRUD, Generation, and Feature Store

The Features API manages two distinct concepts: feature definitions (the plugin configuration stored in the database) and feature datasets (the computed parquet files stored in S3/MinIO). This separation allows the same definition to be computed over different symbols, timeframes, and date ranges while maintaining full version history via SHA-256 content hashing. A Feature row captures a plugin key, its hyperparameters, a human-readable name and type, and an optional storage URI prefix. A FeatureDataset row represents one generated instance of that definition — bound to a specific symbol, timeframe, and date range — and is addressed by a version_hash derived from all its inputs, including the source data fingerprint.

Feature CRUD

Create a Feature Definition

POST

string

/api/v1/features

Creates a new feature definition record. The definition is not computed at this point — use the generation endpoints to produce a dataset.

Request Body

name

string

required

Human-readable name for this feature, e.g. "14-period RSI". Maximum 255 characters.

plugin_key

string

required

Plugin identifier resolved through the feature plugin registry, e.g. "technical.rsi" or "statistical.autocorr". Use GET /api/v1/features/plugins/available to enumerate registered keys.

type

string

required

Feature category. One of: "technical", "statistical", "automated", "news", "fundamental", "macro".

parameters

object

Plugin-specific hyperparameters passed to the feature plugin constructor, e.g. {"period": 14}. Defaults to {}.

description

string

Optional free-text description of this feature definition.

Response — `FeatureRead`

string (UUID)

Unique identifier assigned at creation.

name

string

The feature name.

plugin_key

string

The resolved plugin key.

type

string

Feature category.

parameters

object

Hyperparameters stored with the definition.

description

string | null

Human-readable description.

version

integer

Optimistic-lock version counter, incremented on every update.

storage_uri

string | null

S3/MinIO key prefix under which generated datasets for this definition are stored. Populated after first generation.

created_at

string (datetime)

ISO 8601 creation timestamp.

updated_at

string (datetime)

ISO 8601 last-updated timestamp.

curl -X POST http://localhost:8000/api/v1/features \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "14-period RSI",
    "plugin_key": "technical.rsi",
    "type": "technical",
    "parameters": {"period": 14},
    "description": "Relative Strength Index with a 14-bar lookback"
  }'

List Feature Definitions

GET

string

/api/v1/features

Returns a paginated list of all feature definitions.

Query Parameters

skip

integer

Number of records to skip. Default 0.

limit

integer

Maximum records to return. Default 100.

Response: Array of FeatureRead objects.

curl "http://localhost:8000/api/v1/features?skip=0&limit=25"

Get a Feature Definition

GET

string

/api/v1/features/{feature_id}

Fetches a single feature definition by its UUID.

feature_id

string (UUID)

required

UUID of the feature definition to retrieve.

Response: FeatureRead object. Errors: 404 Feature not found if the ID does not exist.

curl http://localhost:8000/api/v1/features/550e8400-e29b-41d4-a716-446655440000

Update a Feature Definition

PATCH

string

/api/v1/features/{feature_id}

Partially updates a feature definition. Only supplied fields are changed; omitted fields retain their current values.

Request Body (all fields optional)

name

string

Updated name.

plugin_key

string

Updated plugin key.

type

string

Updated feature category.

parameters

object

Replacement hyperparameter dict. Replaces the entire parameters object (not merged).

description

string

Updated description.

storage_uri

string

Override the S3 prefix for this definition’s datasets.

Response: Updated FeatureRead object. Errors: 404 Feature not found.

curl -X PATCH http://localhost:8000/api/v1/features/550e8400-e29b-41d4-a716-446655440000 \
  -H 'Content-Type: application/json' \
  -d '{"description": "Updated: 14-bar RSI on close price"}'

Delete a Feature Definition

DELETE

string

/api/v1/features/{feature_id}

Permanently removes a feature definition from the database.

Deleting a feature definition does not remove the generated FeatureDataset rows or the underlying S3 objects. Clean up orphaned datasets separately if storage reclamation is required.

Response: 204 No Content Errors: 404 Feature not found.

curl -X DELETE http://localhost:8000/api/v1/features/550e8400-e29b-41d4-a716-446655440000

Feature Generation

Generate (or Reuse) a Feature Dataset

POST

string

/api/v1/features/{feature_id}/generate

Computes a feature dataset for the requested symbol, timeframe, and date range — or returns the cached version if one already exists for the exact same inputs. The Feature Engine derives a SHA-256 version_hash from the tuple (plugin_key, parameters, symbol, timeframe, start_date, end_date, source_fingerprint). If a FeatureDataset row with that hash already exists in the store, it is returned immediately without any recomputation, making repeated calls safe and cheap.

Path Parameter

feature_id

string (UUID)

required

UUID of the feature definition to compute.

Request Body

symbol

string

required

Ticker symbol to compute the feature for, e.g. "AAPL" or "BTC-USD".

timeframe

string

required

OHLCV bar size. Supported values: "1d", "1h", "1w". Default "1d".

start_date

string

required

ISO 8601 start of the date range, e.g. "2023-01-01T00:00:00".

end_date

string

required

ISO 8601 end of the date range (exclusive), e.g. "2024-01-01T00:00:00".

Response — `FeatureGenerateResponse`

dataset

FeatureDatasetRead

Show FeatureDatasetRead fields

string (UUID)

Unique dataset identifier.

feature_id

string (UUID)

The definition this dataset was computed from.

symbol

string

Ticker symbol.

timeframe

string

Bar size used during computation.

start_date

string (datetime)

Requested start of the date range.

end_date

string (datetime)

Requested end of the date range.

version_hash

string

SHA-256 content hash of all inputs including source data fingerprint. Identical inputs always produce the same hash.

storage_uri

string

S3/MinIO URI where the computed parquet file is stored.

row_count

integer | null

Number of rows in the generated dataset. Null if the plugin did not report row count.

columns

array of strings

Column names present in the generated dataset.

created_at

string (datetime)

When this dataset version was first computed.

preview

array of objects

First 10 rows of the generated feature data as a list of row dicts, useful for quick visual inspection in the UI.

Errors:

404 Feature not found — the feature_id does not exist in the database.
422 Unprocessable Entity — the Market Data Layer returned an empty OHLCV frame for the requested symbol and date range.

curl -X POST http://localhost:8000/api/v1/features/550e8400-e29b-41d4-a716-446655440000/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "symbol": "AAPL",
    "timeframe": "1d",
    "start_date": "2023-01-01T00:00:00",
    "end_date": "2024-01-01T00:00:00"
  }'

Force Recompute a Feature Dataset

POST

string

/api/v1/features/{feature_id}/regenerate

Always calls the feature plugin against the current state of the Market Data Layer. If the freshly fetched OHLCV data has a different fingerprint than the last stored version, a new FeatureDataset row is created, preserving full lineage history. If the data has not changed the existing dataset version is resolved and returned.

regenerate always invokes the plugin even if a cached version exists. Use this when you suspect the Market Data Layer has updated or revised historical bars (e.g. after a corporate action adjustment or data-vendor restatement) and want to ensure your stored features reflect the latest source data.

Request/Response: Identical to generate — same body fields, same FeatureGenerateResponse shape. Errors: 404 if feature not found; 422 if the Market Data Layer returns empty OHLCV.

curl -X POST http://localhost:8000/api/v1/features/550e8400-e29b-41d4-a716-446655440000/regenerate \
  -H 'Content-Type: application/json' \
  -d '{
    "symbol": "AAPL",
    "timeframe": "1d",
    "start_date": "2023-01-01T00:00:00",
    "end_date": "2024-01-01T00:00:00"
  }'

List Historical Dataset Versions

GET

string

/api/v1/features/{feature_id}/versions

Returns all previously computed FeatureDataset records for a feature definition, filtered to a specific symbol and timeframe, ordered by created_at ascending.

Query Parameters

symbol

string

required

Ticker symbol to filter versions by, e.g. "AAPL".

timeframe

string

Bar size to filter by. Default "1d".

Response: Array of FeatureDatasetRead objects ordered by created_at. Errors: 404 Feature not found.

Use this endpoint to audit the full computation lineage for a symbol. Each entry’s version_hash traces back to the exact plugin parameters and source data fingerprint that produced it — essential for reproducing historical backtest results.

curl "http://localhost:8000/api/v1/features/550e8400-e29b-41d4-a716-446655440000/versions?symbol=AAPL&timeframe=1d"

Plugin Discovery

List Available Feature Plugins

GET

string

/api/v1/features/plugins/available

Returns the list of all plugin keys currently registered in the Feature Plugin Registry. These keys can be used as plugin_key when creating feature definitions. Response:

{
  "plugins": [
    "technical.rsi",
    "technical.atr",
    "technical.macd",
    "statistical.autocorr",
    "news.sentiment",
    "fundamental.pe_ratio"
  ]
}

The returned keys are driven by the server-side plugin registry. If you have deployed custom plugins, they will appear here automatically without any frontend changes.

curl http://localhost:8000/api/v1/features/plugins/available

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Features API — CRUD, Generation, and Feature Store

Feature CRUD

Create a Feature Definition

Request Body

Response — `FeatureRead`

List Feature Definitions

Query Parameters

Get a Feature Definition

Update a Feature Definition

Request Body (all fields optional)

Delete a Feature Definition

Feature Generation

Generate (or Reuse) a Feature Dataset

Path Parameter

Request Body

Response — `FeatureGenerateResponse`

Force Recompute a Feature Dataset

List Historical Dataset Versions

Query Parameters

Plugin Discovery

List Available Feature Plugins

Build docs developers (and LLMs) love

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Documentation Index

​Feature CRUD

​Create a Feature Definition

​Request Body

​Response — FeatureRead

​List Feature Definitions

​Query Parameters

​Get a Feature Definition

​Update a Feature Definition

​Request Body (all fields optional)

​Delete a Feature Definition

​Feature Generation

​Generate (or Reuse) a Feature Dataset

​Path Parameter

​Request Body

​Response — FeatureGenerateResponse

​Force Recompute a Feature Dataset

​List Historical Dataset Versions

​Query Parameters

​Plugin Discovery

​List Available Feature Plugins

Build docs developers (and LLMs) love

Feature CRUD

Create a Feature Definition

Request Body

Response — `FeatureRead`

List Feature Definitions

Query Parameters

Get a Feature Definition

Update a Feature Definition

Request Body (all fields optional)

Delete a Feature Definition

Feature Generation

Generate (or Reuse) a Feature Dataset

Path Parameter

Request Body

Response — `FeatureGenerateResponse`

Force Recompute a Feature Dataset

List Historical Dataset Versions

Query Parameters

Plugin Discovery

List Available Feature Plugins