API overview

Base URL

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

All runtime examples in this documentation use the production API base.

This reference intentionally covers only endpoints intended for customer use. Browser implementation details, payment and provider callbacks, and operator-only routes are not part of the public API.

Endpoint families

Family	Example	Primary auth	Purpose
Runtime v1	/v1/leaderboard/{id}/inference, /v1/models/{id}/inference	Dr.Gero API token	Leaderboard/model 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	Supabase user session	Workspace administration and model deployment.

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, POST, PUT, DELETE	/api/leaderboards/{leaderboard_id}/human/...	Human case, review, document and export APIs. Supabase session required.
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.
GET	/api/leaderboards/{leaderboard_id}/artifacts	List downloadable run artifacts.
GET	/api/leaderboards/{leaderboard_id}/artifacts/{artifact_id}/download	Create a short-lived artifact download URL.
PATCH, PUT, POST	/api/leaderboards/{leaderboard_id}/run/webhook	Configure run-event delivery.
PATCH, PUT, POST	/api/leaderboards/{leaderboard_id}/inference/webhook	Configure inference-event delivery.
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/models/{model_id}/versions	List successful immutable model versions.
POST	/api/models/{model_id}/versions/{version_id}/deploy	Deploy a selected model version. Browser session endpoint.
POST	/v1/models/{model_id}/inference	Run inference through the model's active deployment.
POST	/v1/models/{model_id}/versions/{version_id}/inference	Run inference through one exact deployed version.
GET	/api/models/{model_id}/inference/logs	List model inference logs.
PATCH, PUT, POST	/api/models/{model_id}/inference/webhook	Configure model inference log delivery.
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, POST, PUT, PATCH	/api/integrations	List or save workspace integrations. Browser session endpoint.
POST, PUT, PATCH, DELETE	/api/integrations/{provider}	Save or remove one workspace integration. 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

An OpenAPI 3.1 file for the public API is available at /openapi.yaml. It intentionally excludes private operational and third-party callback routes.