Create Deployment

Gracefully creates a new deployment from the provided schema. If a deployment with the same name and flow_id already exists, the deployment is updated.

If the deployment has an active schedule, flow runs will be scheduled. When upserting, any scheduled runs from the existing deployment will be deleted.

Headers

x-prefect-api-version

string

Body

application/json

Data used by the Prefect REST API to create a deployment.

flow_id

string

required

The ID of the flow associated with the deployment.

name

string

required

The name of the deployment.

concurrency_limit

integer | null

The deployment's concurrency limit.

Required range: x > 0

concurrency_options

object | null

The deployment's concurrency options.

Show child attributes

concurrency_options.collision_strategy

enum<string>

required

Enumeration of concurrency collision strategies.

Available options:

ENQUEUE,

CANCEL_NEW

description

string | null

enforce_parameter_schema

boolean

default:

true

Whether or not the deployment should enforce the parameter schema.

entrypoint

string | null

infrastructure_document_id

string | null

job_variables

object

Overrides for the flow's infrastructure configuration.

labels

object | null

A dictionary of key-value labels. Values can be strings, numbers, or booleans.

Show child attributes

labels.{key}

parameter_openapi_schema

object | null

The parameter schema of the flow, including defaults.

parameters

object

Parameters for flow runs scheduled by the deployment.

path

string | null

paused

boolean

default:

false

Whether or not the deployment is paused.

pull_steps

object[] | null

schedules

object[]

A list of schedules for the deployment.

Show child attributes

schedules.schedule

object

required

The schedule for the deployment.

• Schedule
• Schedule
• Schedule

Show child attributes

schedules.schedule.interval

number

required

schedules.schedule.anchor_date

string

schedules.schedule.timezone

string | null

schedules.active

boolean

default:

true

Whether or not the schedule is active.

schedules.max_scheduled_runs

integer | null

The maximum number of scheduled runs for the schedule.

Required range: x > 0

schedules.parameters

object

A dictionary of parameter value overrides.

storage_document_id

string | null

tags

string[]

A list of deployment tags.

version

string | null

work_pool_name

string | null

The name of the deployment's work pool.

work_queue_name

string | null

Response

200 - application/json

created

string | null

required

flow_id

string

required

The flow id associated with the deployment.

id

string

required

name

string

required

The name of the deployment.

updated

string | null

required

concurrency_limit

integer | null

deprecated

DEPRECATED: Prefer global_concurrency_limit. Will always be None for backwards compatibility. Will be removed after December 2024.

concurrency_options

object | null

The concurrency options for the deployment.

Show child attributes

concurrency_options.collision_strategy

enum<string>

required

Enumeration of concurrency collision strategies.

Available options:

ENQUEUE,

CANCEL_NEW

created_by

object | null

Optional information about the creator of this deployment.

Show child attributes

created_by.display_value

string | null

The display value for the creator.

created_by.id

string | null

The id of the creator of the object.

created_by.type

string | null

The type of the creator of the object.

description

string | null

A description for the deployment.

enforce_parameter_schema

boolean

default:

true

Whether or not the deployment should enforce the parameter schema.

entrypoint

string | null

The path to the entrypoint for the workflow, relative to the path.

global_concurrency_limit

object | null

The global concurrency limit object for enforcing the maximum number of flow runs that can be active at once.

Show child attributes

global_concurrency_limit.active_slots

integer

required

The number of active slots.

global_concurrency_limit.created

string | null

required

global_concurrency_limit.id

string

required

global_concurrency_limit.limit

integer

required

The concurrency limit.

global_concurrency_limit.name

string

required

The name of the global concurrency limit.

global_concurrency_limit.updated

string | null

required

global_concurrency_limit.active

boolean

default:

true

Whether the global concurrency limit is active.

global_concurrency_limit.slot_decay_per_second

number

default:

2

The decay rate for active slots when used as a rate limit.

infrastructure_document_id

string | null

The block document defining infrastructure to use for flow runs.

job_variables

object

Overrides to apply to the base infrastructure block at runtime.

labels

object

A dictionary of key-value labels. Values can be strings, numbers, or booleans.

Show child attributes

labels.{key}

last_polled

string | null

The last time the deployment was polled for status updates.

parameter_openapi_schema

object | null

The parameter schema of the flow, including defaults.

parameters

object

Parameters for flow runs scheduled by the deployment.

path

string | null

The path to the working directory for the workflow, relative to remote storage or an absolute path.

paused

boolean

default:

false

Whether or not the deployment is paused.

pull_steps

object[] | null

Pull steps for cloning and running this deployment.

schedules

object[]

A list of schedules for the deployment.

Show child attributes

schedules.created

string | null

required

schedules.id

string

required

schedules.schedule

object

required

The schedule for the deployment.

• Schedule
• Schedule
• Schedule

Show child attributes

schedules.schedule.interval

number

required

schedules.schedule.anchor_date

string

schedules.schedule.timezone

string | null

schedules.updated

string | null

required

schedules.active

boolean

default:

true

Whether or not the schedule is active.

schedules.deployment_id

string | null

The deployment id associated with this schedule.

schedules.max_scheduled_runs

integer | null

The maximum number of scheduled runs for the schedule.

Required range: x > 0

schedules.parameters

object

A dictionary of parameter value overrides.

status

enum<string> | null

default:

NOT_READY

Whether the deployment is ready to run flows.

Available options:

READY,

NOT_READY

storage_document_id

string | null

The block document defining storage used for this flow.

tags

string[]

A list of tags for the deployment

updated_by

object | null

Optional information about the updater of this deployment.

Show child attributes

updated_by.display_value

string | null

The display value for the updater.

updated_by.id

string | null

The id of the updater of the object.

updated_by.type

string | null

The type of the updater of the object.

version

string | null

An optional version for the deployment.

work_pool_name

string | null

The name of the deployment's work pool.

work_queue_name

string | null

The work queue for the deployment. If no work queue is set, work will not be scheduled.