---
title: "Create Optimizer"
method: POST
path: "/v1/optimizers"
tags: ["Optimizers"]
---

# Create Optimizer

`POST /v1/optimizers`

## 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/optimizers`
- Auth: HTTP bearer

Author one portfolio-weighting class. Pass `prompt` to have the LLM
write it (metered like a build) or `script` with exact Python exposing
`@staticmethod opt(ret_df, syms)`. The class is frozen and injected into
every later backtest that names it. Models identify the stored optimizer
by its class name.

## Request body

- OptimizerCreateRequest: Author one optimizer: exactly one of `prompt` or `script`.
  - `prompt` string, nullable: The weighting rule in words. The LLM writes the class; metered like a build.
  - `script` string, nullable: Exact Python source for one class with `@staticmethod opt(ret_df, syms)`. No LLM.
  - `name` string, nullable: Class name (CapWords). Must match the class in `script`; a hint for `prompt`.
  - `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.

## Response `201`

Successful Response

- Optimizer: One stored optimizer class.
  - `id` string, required: Optimizer ID (optimizer_... or legacy o-...)
  - `name` string, required: Python class name
  - `description` string, required
  - `source` 'prompt' | 'script', required
  - `prompt` string, nullable
  - `script` string, required
  - `hash` string, required
  - `used_by` OptimizerModelRef[]
    - `id` string, required
    - `name` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `4XX`: The request was refused; `error.type` says why
- `5XX`: The server failed; quote `X-Request-Id` when reporting it

---

[API](https://skmtc.dev/ensemble/apis/ensemble-api.md) · [All operations](https://skmtc.dev/ensemble/apis/ensemble-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ensemble/apis/ensemble-api/revisions/4c0fbd80c197?raw)