POST
/api/v1/prompts/optimizeAuto-optimize a prompt
Runs the prompt-optimization engine synchronously against the supplied eval cases + scorers using the chosen strategy and returns the optimized prompt + score deltas. Per-run LLM spend is capped (default $5, override via costCeilingUsd, hard cap $100) — exceeding it returns 402.
Authentication
Send Authorization: Bearer YOUR_API_KEY on every request. Generate API keys at /dashboard/api-keys.
Request body required
Example
{
"projectId": "00000000-0000-0000-0000-000000000000",
"prompt": "<Base prompt to optimize (must not be bla>",
"strategy": "iterative-refinement",
"evalCases": [
{
"input": "string",
"expectedOutput": "string"
}
],
"scorers": [
"string"
],
"targetModel": "<Defaults to gpt-4o.>",
"maxIterations": 1,
"targetScore": 0,
"costCeilingUsd": 0,
"populationSize": 2,
"mutationRate": 0,
"crossoverRate": 0,
"eliteCount": 1,
"maxExamples": 1
}Schema
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 100000,
"description": "Base prompt to optimize (must not be blank)."
},
"strategy": {
"type": "string",
"enum": [
"iterative-refinement",
"genetic",
"few-shot-injection",
"constraint-tightening"
]
},
"evalCases": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"input": {
"type": "string",
"minLength": 1,
"maxLength": 100000
},
"expectedOutput": {
"type": "string",
"maxLength": 100000
}
},
"required": [
"input"
],
"additionalProperties": false
}
},
"scorers": {
"minItems": 1,
"maxItems": 64,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"targetModel": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Defaults to gpt-4o."
},
"maxIterations": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"targetScore": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"costCeilingUsd": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 100
},
"populationSize": {
"type": "integer",
"minimum": 2,
"maximum": 64,
"description": "Genetic strategy."
},
"mutationRate": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Genetic strategy."
},
"crossoverRate": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Genetic strategy."
},
"eliteCount": {
"type": "integer",
"minimum": 1,
"maximum": 32,
"description": "Genetic strategy."
},
"maxExamples": {
"type": "integer",
"minimum": 1,
"maximum": 64,
"description": "Few-shot strategy."
}
},
"required": [
"projectId",
"prompt",
"strategy",
"evalCases",
"scorers"
],
"additionalProperties": false
}
}
}Response
200 example
{
"success": true
}All status codes
200Optimization result ({ optimizedPrompt, originalScore, optimizedScore, improvementPercent, strategy, iterations, changelog, durationMs, targetModel, costUsd }).
400(no description)
401(no description)
402COST_BUDGET_EXCEEDED — per-run LLM spend ceiling reached.
404PROJECT_NOT_FOUND.
429(no description)
Code samples
cURL
curl -X POST \
https://evalguard.ai/api/v1/prompts/optimize \
-H "Authorization: Bearer $EVALGUARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "projectId": "00000000-0000-0000-0000-000000000000", "prompt": "<Base prompt to optimize (must not be bla>", "strategy": "iterative-refinement", "evalCases": [ { "input": "string", "expectedOutput": "string" } ], "scorers": [ "string" ], "targetModel": "<Defaults to gpt-4o.>", "maxIterations": 1, "targetScore": 0, "costCeilingUsd": 0, "populationSize": 2, "mutationRate": 0, "crossoverRate": 0, "eliteCount": 1, "maxExamples": 1 }'TypeScript
import { EvalGuard } from "@evalguard/sdk";
const client = new EvalGuard({ apiKey: process.env.EVALGUARD_API_KEY });
const response = await client.request({
method: "POST",
path: "/api/v1/prompts/optimize",
body: {
"projectId": "00000000-0000-0000-0000-000000000000",
"prompt": "<Base prompt to optimize (must not be bla>",
"strategy": "iterative-refinement",
"evalCases": [
{
"input": "string",
"expectedOutput": "string"
}
],
"scorers": [
"string"
],
"targetModel": "<Defaults to gpt-4o.>",
"maxIterations": 1,
"targetScore": 0,
"costCeilingUsd": 0,
"populationSize": 2,
"mutationRate": 0,
"crossoverRate": 0,
"eliteCount": 1,
"maxExamples": 1
},
});
console.log(response);Python
from evalguard import EvalGuard
import os
client = EvalGuard(api_key=os.environ["EVALGUARD_API_KEY"])
response = client.request(
method="POST",
path="/api/v1/prompts/optimize",
body={
"projectId": "00000000-0000-0000-0000-000000000000",
"prompt": "<Base prompt to optimize (must not be bla>",
"strategy": "iterative-refinement",
"evalCases": [
{
"input": "string",
"expectedOutput": "string"
}
],
"scorers": [
"string"
],
"targetModel": "<Defaults to gpt-4o.>",
"maxIterations": 1,
"targetScore": 0,
"costCeilingUsd": 0,
"populationSize": 2,
"mutationRate": 0,
"crossoverRate": 0,
"eliteCount": 1,
"maxExamples": 1
},
)
print(response)Go
package main
import (
"context"
"fmt"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{"projectId":"00000000-0000-0000-0000-000000000000","prompt":"<Base prompt to optimize (must not be bla>","strategy":"iterative-refinement","evalCases":[{"input":"string","expectedOutput":"string"}],"scorers":["string"],"targetModel":"<Defaults to gpt-4o.>","maxIterations":1,"targetScore":0,"costCeilingUsd":0,"populationSize":2,"mutationRate":0,"crossoverRate":0,"eliteCount":1,"maxExamples":1}`)
req, _ := http.NewRequestWithContext(context.Background(), "POST", "https://evalguard.ai/api/v1/prompts/optimize", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("EVALGUARD_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
fmt.Println(resp.Status)
}Errors
400401402404429