---
title: "Adapt prompts across LLMs"
method: POST
path: "/v2/prompt/optimize"
tags: ["Prompt Optimization"]
---

# Adapt prompts across LLMs

`POST /v2/prompt/optimize`

Optimize your prompt from one LLM to work optimally across different target LLMs.

This endpoint automatically optimizes your prompt (system prompt + user message template) to improve accuracy on your use case across various models. Each model has unique characteristics, and what works well for GPT-5 might not work as well for Claude or Gemini.

**How Prompt Optimization Works:**
1. You provide your current prompt and optionally your current origin model
2. You specify the target models you want to optimize your prompt to
3. You provide evaluation examples (golden records) with expected answers
4. The system runs optimization to find the best prompt for each target model
5. You receive optimized prompts that perform well on your target models

**Evaluation Metrics:**
Choose either a standard metric or provide custom evaluation:
- **Standard metrics**: LLMaaJ:Sem_Sim_1 (semantic similarity), JSON_Match
- **Custom evaluation**: Provide evaluation_config with your own LLM judge, prompt, and cutoff

**Dataset Requirements:**
- Minimum 25 examples in train_goldens (more examples = better optimization)
- **Prototype mode**: Set `prototype_mode: true` to use as few as 3 examples for prototyping
  - Recommended when you don't have enough data yet to build a proof-of-concept
  - Note: Performance may be degraded compared to standard mode (25+ examples)
  - Trade-off: Faster iteration with less data vs. potentially less generalizability
- Each example must have fields matching your template placeholders
- Supervised evaluation requires 'answer' field in each golden record
- Unsupervised evaluation can work without answers

**Training Time:**
- Processing is asynchronous and typically takes 10-30 minutes
- Time depends on: number of target models, dataset size, model availability
- Use the returned optimization_run_id to check status and retrieve results

**Example Workflow:**
```
1. POST /v2/prompt/optimize - Submit optimization request
2. GET /v2/prompt/optimizeStatus/{id} - Poll status until completed
3. GET /v2/prompt/optimizeResults/{id} - Retrieve optimized prompts
4. Use optimized prompts in production with target models
```

## Request body

- PromptAdaptationRequest — Request model for POST /v2/prompt/optimize endpoint. Submits a prompt adaptation job to optimize your prompt for different target LLMs. The system evaluates your original prompt on the origin model, then automatically generates and tests optimized prompts for each target model to maximize performance. **Key concepts:** - **system_prompt + template**: Your current prompt configuration - **origin_model**: The model your prompt currently works well with (baseline) - **target_models**: The models you want to optimize for - **train_goldens**: Evaluation examples used to optimize the prompts - **test_goldens**: Held-out examples used to measure final performance **Workflow:** 1. Submit this request to start adaptation 2. System evaluates baseline performance on origin model 3. Optimizes prompts for each target model 4. Returns adaptation_run_id for tracking progress 5. Poll /adaptStatus until complete 6. Retrieve optimized prompts from /adaptResults **Requirements:** - Minimum 25 examples in train_goldens (or 3 examples with prototype_mode=True) - test_goldens required when using train_goldens - Either use (goldens) or (train_goldens + test_goldens), not both - For supervised metrics, all examples must include 'answer' field **Prototype Mode:** - Set prototype_mode=True to allow as few as 3 training examples - Useful for prototyping AI applications when you don't have enough data yet - Note: Performance may be degraded compared to standard mode (25+ examples)
  - `evaluation_metric` string, nullable
  - `evaluation_config` string, nullable
  - `system_prompt` string, required — System prompt to use with the origin model. This sets the context and role for the LLM
  - `template` string, required — User message template with placeholders for fields. Use curly braces for field substitution
  - `fields` string[], required — List of field names that will be substituted into the template. Must match keys in golden records
  - `goldens` GoldenRecord[], nullable — Training examples (legacy parameter). Use train_goldens and test_goldens for better control. Minimum 25 examples (or 3 with prototype_mode=true)
    - `fields` object, required — Dictionary mapping field names to their values. Keys must match the fields specified in the template
    - `answer` string, nullable — Expected answer for supervised evaluation. Required for supervised metrics, optional for unsupervised
  - `train_goldens` GoldenRecord[], nullable — Training examples for prompt optimization. Minimum 25 examples required (or 3 with prototype_mode=true). Cannot be used with 'goldens' parameter
    - `fields` object, required — Dictionary mapping field names to their values. Keys must match the fields specified in the template
    - `answer` string, nullable — Expected answer for supervised evaluation. Required for supervised metrics, optional for unsupervised
  - `test_goldens` GoldenRecord[], nullable — Test examples for evaluation. Required if train_goldens is provided. Used to measure final performance on held-out data
    - `fields` object, required — Dictionary mapping field names to their values. Keys must match the fields specified in the template
    - `answer` string, nullable — Expected answer for supervised evaluation. Required for supervised metrics, optional for unsupervised
  - `origin_model` RequestProvider — Model for specifying an LLM provider in API requests.
    - `is_custom` boolean — Whether this is a custom model not in Not Diamond's supported model list
    - `context_length` integer, nullable — Maximum context length for the model (required for custom models)
    - `input_price` number, nullable — Input token price per million tokens in USD (required for custom models)
    - `output_price` number, nullable — Output token price per million tokens in USD (required for custom models)
    - `latency` number, nullable — Average latency in seconds (required for custom models)
    - `provider` string, required — Provider name (e.g., 'openai', 'anthropic', 'google')
    - `model` string, required — Model name (e.g., 'gpt-4o', 'claude-sonnet-4-5-20250929')
  - `target_models` RequestProvider[], required — List of models to optimize the prompt for. Maximum count depends on your subscription tier (Free: 1, Starter: 3, Startup: 5, Enterprise: 10)
    - `is_custom` boolean — Whether this is a custom model not in Not Diamond's supported model list
    - `context_length` integer, nullable — Maximum context length for the model (required for custom models)
    - `input_price` number, nullable — Input token price per million tokens in USD (required for custom models)
    - `output_price` number, nullable — Output token price per million tokens in USD (required for custom models)
    - `latency` number, nullable — Average latency in seconds (required for custom models)
    - `provider` string, required — Provider name (e.g., 'openai', 'anthropic', 'google')
    - `model` string, required — Model name (e.g., 'gpt-4o', 'claude-sonnet-4-5-20250929')
  - `origin_model_evaluation_score` number, nullable — Optional baseline score for the origin model. If provided, can skip origin model evaluation
  - `prototype_mode` boolean — Enable prototype mode to use as few as 3 training examples (instead of 25). Note: Performance may be degraded with fewer examples. Recommended for prototyping AI applications when you don't have enough data yet

## Response `200`

Successfully started prompt optimization

- PromptAdaptationResponse — Response model for POST /v2/prompt/optimize endpoint. Returned immediately after submitting a prompt optimization request. The optimization process runs asynchronously, so use the returned optimization_run_id to track progress and retrieve results when complete. **Next steps:** 1. Store the optimization_run_id 2. Poll GET /v2/prompt/optimizeStatus/{optimization_run_id} to check progress 3. When status is 'completed', retrieve optimized prompts from GET /v2/prompt/optimizeResults/{optimization_run_id} 4. Use the optimized prompts with your target models
  - `optimization_run_id` string, required — Unique identifier for this optimization run. Use this to poll status and retrieve optimized prompts when complete

## Other responses

- `400` — Invalid request (e.g., insufficient examples, invalid models, missing required fields)
- `401` — Authentication failed or no prompt optimization access
- `404` — Not found
- `422` — Validation error (e.g., must provide either goldens or train_goldens/test_goldens)
- `429` — Concurrent run limit exceeded

---

[API](https://skmtc.net/not-diamond/apis/not-diamond-api.md) · [All operations](https://skmtc.net/not-diamond/apis/not-diamond-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/not-diamond/not-diamond-api/versions/ea8fcb544470/schema)