Great question. In Prefect 3.x, when you POST to /deployments/ you can include two related fields in the request body: -

parameters

(object) - What it is: Default parameter values for the flow that this deployment will run. - How it’s used: - Stored on the deployment and applied to every flow run created from this deployment (scheduled or manual). - Merged with any parameters you pass at run time (run-time values override deployment defaults). - Hydrated at run creation (e.g., Jinja templates and workspace variables are rendered before the run starts). - Optional; can be updated later via PATCH. -

parameter_openapi_schema

(object) - What it is: An OpenAPI/JSON Schema describing the flow’s parameters (types, defaults, required/optional, descriptions). - How it’s used: - Powers the Prefect UI to render parameter input forms for manual runs. - Enables server-side validation of parameters for runs created from this deployment when

enforce_parameter_schema

is true. - Optional; can be updated later via PATCH. Typical usage in a POST body looks like:

{
  "name": "my-deployment",
  "flow_id": "your-flow-id",
  "parameters": {
    "x": 10,
    "y": "{{ variables.default_y }}"   // can be hydrated at run time
  },
  "parameter_openapi_schema": {
    "type": "object",
    "properties": {
      "x": {"type": "integer", "description": "First param"},
      "y": {"type": "integer"}
    },
    "required": ["x"]
  },
  "enforce_parameter_schema": true
}

Key behaviors - If

enforce_parameter_schema

is true, Prefect validates deployment parameters at update time and run-time parameters when a run is created from the deployment. - At run creation, Prefect merges run-time parameters with the deployment’s

parameters

, then hydrates and validates (if enforcement is enabled). References - Deployments concept doc: Deployments (Prefect 3.x) - REST API (create deployment): Create Deployment API - Source (deployment run parameter merge/hydration/validation): server/api/deployments.py - Source (validators for parameters/schema): _internal/schemas/validators.py

Short answer: the flow run will fail if the missing parameter doesn’t have a default. Details (Prefect 3.x): - The deployment’s

parameters

are just defaults; they’re merged with any parameters you pass when creating a run. If your flow requires

asset_id

and

run_date

but the deployment only provides

asset_id

, then: - If

run_date

has no default in the flow function signature and you don’t supply it at run time, the run will fail immediately with a parameter validation error before the flow body executes. - If

run_date

has a default in the flow signature, the run will proceed using that default. -

parameter_openapi_schema

primarily powers the UI form and optional server-side validation when

enforce_parameter_schema

is true. If your schema omits

run_date

, the UI won’t prompt for it. With default JSON Schema semantics (no

additionalProperties: false

), passing

run_date

at run time is still allowed and will be accepted by the flow’s signature. - The function signature is always the final source of truth at runtime. Even if the schema doesn’t require

run_date

, a missing required parameter will still fail the run. References - Deployment run creation (merge, hydrate, optional schema validation): server/api/deployments.py - Runtime parameter-to-signature validation: utilities/callables.py - Validators for schema/parameters (enforcement flag): _internal/schemas/validators.py - Concept doc: Deployments (Prefect 3.x) Practical tips - Include all required flow parameters in both

parameters

(if you want defaults) and

parameter_openapi_schema

(so the UI prompts for them). - If you want to strictly prevent unknown parameters via API, set

enforce_parameter_schema: true

and define

additionalProperties: false

in your schema.