PATCH/api/models/{slug}/waterfall

Edit your waterfall step by step

Applies operations in order to your current chain (your override, else served_default) and writes the result as one chain under compare-and-swap: expected_revision must equal the read's override_revision or the call answers 409 and changes nothing. The shared-model rule of PUT still applies (422). Any key of the organization may edit; a session needs the org admin role.

Authentication: Bearer API key in the Authorization header

Path parameters

  • slugstringrequired

    Model slug.

Request body

  • org_idstring | null

    Implied by a key.

  • expected_revisionintegerrequired

    The override_revision the edits were planned against.

  • operationsarray<object>required
    operations
    • openumrequired
      "add""remove""move"
    • rungstringrequired

      A rung token (the rung field of a read).

    • positioninteger | null

      0-based, clamped to the chain end. Omitted on add appends; required on move.

Responses

  • 200

    The waterfall after the edit (same shape as GET).

    Response
    • 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
        One of

        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
        One of

        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
        One of

        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
        One of

        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
        One of

        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
        One of

        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.

    Response
    • errorstringrequired

      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.

    Response
    • errorstringrequired

      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 or organization is not visible, or a move/remove names a rung that is not in the chain.

    Response
    • errorstringrequired

      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 no longer matches override_revision.

    Response
    • errorstringrequired

      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

    add of a rung already present, move without a position, a shared-model chain with no byok: rung, or a body validation failure.

Request

curl -X PATCH https://api.experientiallabs.ai/api/models/gpt-6-luna/waterfall \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_revision": 1,
  "operations": [
    {
      "op": "move",
      "rung": "byok:1e7c3b90-2f4d-4a68-9b15-c0d8e2a7f614",
      "position": 0
    },
    {
      "op": "add",
      "rung": "3a9d7c1e-5b2f-4e80-9c64-1d8f0a2b7e95"
    }
  ]
}'

Response

{
  "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": 2,
  "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