Adapter versions

Each training run makes a new adapter version of its task. These operations read the versions and move one through promotion. Mubit also moves versions by itself; these calls do it by hand.

All paths are under https://api.mubit.ai, with a management key in Authorization: Bearer. Management API covers keys, roles, pagination, retries and errors. The samples read the key from MUBIT_MANAGEMENT_KEY.

List adapter versions

GET /api/v1/tasks/{task_id}/versions

Lists the task's adapter versions.

Role: read or higher.

curl "https://api.mubit.ai/api/v1/tasks/$TASK_ID/versions" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY"

Response 200: Version list

Each item of data:

{
  "data": [
    {
      "id": "ver_002",
      "task_id": "task_triage12",
      "version_number": 2,
      "status": "promoted",
      "score": 0.88,
      "base_model": "Qwen/Qwen3-4B-Instruct-2507",
      "created_at": "2026-10-24T00:00:00Z"
    }
  ],
  "next_cursor": null
}

Get a version

GET /api/v1/versions/{version_id}

Returns one adapter version with its test results and its canary and shadow shares.

Role: read or higher.

curl "https://api.mubit.ai/api/v1/versions/$VERSION_ID" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY"

Response 200: Version details

{
  "id": "ver_002",
  "task_id": "task_triage12",
  "version_number": 2,
  "status": "promoted",
  "score": 0.88,
  "canary_percent": 100,
  "shadow_percent": 0,
  "eval_metrics": {
    "accuracy": 0.92,
    "latency_p50_ms": 180
  }
}

Promote a version

POST /api/v1/versions/{version_id}/promote

Promotes the version, so it answers the task's calls. A version that can't be promoted now is 409.

Role: admin.

Request body (optional)

curl -X POST "https://api.mubit.ai/api/v1/versions/$VERSION_ID/promote" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Cleared 90% accuracy hurdle"}'

Response 200: Version promoted

{
  "id": "ver_002",
  "status": "promoted"
}

Roll back a version

POST /api/v1/versions/{version_id}/rollback

Rolls back the promoted version and promotes the version promoted before it again. The version must be the promoted one (409 not_promoted otherwise). It takes no body.

Role: admin.

curl -X POST "https://api.mubit.ai/api/v1/versions/$VERSION_ID/rollback" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

Response 200: Version rolled back

{
  "id": "ver_2_support-triage",
  "status": "rolled_back",
  "restored_version_id": "ver_1_support-triage"
}

Set canary or shadow share

PATCH /api/v1/versions/{version_id}/rollout

Sets the version's canary or shadow share, in percent. canary_percent above 0 makes it a canary at that share; shadow_percent above 0 makes it a shadow at that share. Both above 0 is 400: a version is in one state at a time. Both 0 takes a canary or shadow out (409 for the promoted version). A share you leave out stays as it is. The answer is the share now in effect.

Role: admin.

curl -X PATCH "https://api.mubit.ai/api/v1/versions/$VERSION_ID/rollout" \
  -H "Authorization: Bearer $MUBIT_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"canary_percent":25}'

Response 200: Rollout updated

{
  "id": "ver_2_support-triage",
  "canary_percent": 25,
  "shadow_percent": 0
}