API overview

Base URL

export API_BASE="https://dr-gero-frontend-99142474693.europe-west1.run.app"

All runtime examples in this documentation use that Cloud Run base. Replace API_BASE only after a custom domain is confirmed.

Endpoint families

Family	Example	Primary auth	Purpose
Runtime v1	/v1/leaderboard/{id}/inference	Dr.Gero API token	Inference, traces, and push datasets.
Resource API	/api/leaderboards, /api/models	Dr.Gero API token	Automate leaderboard/model CRUD and runs.
Browser-session APIs	/api/tokens, /api/invite-user, /api/integrations/validate	Supabase user session	Workspace admin actions from the UI.
Operator APIs	/api/leaderboard-schedules/run-due, /api/push-datasets/consolidate-due	Deployment cron secret	Backend cron jobs.

Health check

curl -sS "$API_BASE/healthz" | jq

The readiness endpoint is also available at /readyz.

Content type

Use JSON for request bodies:

Content-Type: application/json

Most successful responses are JSON. Trace export can return JSONL when format=jsonl or format=ndjson is requested.

Public API conventions

• IDs are UUIDs.
• List endpoints support limit and offset where available.
• Errors return JSON with at least error or message.
• Runtime inference responses include Dr.Gero headers for trace ID, selected model, and budget state when available.

API map

Method	Path	Description
GET	/healthz	Service health.
GET	/readyz	Service readiness.
GET	/api/leaderboards	List leaderboards.
POST	/api/leaderboards	Create a leaderboard.
GET	/api/leaderboards/{leaderboard_id}	Get leaderboard detail.
PATCH	/api/leaderboards/{leaderboard_id}	Update leaderboard.
DELETE	/api/leaderboards/{leaderboard_id}	Delete leaderboard.
GET	/api/leaderboards/{leaderboard_id}/models	List candidate models.
POST	/api/leaderboards/{leaderboard_id}/models	Add a candidate model.
DELETE	/api/leaderboards/{leaderboard_id}/models/{leaderboard_model_id}	Remove a candidate model.
POST	/api/leaderboards/{leaderboard_id}/models/auto-select	Auto-select OpenRouter candidate models. UI session endpoint.
GET	/api/leaderboards/{leaderboard_id}/runs	List leaderboard runs.
POST	/api/leaderboards/{leaderboard_id}/run	Start a leaderboard run.
POST	/api/leaderboards/{leaderboard_id}/improve-dataset	Run with dataset improvement behavior.
POST	/v1/leaderboard/{leaderboard_id}/inference	Run inference through the selected leaderboard model.
GET	/v1/leaderboard/{leaderboard_id}/traces	Export traces.
POST	/v1/leaderboard/{leaderboard_id}/dataset/push	Push rows into a PUSH dataset.
GET	/v1/leaderboard/{leaderboard_id}/dataset/status	View push dataset status.
GET	/v1/leaderboard/{leaderboard_id}/dataset	Download consolidated JSONL dataset.
POST	/v1/leaderboard/{leaderboard_id}/dataset/token	Create a push dataset token.
DELETE	/v1/leaderboard/{leaderboard_id}/dataset/tokens	Revoke push dataset tokens.
POST	/v1/leaderboard/{leaderboard_id}/dataset/consolidate	Consolidate pending push dataset rows.
POST	/v1/leaderboard/{leaderboard_id}/dataset/auto-labels	Generate/update dataset labels.
GET	/api/models	List Dr.Gero models.
POST	/api/models	Create a Dr.Gero model.
GET	/api/models/{model_id}	Get model detail.
PATCH	/api/models/{model_id}	Update model.
DELETE	/api/models/{model_id}	Delete model.
GET	/api/models/{model_id}/leaderboards	List leaderboards assigned to a model.
GET	/api/models/{model_id}/fine-tune/runs	List fine-tune runs.
POST	/api/models/{model_id}/fine-tune/run	Start fine-tuning.
POST	/api/models/{model_id}/fine-tune/sync	Sync fine-tune state.
GET	/api/base-models	List supported base models.
POST	/api/datasets/huggingface/check	Validate a Hugging Face JSONL dataset URL.
GET	/api/tokens	List API tokens. Browser session endpoint.
POST	/api/tokens	Create an API token. Browser session endpoint.
POST	/api/tokens/{token_id}/revoke	Revoke an API token. Browser session endpoint.
DELETE	/api/tokens/{token_id}	Delete an API token. Browser session endpoint.
POST	/api/integrations/validate	Validate provider credentials. Browser session endpoint.
GET	/api/invite-user	List workspace members/invites. Browser session endpoint.
POST	/api/invite-user	Invite a workspace user. Browser session endpoint.
DELETE	/api/invite-user	Remove a member or revoke invite. Browser session endpoint.

OpenAPI

A draft OpenAPI 3.1 file is included at /openapi.yaml. Treat it as implementation documentation, not a public stability guarantee.