Developer documentation > API reference > REST API > Deployments > Runtime parameters

Runtime parameters¶

Use the endpoints described below to manage deployment runtime parameters for deployed custom models.

List runtime parameters by deployment ID¶

Operation path: GET /api/v2/deployments/{deploymentId}/runtimeParameters/

Authentication requirements: BearerAuth

List runtime parameters.

Notice: Endpoint is currently in [PUBLIC_PREVIEW]. Do not use it in production workflows to reduce risk. See details:

This endpoint depends on the following features that are subject to change.

Feature Flag	Maturity	Enabled by default	Description
CUSTOM_MODEL_EDIT_RUNTIME_PARAMETERS_ON_DEPLOYMENT	PUBLIC_PREVIEW	true	Enables the ability to edit Custom Model Runtime-Parameters (and replica and resource bundle settings) directly from the Deployment info page. Edited values are local to a given Deployment and do not affect the runtime of any current or future Deployments of the same Model Package.

Parameters

Name	In	Type	Required	Description
offset	query	integer	false	Number of results to skip.
limit	query	integer	false	At most this many results are returned. The default may change without notice.
orderBy	query	string	true	The sort order to apply to the runtime parameters list. Prefix the attribute name with a dash to sort in descending order; for example: '-created_at'.
deploymentId	path	string	true	Unique identifier of the deployment.

Enumerated Values¶

Parameter	Value
orderBy	[`createdAt`, `-createdAt`, `name`, `-name`]

Example responses¶

200 Response

{
  "properties": {
    "count": {
      "description": "Number of items returned on this page.",
      "type": "integer"
    },
    "data": {
      "description": "A unified view of the defined runtime parameters for this object, including the values that are currently set. Includes the ID of the key value associated with a runtime parameter.",
      "items": {
        "properties": {
          "allowEmpty": {
            "default": true,
            "description": "Indicates whether the param must be set before registration",
            "type": "boolean"
          },
          "credentialType": {
            "description": "The type of credential, required only for credentials parameters.",
            "enum": [
              "adlsGen2Oauth",
              "apiToken",
              "azure",
              "azureOauth",
              "azureServicePrincipal",
              "basic",
              "bearer",
              "databricksAccessTokenAccount",
              "databricksServicePrincipalAccount",
              "gcp",
              "oauth",
              "rsa",
              "s3",
              "sapOauth",
              "snowflakeKeyPairUserAccount",
              "snowflakeOauthUserAccount",
              "tableauAccessToken"
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "currentValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Given the default and the override, this is the actual current value of the parameter."
          },
          "defaultValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "The default value for the given field."
          },
          "description": {
            "description": "Description how this parameter impacts the running model.",
            "type": [
              "string",
              "null"
            ]
          },
          "fieldName": {
            "description": "The parameter name. This value will be added as an environment variable when running custom models.",
            "type": "string"
          },
          "keyValueId": {
            "description": "The ID of the key value associated with a runtime parameter.",
            "type": [
              "string",
              "null"
            ]
          },
          "maxValue": {
            "description": "The maximum value for a numeric field.",
            "type": [
              "number",
              "null"
            ]
          },
          "minValue": {
            "description": "The minimum value for a numeric field.",
            "type": [
              "number",
              "null"
            ]
          },
          "overrideValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Value set by the user that overrides the default set in the definition."
          },
          "type": {
            "description": "The value type that the parameter accepts.",
            "enum": [
              "boolean",
              "credential",
              "deployment",
              "numeric",
              "string"
            ],
            "type": "string"
          }
        },
        "required": [
          "fieldName",
          "type"
        ],
        "type": "object",
        "x-versionadded": "v2.35"
      },
      "maxItems": 1000,
      "type": "array"
    },
    "next": {
      "description": "URL pointing to the next page (if null, there is no next page).",
      "format": "uri",
      "type": [
        "string",
        "null"
      ]
    },
    "previous": {
      "description": "URL pointing to the previous page (if null, there is no previous page).",
      "format": "uri",
      "type": [
        "string",
        "null"
      ]
    },
    "totalCount": {
      "description": "The total number of items across all pages.",
      "type": "integer"
    }
  },
  "required": [
    "next",
    "previous",
    "totalCount"
  ],
  "type": "object",
  "x-versionadded": "v2.35"
}

Responses¶

Status	Meaning	Description	Schema
200	OK	none	RuntimeParameterListResponse

Update runtime parameters by deployment ID¶

Operation path: PUT /api/v2/deployments/{deploymentId}/runtimeParameters/

Authentication requirements: BearerAuth

Update runtime parameters by replacing existing params with the provided set. Any values not provided will revert back to the values set from the model package.

Notice: Endpoint is currently in [PUBLIC_PREVIEW]. Do not use it in production workflows to reduce risk. See details:

This endpoint depends on the following features that are subject to change.

Feature Flag	Maturity	Enabled by default	Description
CUSTOM_MODEL_EDIT_RUNTIME_PARAMETERS_ON_DEPLOYMENT	PUBLIC_PREVIEW	true	Enables the ability to edit Custom Model Runtime-Parameters (and replica and resource bundle settings) directly from the Deployment info page. Edited values are local to a given Deployment and do not affect the runtime of any current or future Deployments of the same Model Package.

Body parameter¶

{
  "properties": {
    "runtimeParameterValues": {
      "description": "Inject values into a model at runtime. The fieldName must match a fieldName defined in the deployed model package. This list is merged with any existing runtime values.",
      "type": "string"
    }
  },
  "required": [
    "runtimeParameterValues"
  ],
  "type": "object",
  "x-versionadded": "v2.35"
}

Parameters

Name	In	Type	Required	Description
deploymentId	path	string	true	Unique identifier of the deployment.
body	body	RuntimeParameterUpdate	false	none

Example responses¶

200 Response

{
  "properties": {
    "count": {
      "description": "Number of items returned on this page.",
      "type": "integer"
    },
    "data": {
      "description": "A unified view of the defined runtime parameters for this object, including the values that are currently set. Includes the ID of the key value associated with a runtime parameter.",
      "items": {
        "properties": {
          "allowEmpty": {
            "default": true,
            "description": "Indicates whether the param must be set before registration",
            "type": "boolean"
          },
          "credentialType": {
            "description": "The type of credential, required only for credentials parameters.",
            "enum": [
              "adlsGen2Oauth",
              "apiToken",
              "azure",
              "azureOauth",
              "azureServicePrincipal",
              "basic",
              "bearer",
              "databricksAccessTokenAccount",
              "databricksServicePrincipalAccount",
              "gcp",
              "oauth",
              "rsa",
              "s3",
              "sapOauth",
              "snowflakeKeyPairUserAccount",
              "snowflakeOauthUserAccount",
              "tableauAccessToken"
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "currentValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Given the default and the override, this is the actual current value of the parameter."
          },
          "defaultValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "The default value for the given field."
          },
          "description": {
            "description": "Description how this parameter impacts the running model.",
            "type": [
              "string",
              "null"
            ]
          },
          "fieldName": {
            "description": "The parameter name. This value will be added as an environment variable when running custom models.",
            "type": "string"
          },
          "keyValueId": {
            "description": "The ID of the key value associated with a runtime parameter.",
            "type": [
              "string",
              "null"
            ]
          },
          "maxValue": {
            "description": "The maximum value for a numeric field.",
            "type": [
              "number",
              "null"
            ]
          },
          "minValue": {
            "description": "The minimum value for a numeric field.",
            "type": [
              "number",
              "null"
            ]
          },
          "overrideValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Value set by the user that overrides the default set in the definition."
          },
          "type": {
            "description": "The value type that the parameter accepts.",
            "enum": [
              "boolean",
              "credential",
              "deployment",
              "numeric",
              "string"
            ],
            "type": "string"
          }
        },
        "required": [
          "fieldName",
          "type"
        ],
        "type": "object",
        "x-versionadded": "v2.35"
      },
      "maxItems": 1000,
      "type": "array"
    },
    "next": {
      "description": "URL pointing to the next page (if null, there is no next page).",
      "format": "uri",
      "type": [
        "string",
        "null"
      ]
    },
    "previous": {
      "description": "URL pointing to the previous page (if null, there is no previous page).",
      "format": "uri",
      "type": [
        "string",
        "null"
      ]
    },
    "totalCount": {
      "description": "The total number of items across all pages.",
      "type": "integer"
    }
  },
  "required": [
    "next",
    "previous",
    "totalCount"
  ],
  "type": "object",
  "x-versionadded": "v2.35"
}

Responses¶

Status	Meaning	Description	Schema
200	OK	none	RuntimeParameterListResponse

Schemas¶

RuntimeParameterListResponse

{
  "properties": {
    "count": {
      "description": "Number of items returned on this page.",
      "type": "integer"
    },
    "data": {
      "description": "A unified view of the defined runtime parameters for this object, including the values that are currently set. Includes the ID of the key value associated with a runtime parameter.",
      "items": {
        "properties": {
          "allowEmpty": {
            "default": true,
            "description": "Indicates whether the param must be set before registration",
            "type": "boolean"
          },
          "credentialType": {
            "description": "The type of credential, required only for credentials parameters.",
            "enum": [
              "adlsGen2Oauth",
              "apiToken",
              "azure",
              "azureOauth",
              "azureServicePrincipal",
              "basic",
              "bearer",
              "databricksAccessTokenAccount",
              "databricksServicePrincipalAccount",
              "gcp",
              "oauth",
              "rsa",
              "s3",
              "sapOauth",
              "snowflakeKeyPairUserAccount",
              "snowflakeOauthUserAccount",
              "tableauAccessToken"
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "currentValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Given the default and the override, this is the actual current value of the parameter."
          },
          "defaultValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "The default value for the given field."
          },
          "description": {
            "description": "Description how this parameter impacts the running model.",
            "type": [
              "string",
              "null"
            ]
          },
          "fieldName": {
            "description": "The parameter name. This value will be added as an environment variable when running custom models.",
            "type": "string"
          },
          "keyValueId": {
            "description": "The ID of the key value associated with a runtime parameter.",
            "type": [
              "string",
              "null"
            ]
          },
          "maxValue": {
            "description": "The maximum value for a numeric field.",
            "type": [
              "number",
              "null"
            ]
          },
          "minValue": {
            "description": "The minimum value for a numeric field.",
            "type": [
              "number",
              "null"
            ]
          },
          "overrideValue": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Value set by the user that overrides the default set in the definition."
          },
          "type": {
            "description": "The value type that the parameter accepts.",
            "enum": [
              "boolean",
              "credential",
              "deployment",
              "numeric",
              "string"
            ],
            "type": "string"
          }
        },
        "required": [
          "fieldName",
          "type"
        ],
        "type": "object",
        "x-versionadded": "v2.35"
      },
      "maxItems": 1000,
      "type": "array"
    },
    "next": {
      "description": "URL pointing to the next page (if null, there is no next page).",
      "format": "uri",
      "type": [
        "string",
        "null"
      ]
    },
    "previous": {
      "description": "URL pointing to the previous page (if null, there is no previous page).",
      "format": "uri",
      "type": [
        "string",
        "null"
      ]
    },
    "totalCount": {
      "description": "The total number of items across all pages.",
      "type": "integer"
    }
  },
  "required": [
    "next",
    "previous",
    "totalCount"
  ],
  "type": "object",
  "x-versionadded": "v2.35"
}

Properties¶

Name	Type	Required	Restrictions	Description
count	integer	false		Number of items returned on this page.
data	[RuntimeParameterResponse]	false	maxItems: 1000	A unified view of the defined runtime parameters for this object, including the values that are currently set. Includes the ID of the key value associated with a runtime parameter.
next	string,null(uri)	true		URL pointing to the next page (if null, there is no next page).
previous	string,null(uri)	true		URL pointing to the previous page (if null, there is no previous page).
totalCount	integer	true		The total number of items across all pages.

RuntimeParameterResponse

{
  "properties": {
    "allowEmpty": {
      "default": true,
      "description": "Indicates whether the param must be set before registration",
      "type": "boolean"
    },
    "credentialType": {
      "description": "The type of credential, required only for credentials parameters.",
      "enum": [
        "adlsGen2Oauth",
        "apiToken",
        "azure",
        "azureOauth",
        "azureServicePrincipal",
        "basic",
        "bearer",
        "databricksAccessTokenAccount",
        "databricksServicePrincipalAccount",
        "gcp",
        "oauth",
        "rsa",
        "s3",
        "sapOauth",
        "snowflakeKeyPairUserAccount",
        "snowflakeOauthUserAccount",
        "tableauAccessToken"
      ],
      "type": [
        "string",
        "null"
      ]
    },
    "currentValue": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Given the default and the override, this is the actual current value of the parameter."
    },
    "defaultValue": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "The default value for the given field."
    },
    "description": {
      "description": "Description how this parameter impacts the running model.",
      "type": [
        "string",
        "null"
      ]
    },
    "fieldName": {
      "description": "The parameter name. This value will be added as an environment variable when running custom models.",
      "type": "string"
    },
    "keyValueId": {
      "description": "The ID of the key value associated with a runtime parameter.",
      "type": [
        "string",
        "null"
      ]
    },
    "maxValue": {
      "description": "The maximum value for a numeric field.",
      "type": [
        "number",
        "null"
      ]
    },
    "minValue": {
      "description": "The minimum value for a numeric field.",
      "type": [
        "number",
        "null"
      ]
    },
    "overrideValue": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Value set by the user that overrides the default set in the definition."
    },
    "type": {
      "description": "The value type that the parameter accepts.",
      "enum": [
        "boolean",
        "credential",
        "deployment",
        "numeric",
        "string"
      ],
      "type": "string"
    }
  },
  "required": [
    "fieldName",
    "type"
  ],
  "type": "object",
  "x-versionadded": "v2.35"
}

Properties¶

Name	Type	Required	Description
allowEmpty	boolean	false	Indicates whether the param must be set before registration
credentialType	string,null	false	The type of credential, required only for credentials parameters.
currentValue	any	false	Given the default and the override, this is the actual current value of the parameter.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	number	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	boolean	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Restrictions	Description
defaultValue	any	false		The default value for the given field.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	number	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	boolean	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Description
description	string,null	false	Description how this parameter impacts the running model.
fieldName	string	true	The parameter name. This value will be added as an environment variable when running custom models.
keyValueId	string,null	false	The ID of the key value associated with a runtime parameter.
maxValue	number,null	false	The maximum value for a numeric field.
minValue	number,null	false	The minimum value for a numeric field.
overrideValue	any	false	Value set by the user that overrides the default set in the definition.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	number	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	boolean	false		none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false		none

continued

Name	Type	Required	Restrictions	Description
type	string	true		The value type that the parameter accepts.

Enumerated Values¶

Property	Value
credentialType	[`adlsGen2Oauth`, `apiToken`, `azure`, `azureOauth`, `azureServicePrincipal`, `basic`, `bearer`, `databricksAccessTokenAccount`, `databricksServicePrincipalAccount`, `gcp`, `oauth`, `rsa`, `s3`, `sapOauth`, `snowflakeKeyPairUserAccount`, `snowflakeOauthUserAccount`, `tableauAccessToken`]
type	[`boolean`, `credential`, `deployment`, `numeric`, `string`]

RuntimeParameterUpdate

{
  "properties": {
    "runtimeParameterValues": {
      "description": "Inject values into a model at runtime. The fieldName must match a fieldName defined in the deployed model package. This list is merged with any existing runtime values.",
      "type": "string"
    }
  },
  "required": [
    "runtimeParameterValues"
  ],
  "type": "object",
  "x-versionadded": "v2.35"
}

Properties¶

Name	Type	Required	Restrictions	Description
runtimeParameterValues	string	true		Inject values into a model at runtime. The fieldName must match a fieldName defined in the deployed model package. This list is merged with any existing runtime values.