PUT/api/models/{slug}/waterfall

Replace your waterfall

Replaces your organization's override with model_provider_ids in order (position 0 is tried first); an empty list clears it. On a shared (public) model the chain must include at least one of your own connections (a byok:{connection_id} rung), otherwise 422: the platform's lane order on a shared model is not settable per organization. Any key of the organization may write; a session needs the org admin role. Idempotent; with expected_revision set, a concurrent change answers 409 and nothing changes.

認証: AuthorizationヘッダーにBearer形式のAPIキー

パスパラメータ

  • slugstring必須

    Model slug.

リクエストボディ

  • org_idstring | null

    Implied by a key.

  • model_provider_idsarray<string>必須

    Rung tokens in order, each at most once: deployment ids, byok:{connection_id} or model:{model_id}. Empty clears your override.

  • expected_revisioninteger | null

    Compare-and-swap guard: the override_revision you read.

レスポンス

  • 200

    The waterfall after the write.

    レスポンス
    • model_idstring
    • slugstring
    • org_idstring | null
    • defaultarray<object>
      default
      • idstring
      • positioninteger

        0 is tried first.

      • model_provider_idstring | null
      • provider_connection_idstring | null
      • target_kindenum
        "deployment""connection""model"
      • referenced_model_idstring | null
      • referenced_modelobject | null
        いずれか

        object

        • idstring
        • slugstring
        • display_namestring
        • statusstring
      • providerstring | null
      • provider_model_idstring | null
      • base_urlstring | null
      • statusstring
      • rungstring | null

        The token to send in a PUT or PATCH: the deployment id, byok:{connection_id} or model:{model_id}.

      • fundingenum
        "platform""own_key""own_endpoint""fallback_model"null
      • healthobject | null
        いずれか

        object

        • statestring

          Fleet verdict, for example healthy, degraded, recovering, throttled, circuit_open, disabled. A BYOK rung reports its connection status.

        • reasonstring | null
        • lifecycleenum
          "active""draining""retired"
    • overridearray | null

      Your organization's chain; null when you have none.

      override
      • idstring
      • positioninteger

        0 is tried first.

      • model_provider_idstring | null
      • provider_connection_idstring | null
      • target_kindenum
        "deployment""connection""model"
      • referenced_model_idstring | null
      • referenced_modelobject | null
        いずれか

        object

        • idstring
        • slugstring
        • display_namestring
        • statusstring
      • providerstring | null
      • provider_model_idstring | null
      • base_urlstring | null
      • statusstring
      • rungstring | null

        The token to send in a PUT or PATCH: the deployment id, byok:{connection_id} or model:{model_id}.

      • fundingenum
        "platform""own_key""own_endpoint""fallback_model"null
      • healthobject | null
        いずれか

        object

        • statestring

          Fleet verdict, for example healthy, degraded, recovering, throttled, circuit_open, disabled. A BYOK rung reports its connection status.

        • reasonstring | null
        • lifecycleenum
          "active""draining""retired"
    • default_revisioninteger
    • override_revisioninteger

      Send this back as expected_revision on a write.

    • default_stateenum
      "absent""available""empty""unavailable"
    • override_stateenum
      "absent""available""empty""unavailable"
    • model_references_enabledboolean

      Whether model:{model_id} fallback-model rungs are accepted.

    • semantics_activeboolean
    • failover_modeenum
      "maximize_cache""maximize_availability""maximize_cache_affinity"
    • throttle_cache_thresholdnumber | null
    • served_defaultarray | null

      The chain served to you without an override: the default with your substituting BYOK keys in place of the platform rungs they replace. Null without an acting organization.

      served_default
      • idstring
      • positioninteger

        0 is tried first.

      • model_provider_idstring | null
      • provider_connection_idstring | null
      • target_kindenum
        "deployment""connection""model"
      • referenced_model_idstring | null
      • referenced_modelobject | null
        いずれか

        object

        • idstring
        • slugstring
        • display_namestring
        • statusstring
      • providerstring | null
      • provider_model_idstring | null
      • base_urlstring | null
      • statusstring
      • rungstring | null

        The token to send in a PUT or PATCH: the deployment id, byok:{connection_id} or model:{model_id}.

      • fundingenum
        "platform""own_key""own_endpoint""fallback_model"null
      • healthobject | null
        いずれか

        object

        • statestring

          Fleet verdict, for example healthy, degraded, recovering, throttled, circuit_open, disabled. A BYOK rung reports its connection status.

        • reasonstring | null
        • lifecycleenum
          "active""draining""retired"
  • 401

    Missing, unknown or revoked API key.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 403

    A session member below the org admin role.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 404

    The model, the organization, or a rung id is not visible to you (another organization's connection answers the same 404).

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 409

    expected_revision is stale: the chain changed since your read.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 422

    A per-organization chain on a shared model with no byok: rung, a repeated id, or a body validation failure.

リクエスト

curl -X PUT https://api.experientiallabs.ai/api/models/gpt-6-luna/waterfall \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model_provider_ids": [
    "byok:1e7c3b90-2f4d-4a68-9b15-c0d8e2a7f614",
    "b6574b0e-933c-4b69-993e-2a0d21e32385"
  ],
  "expected_revision": 0
}'

レスポンス

{
  "model_id": "6adffebe-5ed8-4466-8d2c-976afee63237",
  "slug": "gpt-6-luna",
  "org_id": "3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10",
  "default": [
    {
      "id": "81297474-de0d-401e-b193-61746f3a0576",
      "position": 0,
      "model_provider_id": "b6574b0e-933c-4b69-993e-2a0d21e32385",
      "provider_connection_id": null,
      "target_kind": "deployment",
      "referenced_model_id": null,
      "referenced_model": null,
      "provider": "openai",
      "provider_model_id": "gpt-6-luna",
      "base_url": null,
      "status": "active",
      "rung": "b6574b0e-933c-4b69-993e-2a0d21e32385",
      "funding": "platform",
      "health": {
        "state": "healthy",
        "reason": null,
        "lifecycle": "active"
      }
    }
  ],
  "override": [
    {
      "id": "2c7e9f14-8a3b-4d56-b1e0-6f4a2d8c9e37",
      "position": 0,
      "model_provider_id": null,
      "provider_connection_id": "1e7c3b90-2f4d-4a68-9b15-c0d8e2a7f614",
      "target_kind": "connection",
      "referenced_model_id": null,
      "referenced_model": null,
      "provider": "openai",
      "provider_model_id": "gpt-6-luna",
      "base_url": null,
      "status": "active",
      "rung": "byok:1e7c3b90-2f4d-4a68-9b15-c0d8e2a7f614",
      "funding": "own_key",
      "health": {
        "state": "healthy",
        "reason": null,
        "lifecycle": "active"
      }
    },
    {
      "id": "4e1b8d63-7c2a-4f09-a6d5-9b3e0c7f2a18",
      "position": 1,
      "model_provider_id": "b6574b0e-933c-4b69-993e-2a0d21e32385",
      "provider_connection_id": null,
      "target_kind": "deployment",
      "referenced_model_id": null,
      "referenced_model": null,
      "provider": "openai",
      "provider_model_id": "gpt-6-luna",
      "base_url": null,
      "status": "active",
      "rung": "b6574b0e-933c-4b69-993e-2a0d21e32385",
      "funding": "platform",
      "health": {
        "state": "healthy",
        "reason": null,
        "lifecycle": "active"
      }
    }
  ],
  "default_revision": 4,
  "override_revision": 1,
  "default_state": "available",
  "override_state": "available",
  "model_references_enabled": false,
  "semantics_active": true,
  "failover_mode": "maximize_cache",
  "throttle_cache_threshold": 0.5,
  "served_default": null
}

https://api.experientiallabs.ai/api/models/gpt-6-luna/waterfall