Prefect Deployments API
Interact with a Workspace's Deployments.
OpenAPI Specification
openapi: 3.1.0
info:
title: Prefect Cloud Account Billing Deployments API
description: Prefect Cloud REST API documentation.
version: 0.8.4
tags:
- name: Deployments
description: Interact with a Workspace's Deployments.
externalDocs:
description: Deployment overview
url: https://docs.prefect.io/v3/deploy/index
paths:
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/:
post:
tags:
- Deployments
summary: Create Deployment
description: '
Required workspace scopes: `write_deployments`'
operationId: create_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentCreate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/branch:
post:
tags:
- Deployments
summary: Branch From Deployment
description: '
Required workspace scopes: `write_deployments`'
operationId: branch_from_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__branch_post
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentBranch'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}:
patch:
tags:
- Deployments
summary: Update Deployment
description: '
Required workspace scopes: `write_deployments`'
operationId: update_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__patch
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentUpdate'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Deployments
summary: Read Deployment
description: 'Get a deployment by id.
Required workspace scopes: `see_deployments`'
operationId: read_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Deployments
summary: Delete Deployment
description: 'Delete a deployment by id.
Required workspace scopes: `manage_deployments`'
operationId: delete_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__delete
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/name/{flow_name}/{deployment_name}:
get:
tags:
- Deployments
summary: Read Deployment By Name
description: 'Get a deployment using the name of the flow and the deployment.
Required workspace scopes: `see_deployments`'
operationId: read_deployment_by_name_api_accounts__account_id__workspaces__workspace_id__deployments_name__flow_name___deployment_name__get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: flow_name
in: path
required: true
schema:
type: string
description: The name of the flow
title: Flow Name
description: The name of the flow
- name: deployment_name
in: path
required: true
schema:
type: string
description: The name of the deployment
title: Deployment Name
description: The name of the deployment
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/filter:
post:
tags:
- Deployments
summary: Read Deployments
description: '
Required workspace scopes: `see_deployments`'
operationId: read_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_filter_post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_read_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DeploymentResponse'
title: Response Read Deployments Api Accounts Account Id Workspaces Workspace Id Deployments Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/paginate:
post:
tags:
- Deployments
summary: Paginate Deployments
description: 'Pagination query for deployments.
Required workspace scopes: `see_deployments`'
operationId: paginate_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_paginate_post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_paginate_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_paginate_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentPaginationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/get_scheduled_flow_runs:
post:
tags:
- Deployments
summary: Get Scheduled Flow Runs For Deployments
description: 'Get scheduled runs for a set of deployments. Used by a runner to poll for work.
Required workspace scopes: `see_deployments`'
operationId: get_scheduled_flow_runs_for_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_get_scheduled_flow_runs_post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_get_scheduled_flow_runs_for_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_get_scheduled_flow_runs_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlowRunResponse'
title: Response Get Scheduled Flow Runs For Deployments Api Accounts Account Id Workspaces Workspace Id Deployments Get Scheduled Flow Runs Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/count:
post:
tags:
- Deployments
summary: Count Deployments
description: 'Count deployments.
Required workspace scopes: `see_deployments`'
operationId: count_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_count_post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_count_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_count_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: integer
title: Response Count Deployments Api Accounts Account Id Workspaces Workspace Id Deployments Count Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/bulk_delete:
post:
tags:
- Deployments
summary: Bulk Delete Deployments
description: 'Bulk delete deployments using a filter.
This endpoint deletes deployments matching the provided filter criteria.
Deployments are deleted immediately so they disappear from the UI.
Associated automations are cleaned up asynchronously in the background.
If ANY deployment in the filter is unauthorized, the entire request fails
and nothing is deleted.
Required workspace scopes: `manage_deployments`'
operationId: bulk_delete_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_bulk_delete_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_bulk_delete_deployments_api_accounts__account_id__workspaces__workspace_id__deployments_bulk_delete_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkDeleteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/schedule:
post:
tags:
- Deployments
summary: Schedule Deployment
description: "Schedule runs for a deployment. For backfills, provide start/end times in the past.\n\nThis function will generate the minimum number of runs that satisfy the min\nand max times, and the min and max counts. Specifically, the following order\nwill be respected.\n\n - Runs will be generated starting on or after the `start_time`\n - No more than `max_runs` runs will be generated\n - No runs will be generated after `end_time` is reached\n - At least `min_runs` runs will be generated\n - Runs will be generated until at least `start_time + min_time` is reached\n\nRequired workspace scopes: `write_deployments`"
operationId: schedule_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__schedule_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_schedule_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__schedule_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/resume_deployment:
post:
tags:
- Deployments
summary: Resume Deployment
description: 'Resume the deployment. Runs will be scheduled immediately.
Required workspace scopes: `write_deployments`'
operationId: resume_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__resume_deployment_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/set_schedule_active:
post:
tags:
- Deployments
summary: Resume Deployment
description: 'Resume the deployment. Runs will be scheduled immediately.
Required workspace scopes: `write_deployments`'
operationId: resume_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__set_schedule_active_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/pause_deployment:
post:
tags:
- Deployments
summary: Pause Deployment
description: 'Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled
state will be deleted.
Required workspace scopes: `write_deployments`'
operationId: pause_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__pause_deployment_post
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/set_schedule_inactive:
post:
tags:
- Deployments
summary: Pause Deployment
description: 'Set a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled
state will be deleted.
Required workspace scopes: `write_deployments`'
operationId: pause_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__set_schedule_inactive_post
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/create_flow_run:
post:
tags:
- Deployments
summary: Create Flow Run From Deployment
description: 'Create a flow run from a deployment.
Any parameters not provided will be inferred from the deployment''s parameters.
If tags are not provided, the deployment''s tags will be used.
If no state is provided, the flow run will be created in a SCHEDULED state with
a scheduled start time of NOW.
Required workspace scopes: `run_deployments`'
operationId: create_flow_run_from_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__create_flow_run_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentFlowRunCreate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FlowRunResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/create_flow_run/bulk:
post:
tags:
- Deployments
summary: Bulk Create Flow Runs From Deployment
description: 'Create multiple flow runs from a deployment in a single request.
Each item in the list uses the same schema as the single create endpoint.
Results are returned in the same order as the input list.
Required workspace scopes: `run_deployments`'
operationId: bulk_create_flow_runs_from_deployment_api_accounts__account_id__workspaces__workspace_id__deployments__id__create_flow_run_bulk_post
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DeploymentFlowRunCreate'
maxItems: 100
description: List of flow runs to create
title: Flow Runs
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FlowRunBulkCreateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/deployments/{id}/access:
get:
tags:
- Deployments
summary: Read Deployment Access
description: 'Read access controls for a deployment.
Required workspace scopes: `see_deployments`'
operationId: read_deployment_access_api_accounts__account_id__workspaces__workspace_id__deployments__id__access_get
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentAccessControl'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Deployments
summary: Set Deployment Access
description: 'Set access controls for a deployment.
The given access controls will replace any existing access controls.
Required workspace scopes: `manage_deployments`'
operationId: set_deployment_access_api_accounts__account_id__workspaces__workspace_id__deployments__id__access_put
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: The deployment id
title: Id
description: The deployment id
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
- name: x-prefect-api-version
in: header
required: false
schema:
type: string
title: X-Prefect-Api-Version
requestBody:
required: true
c
# --- truncated at 32 KB (202 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prefect/refs/heads/main/openapi/prefect-deployments-api-openapi.yml