Skip to main content
POST
/
api
/
prompt-learning
/
online
/
gepa
/
sessions
GEPA Online API
curl --request POST \
  --url https://api.example.com/api/prompt-learning/online/gepa/sessions
Online GEPA is an interactive optimization mode where you:
  1. create a session on the backend
  2. call a proxy URL for each LLM inference (the proxy applies the currently-selected candidate prompt)
  3. compute a reward locally
  4. report that reward back to the session

​
Sessions

​
Create Session

POST /api/prompt-learning/online/gepa/sessions Request body (example): 
{
  "config_body": {
    "prompt_learning": {
      "algorithm": "gepa",
      "gepa": {
        "mode": "online",
        "online_proposer_min_rollouts": 10
      },
      "initial_prompt": {
        "messages": [
          { "role": "system", "pattern": "You are a classifier..." }
        ]
      }
    }
  }
}
Response body (example): 
{
  "session_id": "50b3f96d-916e-4780-a86c-37d6456e90fc",
  "job_id": "pl_1234567890abcdef",
  "status": "started",
  "mode": "online",
  "proxy_url": "http://localhost:8080/api/gepa/v1/50b3f96d-916e-4780-a86c-37d6456e90fc",
  "chat_completions_url": "http://localhost:8080/api/gepa/v1/50b3f96d-916e-4780-a86c-37d6456e90fc/chat/completions"
}

​
Get Session

GET /api/prompt-learning/online/gepa/sessions/{session_id} Returns live state including candidate summaries and the current best candidate: 
{
  "session_id": "50b3f96d-916e-4780-a86c-37d6456e90fc",
  "status": "started",
  "rollout_count": 40,
  "reward_count": 40,
  "best_candidate_id": "cand_...",
  "best_score": 0.789,
  "candidates": [
    { "candidate_id": "baseline", "avg_reward": 0.42, "rollout_count": 21, "is_baseline": true }
  ]
}

​
Pause / Resume / Cancel

  • POST /api/prompt-learning/online/gepa/sessions/{session_id}/pause
  • POST /api/prompt-learning/online/gepa/sessions/{session_id}/resume
  • POST /api/prompt-learning/online/gepa/sessions/{session_id}/cancel

​
Reward Update

POST /api/prompt-learning/online/gepa/sessions/{session_id}/reward The proxy call returns identifiers in response headers:
  • x-gepa-rollout-id
  • x-gepa-candidate-id
Use them in the reward update so the backend can attribute rewards correctly: 
{
  "reward_info": { "outcome_reward": 1.0, "seed": 123 },
  "rollout_id": "f0a1...",
  "candidate_id": "cand_..."
}
If you set "stop": true, the session will be marked completed.

​
Prompt URLs

GET /api/prompt-learning/online/gepa/sessions/{session_id}/prompt Returns the proxy URLs you should call for inference.

​
Proxy (Prompt Substitution)

The proxy behaves like a normal OpenAI-compatible Chat Completions endpoint, but it injects the selected candidate instruction into the request as the system message.

​
Chat Completions

POST /api/gepa/v1/{session_id}/chat/completions Example request: 
{
  "model": "gpt-4.1-mini",
  "messages": [
    { "role": "user", "content": "When will my card arrive?" }
  ]
}
Example response headers: 
x-gepa-system-id: 50b3f96d-916e-4780-a86c-37d6456e90fc
x-gepa-rollout-id: 3b7d...
x-gepa-candidate-id: baseline
Optional correlation routing (useful for multi-turn conversations):
  • POST /api/gepa/v1/{session_id}/{correlation_id}/chat/completions
  • POST /api/gepa/v1/{session_id}/{correlation_id}/v1/chat/completions