Trading Strategies API — CRUD and Promotion Workflow

Strategies are the top-level research artifacts in the Hedge Fund Backend. Each strategy encapsulates a universe of ticker symbols, a target timeframe, references to one or more features and an ML model, and an optional signal logic definition. Strategies progress through a well-defined lifecycle — draft → backtested → validated → promoted → archived — and can only be promoted to the Portfolio Construction Layer once they carry a validated status and at least one completed backtest. The endpoints below cover full CRUD management as well as the promotion workflow that publishes a StrategyValidated event to the internal event bus.

CRUD Endpoints

Create Strategy

curl -X POST https://api.example.com/api/v1/strategies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Momentum Alpha v1",
    "description": "Dual-momentum strategy on large-cap US equities",
    "universe": ["AAPL", "MSFT", "NVDA", "GOOGL"],
    "timeframe": "1d",
    "feature_ids": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ],
    "model_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "signal_logic_id": null,
    "pipeline_config": {}
  }'

POST /api/v1/strategies Creates a new strategy in draft status. All fields from StrategyBase are accepted. The name field is required; all others are optional and default to safe empty values.

Request Body

name

string

required

Human-readable strategy name. Maximum 255 characters. Stored with a database index for fast lookup.

description

string

Free-text description of the strategy’s hypothesis and methodology.

universe

string[]

default:"[]"

List of ticker symbols this strategy trades. For example ["AAPL", "MSFT", "NVDA"].

timeframe

string

default:"1d"

Candle resolution. Common values: 1m, 5m, 15m, 1h, 4h, 1d, 1w.

feature_ids

uuid[]

default:"[]"

Array of Feature UUIDs whose computed columns will be fed into the model at inference time.

model_id

uuid

UUID of the MLModel that generates predictions for this strategy. May be attached later.

signal_logic_id

uuid

UUID of the SignalLogic row that converts model predictions into BUY/SELL/HOLD decisions.

pipeline_config

object

default:"{}"

Arbitrary JSONB configuration forwarded to the feature and signal pipelines at runtime.

Response — `201 Created`

uuid

Unique identifier of the newly created strategy.

name

string

Strategy name as provided.

description

string | null

Optional description.

universe

string[]

Ticker universe.

timeframe

string

Candle resolution.

feature_ids

uuid[]

Linked feature IDs.

model_id

uuid | null

Linked ML model ID.

signal_logic_id

uuid | null

Linked signal logic ID.

pipeline_config

object

Pipeline configuration blob.

status

string

Lifecycle status. Always "draft" on creation.

version

integer

Optimistic-concurrency version counter. Starts at 1.

created_at

datetime

ISO 8601 timestamp of creation.

updated_at

datetime

ISO 8601 timestamp of the last update.

Show Example response

{
  "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "name": "Momentum Alpha v1",
  "description": "Dual-momentum strategy on large-cap US equities",
  "universe": ["AAPL", "MSFT", "NVDA", "GOOGL"],
  "timeframe": "1d",
  "feature_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ],
  "model_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "signal_logic_id": null,
  "pipeline_config": {},
  "status": "draft",
  "version": 1,
  "created_at": "2024-11-01T09:00:00Z",
  "updated_at": "2024-11-01T09:00:00Z"
}

List Strategies

GET /api/v1/strategies Returns a paginated array of all strategies ordered by creation time. Use skip and limit for cursor-style pagination.

curl "https://api.example.com/api/v1/strategies?skip=0&limit=25"

Query Parameters

skip

integer

default:"0"

Number of records to skip. Used for offset-based pagination.

limit

integer

default:"100"

Maximum number of strategies to return in a single response.

Response — `200 OK`

Returns list[StrategyRead]. Each element has the same shape as the Create Strategy response above.

Get Strategy

GET /api/v1/strategies/{strategy_id} Retrieves a single strategy by its UUID.

curl https://api.example.com/api/v1/strategies/d4e5f6a7-b8c9-0123-def0-234567890123

Path Parameters

strategy_id

uuid

required

UUID of the strategy to retrieve.

Response

Returns StrategyRead on 200 OK. Returns 404 Not Found with {"detail": "Strategy not found"} if no strategy exists for the given ID.

Update Strategy

PATCH /api/v1/strategies/{strategy_id} Partially updates a strategy. Only the fields included in the request body are modified; omitted fields are left unchanged. This is especially useful for transitioning status between lifecycle stages or attaching a model after initial creation.

curl -X PATCH https://api.example.com/api/v1/strategies/d4e5f6a7-b8c9-0123-def0-234567890123 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "validated",
    "model_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }'

Path Parameters

strategy_id

uuid

required

UUID of the strategy to update.

Request Body (`StrategyUpdate` — all fields optional)

name

string

New name. Maximum 255 characters.

description

string | null

Updated description.

universe

string[]

Replacement ticker universe.

timeframe

string

New candle resolution.

feature_ids

uuid[]

Full replacement list of feature IDs.

model_id

uuid | null

Attach or detach the linked ML model.

signal_logic_id

uuid | null

Attach or detach signal logic.

pipeline_config

object

Replacement pipeline config blob.

status

string

Manually set the lifecycle status. Accepted values: draft, backtested, validated, promoted, archived.

Promotion and demotion status changes should normally go through the dedicated /promote and /demote endpoints, which also handle event publishing and prerequisite validation.

Response — `200 OK`

Returns the updated StrategyRead object. Returns 404 Not Found if the strategy does not exist.

Delete Strategy

DELETE /api/v1/strategies/{strategy_id} Permanently deletes a strategy and its database row.

curl -X DELETE https://api.example.com/api/v1/strategies/d4e5f6a7-b8c9-0123-def0-234567890123

Path Parameters

strategy_id

uuid

required

UUID of the strategy to delete.

Response

204 No Content on success. 404 Not Found if the strategy does not exist.

Deletion is permanent. Associated backtests and experiments retain their strategy_id foreign key but the strategy row itself cannot be recovered. Archive strategies instead of deleting them when audit trails matter.

Promotion Endpoints

The promotion workflow controls the transition of a strategy from the research environment into the live Portfolio Construction Layer. Promotion publishes a StrategyValidated event to the internal event bus. The /status endpoint lets you inspect promotion readiness before attempting a promotion.

Promote Strategy

POST /api/v1/strategies/{strategy_id}/promote Promotes a validated strategy to the Portfolio Construction Layer. The service checks that the strategy has validated status and at least one completed backtest before publishing the event. Returns 409 Conflict if any promotion requirement is unmet.

curl -X POST https://api.example.com/api/v1/strategies/d4e5f6a7-b8c9-0123-def0-234567890123/promote \
  -H "Content-Type: application/json" \
  -d '{"confidence_override": 0.85}'

Path Parameters

strategy_id

uuid

required

UUID of the strategy to promote.

Request Body

confidence_override

float | null

default:"null"

Optional override for the model confidence threshold forwarded in the promotion event payload. When null, the model’s stored confidence value is used.

Response — `200 OK`

success

boolean

true when the strategy was successfully promoted and the event was published.

message

string

Human-readable outcome message from the promotion service.

payload_sent

object

The exact StrategyValidated event payload that was dispatched to the event bus.

Show Example response

{
  "success": true,
  "message": "Strategy promoted to portfolio layer",
  "payload_sent": {
    "strategy_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
    "name": "Momentum Alpha v1",
    "confidence": 0.85,
    "universe": ["AAPL", "MSFT", "NVDA", "GOOGL"],
    "timeframe": "1d",
    "promoted_at": "2024-11-15T14:30:00Z"
  }
}

Show Example 409 response — requirements not met

{
  "detail": "Strategy must have validated status and at least one completed backtest before promotion"
}

Demote Strategy

POST /api/v1/strategies/{strategy_id}/demote Rolls back a promoted strategy to validated status. Use this to pull a strategy from the portfolio layer without archiving it, preserving all backtests and history.

curl -X POST https://api.example.com/api/v1/strategies/d4e5f6a7-b8c9-0123-def0-234567890123/demote \
  -H "Content-Type: application/json" \
  -d '{"reason": "Underperforming against benchmark — pulling for re-tuning"}'

Path Parameters

strategy_id

uuid

required

UUID of the strategy to demote.

Request Body

reason

string

default:"\"\""

Free-text explanation for the demotion. Recorded in the audit log for compliance purposes.

Response — `200 OK`

Returns the updated strategy state from the promotion service after the rollback completes.

Get Strategy Status

GET /api/v1/strategies/{strategy_id}/status Returns the current lifecycle status of a strategy alongside a promotion readiness checklist. Call this endpoint before attempting a promotion to confirm all requirements are satisfied without risking a 409 error.

curl https://api.example.com/api/v1/strategies/d4e5f6a7-b8c9-0123-def0-234567890123/status

Path Parameters

strategy_id

uuid

required

UUID of the strategy to inspect.

Response — `200 OK`

strategy_id

string

UUID of the strategy (serialized as string).

name

string

Human-readable strategy name.

status

string

Current lifecycle status. One of: draft, backtested, validated, promoted, archived.

promotion_ready

boolean

true when both has_validated_status and has_completed_backtest are true. This is the single gate check before calling /promote.

checklist

object

Detailed breakdown of each promotion prerequisite.

Show Checklist fields

checklist.has_validated_status

boolean

true when the strategy’s status is exactly validated.

checklist.has_completed_backtest

boolean

true when at least one backtest row linked to this strategy has status = COMPLETED.

checklist.is_promoted

boolean

true when the strategy is currently in the promoted state. Informational — not a gate.

n_backtests

integer

Count of completed backtests linked to this strategy.

Show Example response — ready to promote

{
  "strategy_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "name": "Momentum Alpha v1",
  "status": "validated",
  "promotion_ready": true,
  "checklist": {
    "has_validated_status": true,
    "has_completed_backtest": true,
    "is_promoted": false
  },
  "n_backtests": 3
}

Show Example response — not ready (still draft)

{
  "strategy_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "name": "Momentum Alpha v1",
  "status": "draft",
  "promotion_ready": false,
  "checklist": {
    "has_validated_status": false,
    "has_completed_backtest": false,
    "is_promoted": false
  },
  "n_backtests": 0
}

Use the checklist fields to drive UI indicators in the strategy dashboard — each boolean maps directly to a step in the research pipeline that must be completed before promotion.

Strategy Lifecycle Reference

The status field follows a linear progression, though manual overrides via PATCH are permitted for administrative purposes.

Status	Description
`draft`	Initial state. Strategy is being configured; no backtests have been run.
`backtested`	At least one backtest has been executed against this strategy.
`validated`	Research team has reviewed backtest results and approved the strategy for promotion consideration.
`promoted`	Strategy has been published to the Portfolio Construction Layer and is active.
`archived`	Strategy has been retired and removed from active consideration.

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Trading Strategies API — CRUD and Promotion Workflow

CRUD Endpoints

Create Strategy

Request Body

Response — `201 Created`

List Strategies

Query Parameters

Response — `200 OK`

Get Strategy

Path Parameters

Response

Update Strategy

Path Parameters

Request Body (`StrategyUpdate` — all fields optional)

Response — `200 OK`

Delete Strategy

Path Parameters

Response

Promotion Endpoints

Promote Strategy

Path Parameters

Request Body

Response — `200 OK`

Demote Strategy

Path Parameters

Request Body

Response — `200 OK`

Get Strategy Status

Path Parameters

Response — `200 OK`

Strategy Lifecycle Reference

Build docs developers (and LLMs) love

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Documentation Index

​CRUD Endpoints

​Create Strategy

​Request Body

​Response — 201 Created

​List Strategies

​Query Parameters

​Response — 200 OK

​Get Strategy

​Path Parameters

​Response

​Update Strategy

​Path Parameters

​Request Body (StrategyUpdate — all fields optional)

​Response — 200 OK

​Delete Strategy

​Path Parameters

​Response

​Promotion Endpoints

​Promote Strategy

​Path Parameters

​Request Body

​Response — 200 OK

​Demote Strategy

​Path Parameters

​Request Body

​Response — 200 OK

​Get Strategy Status

​Path Parameters

​Response — 200 OK

​Strategy Lifecycle Reference

Build docs developers (and LLMs) love

CRUD Endpoints

Create Strategy

Request Body

Response — `201 Created`

List Strategies

Query Parameters

Response — `200 OK`

Get Strategy

Path Parameters

Response

Update Strategy

Path Parameters

Request Body (`StrategyUpdate` — all fields optional)

Response — `200 OK`

Delete Strategy

Path Parameters

Response

Promotion Endpoints

Promote Strategy

Path Parameters

Request Body

Response — `200 OK`

Demote Strategy

Path Parameters

Request Body

Response — `200 OK`

Get Strategy Status

Path Parameters

Response — `200 OK`

Strategy Lifecycle Reference