Inference API

The inference endpoint routes a request through the leaderboard's selected model.

export API_BASE="https://dr-gero-frontend-99142474693.europe-west1.run.app"
export DRGERO_TOKEN="drgero_REPLACE_WITH_TOKEN_FROM_SETTINGS"
export LEADERBOARD_ID="b60fe691-06a3-4261-bec3-6080380dc72d"

Request

curl -sS -X POST "$API_BASE/v1/leaderboard/$LEADERBOARD_ID/inference" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What did the user ask?"
  }'

Requires leaderboards:inference and a completed leaderboard ranking.

Alternate path

The same handler is also available under:

POST /api/leaderboards/{leaderboard_id}/inference

Use the /v1/leaderboard/... path for public runtime integrations.

Body fields

Field	Type	Description
input	string	Main task input.
prompt, question, query	string	Aliases used when input is absent.
messages	array	Chat messages. If present, messages are forwarded instead of rendering the leaderboard prompt around input.
temperature, max_tokens, etc.	any	Forwarded to compatible providers when safe.
stream	boolean	Streaming is not supported; stream: true returns an error.

Reserved fields such as model, input, prompt, question, and query are not forwarded as provider overrides.

Prompt rendering

If you pass input, Dr.Gero renders the leaderboard challenge prompt:

• If the prompt contains {input}, {question}, or {query}, the placeholder is replaced.
• If it has no placeholder, the input is appended to the prompt.

If you pass messages, the messages are sent as the chat payload and prompt rendering is skipped.

Selected model behavior

The selected model is determined by the leaderboard:

• ranking_winner: use the top model from the latest completed ranking.
• manual: use the pinned leaderboard model.

A leaderboard without a completed ranking returns a conflict error until a run completes.

Response headers

Important response headers:

X-Dr.Gero-Trace-Id: 9fe32c4b-...
X-Dr.Gero-Leaderboard-Model-Id: 3e3c79c0-...
X-Dr.Gero-Model-Source: OpenRouter
X-Dr.Gero-Model-Ref: openai/gpt-5.2
X-Dr.Gero-Token-Budget-Remaining-Usd: 19.42

Store X-Dr.Gero-Trace-Id with your application logs so you can join production events to Dr.Gero traces.

OpenAI-style request example

curl -sS -X POST "$API_BASE/v1/leaderboard/$LEADERBOARD_ID/inference" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "Answer as a concise support agent."},
      {"role": "user", "content": "Can I reset my password?"}
    ],
    "temperature": 0.2,
    "max_tokens": 300
  }' | jq

Common errors

Status	Meaning
401	Missing/invalid token.
403	Token lacks leaderboards:inference or workspace lacks entitlement.
404	Leaderboard not found.
409	Leaderboard has no completed ranking/selected model yet.
400	Invalid body, including stream: true.