/api/models/{slug}/waterfallReplace 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.
Authentication: Bearer API key in the Authorization header
Path parameters
slugstringrequiredModel slug.
Request body
org_idstring | nullImplied by a key.
model_provider_idsarray<string>requiredRung tokens in order, each at most once: deployment ids,
byok:{connection_id}ormodel:{model_id}. Empty clears your override.expected_revisioninteger | nullCompare-and-swap guard: the
override_revisionyou read.
Responses
200The waterfall after the write.
Response
model_idstringslugstringorg_idstring | nulldefaultarray<object>default
idstringpositioninteger0 is tried first.
model_provider_idstring | nullprovider_connection_idstring | nulltarget_kindenumreferenced_model_idstring | nullreferenced_modelobject | nullOne of
object
idstringslugstringdisplay_namestringstatusstring
providerstring | nullprovider_model_idstring | nullbase_urlstring | nullstatusstringrungstring | nullThe token to send in a PUT or PATCH: the deployment id,
byok:{connection_id}ormodel:{model_id}.fundingenumhealthobject | nullOne of
object
statestringFleet verdict, for example healthy, degraded, recovering, throttled, circuit_open, disabled. A BYOK rung reports its connection status.
reasonstring | nulllifecycleenum
overridearray | nullYour organization's chain; null when you have none.
override
idstringpositioninteger0 is tried first.
model_provider_idstring | nullprovider_connection_idstring | nulltarget_kindenumreferenced_model_idstring | nullreferenced_modelobject | nullOne of
object
idstringslugstringdisplay_namestringstatusstring
providerstring | nullprovider_model_idstring | nullbase_urlstring | nullstatusstringrungstring | nullThe token to send in a PUT or PATCH: the deployment id,
byok:{connection_id}ormodel:{model_id}.fundingenumhealthobject | nullOne of
object
statestringFleet verdict, for example healthy, degraded, recovering, throttled, circuit_open, disabled. A BYOK rung reports its connection status.
reasonstring | nulllifecycleenum
default_revisionintegeroverride_revisionintegerSend this back as
expected_revisionon a write.default_stateenumoverride_stateenummodel_references_enabledbooleanWhether
model:{model_id}fallback-model rungs are accepted.semantics_activebooleanfailover_modeenumthrottle_cache_thresholdnumber | nullserved_defaultarray | nullThe 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
idstringpositioninteger0 is tried first.
model_provider_idstring | nullprovider_connection_idstring | nulltarget_kindenumreferenced_model_idstring | nullreferenced_modelobject | nullOne of
object
idstringslugstringdisplay_namestringstatusstring
providerstring | nullprovider_model_idstring | nullbase_urlstring | nullstatusstringrungstring | nullThe token to send in a PUT or PATCH: the deployment id,
byok:{connection_id}ormodel:{model_id}.fundingenumhealthobject | nullOne of
object
statestringFleet verdict, for example healthy, degraded, recovering, throttled, circuit_open, disabled. A BYOK rung reports its connection status.
reasonstring | nulllifecycleenum
401Missing, unknown or revoked API key.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
403A session member below the org admin role.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
404The model, the organization, or a rung id is not visible to you (another organization's connection answers the same 404).
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
409expected_revisionis stale: the chain changed since your read.Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
422A per-organization chain on a shared model with no
byok:rung, a repeated id, or a body validation failure.
Request
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
}'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": 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