Dr.Gero Docs

Appearance

Models and fine-tuning API ​

The model resource API manages Dr.Gero model objects and fine-tune runs.

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

List models ​

bash
curl -sS "$API_BASE/api/models?limit=50&offset=0" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Requires models:read.

Create a model ​

bash
curl -sS -X POST "$API_BASE/api/models" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant Fine Tune",
    "description": "Fine-tuned from support leaderboards",
    "leaderboard_ids": ["b60fe691-06a3-4261-bec3-6080380dc72d"],
    "creation_mode": "auto",
    "auto_update_model": true,
    "continuous_self_learning": true,
    "hypertuning_parameters": false
  }' | jq

Requires models:write.

Accepted aliases include camelCase variants such as modelName, leaderboardIds, creationMode, autoUpdateModel, and continuousSelfLearning.

Every assigned leaderboard must use a webhook or Hugging Face dataset with at least 100 rows, and it must not be running. The API returns leaderboard_dataset_min_rows_required or leaderboard_running_assignment_blocked when an assignment is not eligible.

Get, update, and delete a model ​

bash
curl -sS "$API_BASE/api/models/$MODEL_ID" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

curl -sS -X PATCH "$API_BASE/api/models/$MODEL_ID" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated description"}' | jq

curl -sS -X DELETE "$API_BASE/api/models/$MODEL_ID" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Base models ​

bash
curl -sS "$API_BASE/api/base-models" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Requires models:read.

Assigned leaderboards ​

bash
curl -sS "$API_BASE/api/models/$MODEL_ID/leaderboards" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Fine-tune runs ​

List runs:

bash
curl -sS "$API_BASE/api/models/$MODEL_ID/fine-tune/runs" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Start a run:

bash
curl -sS -X POST "$API_BASE/api/models/$MODEL_ID/fine-tune/run" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_size": {
      "mode": "LIMIT",
      "limit": {"auto": false, "rows": 1000, "algorithm": "LAST_N"}
    },
    "create_synthetic_data": false,
    "hypertuning_enabled": true
  }' | jq

Sync run state:

bash
curl -sS -X POST "$API_BASE/api/models/$MODEL_ID/fine-tune/sync" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"run_id":"OPTIONAL_RUN_ID"}' | jq

Requires models:fine-tune.

Versions and deployment ​

Each successful fine-tune produces an immutable version. List versions and their deployment status with:

bash
curl -sS "$API_BASE/api/models/$MODEL_ID/versions" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Requires models:read. The response includes each version's ID, creation and completion timestamps, base model, deployment status, and exact-version inference URL when deployed. Artifact locations and deployment credentials are not exposed.

Deploy one version with a signed-in owner/admin session:

bash
curl -sS -X POST \
  "$API_BASE/api/models/$MODEL_ID/versions/$VERSION_ID/deploy" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "max_workers": 3,
    "active_workers": 0,
    "default_max_new_tokens": 300,
    "idle_timeout": 5
  }' | jq

Supported options are max_workers (1–100), active_workers (0 through max_workers), default_max_new_tokens (1–4096), and idle_timeout (1–3600). All other deployment configuration is managed by Dr.Gero.

Schedule fine-tuning ​

Schedules are saved by patching the model:

bash
curl -sS -X PATCH "$API_BASE/api/models/$MODEL_ID" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fine_tune_schedule": {
      "run": {"type": "WEEKLY"},
      "dataset": {
        "mode": "LIMIT",
        "limit": {"auto": false, "rows": 2000, "algorithm": "WEIGHTED_SHUFFLE"}
      }
    }
  }' | jq

Schedule changes may require a paid entitlement.

Continuous-learning schedules can be enabled only after the model has completed its first successful fine-tune run.

Direct model inference ​

After a successful fine tune, deploy a version from Models → Versions. Once the model has an active version, call its stable Dr.Gero endpoint:

bash
curl -sS -X POST "$API_BASE/v1/models/$MODEL_ID/inference" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Summarize this support request."}
    ],
    "temperature": 0.2,
    "max_tokens": 300
  }' | jq

Requires models:inference. The stable endpoint uses the most recently deployed active version. The alias POST /api/models/{model_id}/inference uses the same handler. Successful synchronous responses may include:

http
X-Dr.Gero-Model-Id: 0f9d93df-...
X-Dr.Gero-Model-Version-Id: 1e7dcf3a-...
X-Dr.Gero-Model-Message-Id: 72e18a0c-...

The version ID identifies the selected immutable fine-tune version. The message ID is present when the inference log was persisted. A model without a successful fine tune or active deployment returns 409 Conflict.

To call one exact deployed version, use:

bash
curl -sS -X POST \
  "$API_BASE/v1/models/$MODEL_ID/versions/$VERSION_ID/inference" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Summarize this request."}]}' | jq

POST /api/models/{model_id}/versions/{version_id}/inference is an equivalent alias. The version must have an active deployment.

Inference logs ​

bash
curl -sS "$API_BASE/api/models/$MODEL_ID/inference/logs?limit=100" \
  -H "Authorization: Bearer $DRGERO_TOKEN" | jq

Requires models:read. limit defaults to 100 and is capped at 100. The response is { "logs": [...] }; each log can include id, timestamp, input_message, output_messages, traces, metadata, and created_at. Private artifact locations, deployment secrets, and proxy credentials are redacted.

Inference webhook ​

Configure a webhook to receive each persisted inference log:

bash
curl -sS -X PATCH "$API_BASE/api/models/$MODEL_ID/inference/webhook" \
  -H "Authorization: Bearer $DRGERO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://example.com/dr-gero/model-inference",
    "enabled": true
  }' | jq

PATCH, PUT, and POST are accepted and require models:write. The URL must be a public HTTPS URL without embedded credentials. Send an empty or null webhook_url to clear and disable it.

Deliveries use this shape:

json
{
  "event": "model.inference",
  "delivered_at": "2026-08-03T12:00:00.000Z",
  "model": {
    "id": "0f9d93df-0000-4000-8000-000000000000",
    "business_id": "1d4a333f-0000-4000-8000-000000000000",
    "name": "Support Assistant Fine Tune"
  },
  "log": {
    "id": "72e18a0c-0000-4000-8000-000000000000",
    "timestamp": "2026-08-03T12:00:00.000Z",
    "input_message": {},
    "output_messages": {},
    "traces": {},
    "metadata": {},
    "created_at": "2026-08-03T12:00:00.000Z"
  }
}

Webhook delivery is best-effort and does not change the inference response. Its result is recorded in metadata.webhook_delivery when delivery was attempted.