Models

Create Model

Create an investment model from a prompt or from your own script.

A model backtests allocations to assets, other models, or both. Existing models referenced by ID, name, or symbol become members. The build (script generation plus a sandboxed backtest at the declared defaults) runs in the background and typically takes 10-60 seconds; this answers at once with the model ID and status building. The model's run becomes null when work ends; status and error describe its outcome. With script, generation is skipped: the script is validated against the contract and smoke-run. Metered per build (base plus compute; tokens only when generating). auto_update=false and notify_email=false disable recurring work and allocation emails. Omitting these preserves the existing enabled defaults.

post/v1/models

Request

Base URL: https://api.ensemble.markets (the document declares no server; this is the origin it was published from)
URL: https://api.ensemble.markets/v1/models
Auth: HTTP bearer

Request body

promptstring nullable

Natural language description of the investment model. A model trades assets, other models, or both; reference your existing models by ID, name, or symbol and they become members. Omit when providing script.

scriptstring nullable

Your own implementation instead of a prompt. Validated against the same contract as generated code, smoke-run in the sandbox, and stored verbatim. Billed as a build without generation tokens.

namestring nullable

Model name (defaults to a sequential name like MODEL-0001; editable any time via update)

symbolstring nullable

Model symbol (defaults to a sequential code like MDL-0001; editable any time via update)

is_favoriteboolean

Favorite this model in your private library

auto_updateboolean nullable

Initial automatic refresh preference. Omission preserves the legacy enabled default. Set false for one-time research; enabling can also enable component models.

notify_emailboolean nullable

Initial allocation email preference. Omission preserves the legacy enabled default. Set false unless notifications were requested.

labelsstring[]

Private organizational labels, such as Alpaca or Altruist; case-insensitive

effort'min' | 'mid' | 'max'

How hard the generator works. min (default, all plans): a fast single-shot build. mid (Hobby and Business): a stronger model plus a fidelity review of the script against your description. max (Business): additionally inspects results and refines the implementation. Higher effort bills more per token.

start_datestring date nullable

Where the default view of the history begins (YYYY-MM-DD). The full history is always computed and full_history=true on any history read reveals it; omission lets start_rule choose. The backtest's start date is an execution input, separate from this view window. A date or period named in the prompt is used when this is omitted.

start_rule'two_members' | 'all_members' | 'first_member' nullable

Where the default view begins when no start_date is set. two_members (default): the first day two universe members have data, the earliest a rebalance between them means anything. all_members: the first day every member has data. first_member: the first day any member has data, the full history. Inferred from the prompt when omitted; two_members otherwise.

Example request

{
  "prompt": "Buy and hold SPY",
  "name": "My SPY Strategy",
  "symbol": "SPY-BH",
  "start_date": "2020-01-01"
}

Response

Successful Response

idstring required

Model ID (model_... or legacy m-...)

namestring nullable

May be null if the build failed before naming

symbolstring nullable

May be null if the build failed before naming

building: no results yet; active: results served and refreshed nightly; updating: a rebuild or refresh is running (results keep serving); blocked: updates await a failed or unavailable dependency; paused: results served, nightly refresh off; failed: the build never produced a usable model

warningstring nullable

Something went wrong without changing the status: a failed rebuild, a paused auto-update, or overdue data

depthinteger

0 when the model holds assets only; otherwise one more than its deepest member

as_ofstring date nullable

Last market session covered by the results

auto_updateboolean

Whether the nightly refresh is on

is_publicboolean required

is_favoriteboolean nullable

Owner's favorite state; null for non-owner readers

labelsstring[] nullable

Owner's private organizational labels; null for non-owner readers

urlstring nullable

Tear sheet URL; set once the model has built

created_atstring date-time required

updated_atstring date-time required

descriptionstring nullable

approved_revision_idstring nullable

editing_availableboolean

promptstring required

universestring[] nullable

Symbols the model's code actually trades, as recorded by the runtime: tickers, member model IDs, or both. Null until a run has succeeded.

script_urlstring nullable

Download URL for the standalone Python implementation (runtime harness inlined, served as text/x-python). Null until code exists.

start_datestring date nullable

start_rule'two_members' | 'all_members' | 'first_member'

inputs_schemaobject nullable

JSON Schema for inputs on a run, with defaults: the script's declared inputs followed by the platform's start_date (format date, default null). A run at the defaults computes the full history and goes live; a run with a start_date trades nothing before it and is a snapshot.

live_run_idstring nullable

The default run whose result is the live history

estimate_centsinteger nullable

On the 202 from create and rebuild: what the queued build holds against the balance, in cents. The charge that lands when it finishes replaces this figure. Null on every other read.

build_idstring nullable

The build that produced the current script; on a failed program, the failed build, so getBuild shows what was billed. getBuild returns it.

is_ownerboolean

True when the caller owns this model

Changes

No recorded changes to this operation across all 1 revision of this API.