GEPA API Reference

GEPA (Genetic Evolution of Prompt Architectures) is an evolutionary algorithm for optimizing prompts through population-based search.

Endpoint: POST /api/policy-optimization/online/jobs

Authentication: Bearer token via Authorization: Bearer $SYNTH_API_KEY

Request

{
  "policy_optimization": {
    "algorithm": "gepa",
    "task_app_url": "https://your-task-app.example.com",
    "policy": {
      "model": "gpt-4o-mini",
      "provider": "openai",
      "temperature": 0.0,
      "max_completion_tokens": 256
    },
    "gepa": {
      "population": {
        "num_generations": 5,
        "children_per_generation": 4
      },
      "rollout": {
        "budget": 200
      }
    }
  }
}

GEPA-Specific Parameters

Parameter	Type	Description
gepa.population.num_generations	int	Number of evolutionary generations
gepa.population.children_per_generation	int	Candidates generated per generation
gepa.rollout.budget	int	Total rollout budget for optimization

Response

{
  "job_id": "pl_abc123",
  "status": "running"
}

Polling for Completion

Use GET /api/policy-optimization/online/jobs/{job_id} to check status:

{
  "job_id": "pl_abc123",
  "status": "succeeded",
  "best_score": 0.875
}

Notes

• GEPA requires the backend to call your task app, so:
  • Task app must be publicly accessible (via tunnel for local development)
  • ENVIRONMENT_API_KEY must be registered with the backend
• See the GEPA walkthrough for a complete example