v1

latestOpenAPI 3.1.02026-07-175793186.0 KB

optimization

Run Optimization

Trigger a blocking GEPA prompt optimization run.

post/api/v1/optimization/run

Request body

dataset_pathstring nullable

Relative filesystem path to the dataset file.

dataset_idstring nullable

Registered dataset identifier to optimize against.

program_specstring

DSPy program specification string to optimize in module:attr form. Required when module_slug is not provided.

module_slugstring nullable

Registered module slug for server-side dispatch. When provided, program_spec is auto-resolved from the module registry.

skill_namestring nullable

Bundled or mounted Fleet skill name to optimize as a markdown skill artifact.

skill_pathstring nullable

Relative path to a SKILL.md-compatible markdown file to optimize.

trace_bundle_pathsstring[]

Optional offline trace bundle paths available to the RLM-GEPA instruction proposer.

reflection_profile_idstring nullable

Optional LLM provider profile id for the GEPA proposer/reflection model.

reflection_model_idstring nullable

Optional provider-native model id for the GEPA proposer/reflection model.

output_pathstring nullable

Optional filesystem path to save the optimized program.

auto'light' | 'medium' | 'heavy'

Optimization intensity level.

max_metric_callsinteger nullable

Optional GEPA metric-call budget override for short offline smoke runs.

train_rationumber

Fraction of examples to use for training (remainder used for validation).

optimizer'gepa'

Optimizer backend to use. GEPA is the only supported optimizer.

Response

Successful Response

okboolean

Whether the optimization run completed successfully.

optimizerstring

Optimizer backend that was used.

program_specstring required

DSPy program specification that was optimized.

train_examplesinteger required

Number of training examples used.

validation_examplesinteger required

Number of validation examples used.

validation_scorenumber nullable

Validation score from the optimized program, when available.

output_pathstring nullable

Filesystem path where the optimized program was saved.

manifest_pathstring nullable

Filesystem path to the optimization manifest, when available.

feedback_summarystring nullable

Short summary of validation feedback from the GEPA run.

module_slugstring nullable

Module slug used for this optimization run, when server-side dispatch was used.

reflection_profile_idstring nullable

LLM provider profile id used for GEPA reflection/proposal, when selected.

reflection_model_idstring nullable

Model id used for GEPA reflection/proposal, when selected.

distilled_trace_bundle_pathstring nullable

Distilled trace bundle used by the RLM-GEPA proposer.

errorstring nullable

Error message when the optimization run failed.