Developer Interface

Use TCBV calculations without the workspace UI.

The API follows the same workflow as the browser workspace: build a date rail, select proxies, backtest market sensitivity, estimate NAV, roll history forward, and export reusable state. Each endpoint is stateless. Send the prior step's output into the next step.

Bring Your Own Data Send source rows and optional custom benchmark time series in the request body.

Stateless Workflow Calculation state is carried by response payloads, especially history snapshots.

Report Ready Responses include structured objects and worksheet rows for direct table output.

Workflow

Standard Call Sequence

A normal cycle starts with raw source rows and ends with updated history. To continue a prior valuation cycle, load exported history first and pass it into the workflow.

timeline proxy backtesting estimating history reports

1. Generate the date rail

Use `/api/timeline/run` to produce all daily checkpoints and event labels.

2. Run one actionable date

For the current checkpoint, call proxy, backtesting, estimating, then history.

3. Export continuation state

Use `/api/history/export/run` to save the compact state needed for the next cycle.

Input Data

Source Row Schema

`sourceRows` are the core input. The unique asset identity is the combination of `portfolio`, `type`, `investment`, and `asset`.

Field	Required	Meaning
`portfolio`	Yes	Portfolio name.
`type`	Yes	Investment type or category.
`investment`	Yes	Investment-level grouping.
`asset`	Yes	Asset name inside the investment.
`market`	No	Usually `Private` or `Public`.
`dataType`	Yes	`NAV`, `Contribution`, `Distribution`, `Estimate`, or `Idiosyncratic`.
`effectiveDate`	Yes	Economic date of the event.
`timing`	No	`EOD` by default. `BOD` means the event is effective before that day's market movement.
`knownDate`	Yes	Date the information becomes available in the workflow.
`currency`	No	Defaults to `USD`.
`value`	Yes	NAV, cash flow amount, estimate amount, or idiosyncratic amount.
`notes`	No	Optional supporting text.

`BOD` does not move the timeline event to the prior day. It changes the market-start date used in the calculation: `marketDate = effectiveDate - 1`. `EOD` uses `effectiveDate`.

{
  "portfolio": "Demo Interval Fund",
  "type": "Direct Investment",
  "investment": "Healthcare Direct 1",
  "asset": "Healthcare Direct 1",
  "market": "Private",
  "dataType": "Contribution",
  "effectiveDate": "2023-07-14",
  "timing": "EOD",
  "knownDate": "2023-07-14",
  "currency": "USD",
  "value": 350000
}

Benchmarks

Default and Custom Benchmark Data

The default site benchmark list is available from `/api/benchmarks/list/run`. If you want to use your own benchmark source, include a `benchmarks` array in calculation requests. A custom benchmark with the same `indexName` overrides the default dataset for that request.

{
  "benchmarks": [
    {
      "indexName": "Custom Benchmark A",
      "currency": "USD",
      "timeSeries": [
        { "date": "2023-01-01", "price": 100.00 },
        { "date": "2023-01-02", "price": 100.45 }
      ]
    }
  ]
}

Endpoints

Requests and Outputs

`POST /api/timeline/run`

Builds the complete daily checkpoint rail through the valuation date.

{
  "sourceRows": [],
  "settings": { "valuationDate": "2023-12-31" },
  "history": { "baseCheckpointDate": "" }
}

Returns `timeline.checkpoints` and `timeline.dateRail`.

`POST /api/proxy/run`

Builds checkpoint decision rows for proxy selection.

{
  "sourceRows": [],
  "timeline": { "checkpointDate": "2023-08-14" },
  "history": { "snapshots": [] },
  "selectionByInvestment": {}
}

Returns `proxy.decisionRows`, `proxy.checkpointStats`, and checkpoint metadata.

`POST /api/backtesting/run`

Calculates asset-level and portfolio-level beta evidence and selected beta.

{
  "benchmarks": [],
  "sourceRows": [],
  "timeline": { "checkpointDate": "2023-08-14" },
  "proxy": { "decisionRows": [] },
  "history": { "snapshots": [] },
  "settings": {
    "pValueHurdle": 0.05,
    "defaultSensitivity": 0.5
  }
}

Returns `backtesting.results` and `backtesting.worksheetRows`.

`POST /api/estimating/run`

Builds NAV estimating rows for the current checkpoint using selected beta and benchmark movement.

{
  "benchmarks": [],
  "sourceRows": [],
  "timeline": { "checkpointDate": "2023-08-14" },
  "proxy": { "decisionRows": [] },
  "backtesting": { "results": [] },
  "history": { "snapshots": [] }
}

Returns `estimating.results` and `estimating.worksheetRows`.

`POST /api/history/run`

Locks the current checkpoint and optionally carries daily rows forward to the next event date.

{
  "benchmarks": [],
  "sourceRows": [],
  "timeline": {
    "checkpointDate": "2023-08-14",
    "carryCheckpointDates": ["2023-08-15", "2023-08-16"]
  },
  "proxy": {
    "decisionRows": [],
    "selectionByInvestment": {}
  },
  "backtesting": { "results": [] },
  "estimating": { "results": [] },
  "history": { "snapshots": [] },
  "settings": {
    "pValueHurdle": 0.05,
    "defaultSensitivity": 0.5
  }
}

Returns `history.snapshots`, which should be appended to your local history state.

`POST /api/valuation/run`

Creates the valuation report from history snapshots through the selected valuation date.

{
  "history": {
    "snapshots": [],
    "baseCheckpointDate": ""
  },
  "settings": {
    "valuationDate": "2023-12-31",
    "unitsShares": 1000000,
    "triggerRate": 0.005
  }
}

Returns `valuation.report`, `valuation.worksheetRows`, NAV per share, and governance trigger metrics.

`POST /api/calibration/run`

Extracts calibration observations from history rows where `calFlag` is `Y`.

{
  "history": { "snapshots": [] },
  "settings": { "valuationDate": "2023-12-31" }
}

Returns `calibration.report` and `calibration.worksheetRows`.

Rollforward

How Daily Carry Works

The browser workspace lets the user click `NAV Rollforward` once. Internally, the request sends the current checkpoint plus each non-actionable daily carry date before the next event date. The backend runs proxy, backtesting, estimating, and history snapshot creation for each carry date.

In practice: run backtesting and estimating for the current event date, then call `/api/history/run` with `carryCheckpointDates`. The returned snapshots include the current event date and the daily carry rows.

Export

History Export and Continuation

History is the portable state object. It contains enough checkpoint state and calibration evidence to continue the workflow later without replaying all prior source rows.

{
  "history": {
    "snapshots": []
  }
}

`POST /api/history/export/run` returns `version`, `exportedAt`, and `historySnapshots`. The export keeps calibration rows, rows after the latest NAV date, and the latest state row for each asset.