OpenAPI Specification
openapi: 3.1.0
info:
title: Prefect Cloud Account Billing Workspaces API
description: Prefect Cloud REST API documentation.
version: 0.8.4
tags:
- name: Workspaces
description: Interact with Prefect Cloud Workspaces.
externalDocs:
description: 'Manage workspaces: control access'
url: https://docs.prefect.io/v3/manage/cloud/workspaces#control-access
paths:
/api/accounts/{account_id}/workspaces/:
post:
tags:
- Workspaces
summary: Create Workspace
description: 'Create a Workspace
Required account permissions: `create:workspace`'
operationId: create_workspace_api_accounts__account_id__workspaces__post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Workspace'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}:
get:
tags:
- Workspaces
summary: Read Workspace
description: 'Get a workspace by id.
Required account permissions: `read:workspace`'
operationId: read_workspace_api_accounts__account_id__workspaces__workspace_id__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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Workspace'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Workspaces
summary: Update Workspace
description: 'Update a workspace by id.
Required workspace scopes: `write_workspace_settings`'
operationId: update_workspace_api_accounts__account_id__workspaces__workspace_id__patch
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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceUpdate'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Workspaces
summary: Delete Workspace
description: 'Delete a workspace by id.
Required workspace scopes: `manage_workspace_settings`'
operationId: delete_workspace_api_accounts__account_id__workspaces__workspace_id__delete
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
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/managed_execution/details:
get:
tags:
- Workspaces
summary: Read Managed Execution Details
description: "Retrieves information about the managed execution usage and terms for a given workspace.\nThis includes the total compute time in seconds utilized by the workspace during the current billing period,\nas well as limits pertaining to the account terms, such as concurrency, work pool, and compute limits.\n\nReturns:\n WorkspaceLimitsUsageResponse: An object containing the compute usage in seconds and limits on\n concurrency, work pool, and compute usage for the specified workspace.\n\nRequired account permissions: `read:workspace`"
operationId: read_managed_execution_details_api_accounts__account_id__workspaces__workspace_id__managed_execution_details_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
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/filter:
post:
tags:
- Workspaces
summary: Read Workspaces
description: 'Query for workspaces.
Required account permissions: `read:workspace`'
operationId: read_workspaces_api_accounts__account_id__workspaces_filter_post
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
title: Account Id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_read_workspaces_api_accounts__account_id__workspaces_filter_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Workspace'
title: Response Read Workspaces Api Accounts Account Id Workspaces Filter Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/transfer:
post:
tags:
- Workspaces
summary: Transfer Workspace
description: 'Transfer a workspace to a new account
Required account permissions: `delete:workspace`'
operationId: transfer_workspace_api_accounts__account_id__workspaces__workspace_id__transfer_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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_transfer_workspace_api_accounts__account_id__workspaces__workspace_id__transfer_post'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/accounts/{account_id}/workspaces/{workspace_id}/validate_transfer:
post:
tags:
- Workspaces
summary: Validate Transfer Workspace
description: 'Validate transfer of a workspace to a new account, returning any validation errors
Required account permissions: `delete:workspace`'
operationId: validate_transfer_workspace_api_accounts__account_id__workspaces__workspace_id__validate_transfer_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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_validate_transfer_workspace_api_accounts__account_id__workspaces__workspace_id__validate_transfer_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
type: object
additionalProperties:
type: string
title: Response Validate Transfer Workspace Api Accounts Account Id Workspaces Workspace Id Validate Transfer Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/workspaces/{workspace_id}:
get:
tags:
- Workspaces
summary: Find Workspace Without Account Id
description: Redirects to the full account-scoped URL of a workspace
operationId: find_workspace_without_account_id_api_workspaces__workspace_id__get
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
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}/settings:
get:
tags:
- Workspaces
summary: Read Workspace Settings
description: 'Read a workspace''s settings by id.
Required workspace scopes: `see_workspace_settings`'
operationId: read_workspace_settings_api_accounts__account_id__workspaces__workspace_id__settings_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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceSettings'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Workspaces
summary: Update Workspace Settings
description: 'Update a workspace''s settings by id.
Required workspace scopes: `write_workspace_settings`'
operationId: update_workspace_settings_api_accounts__account_id__workspaces__workspace_id__settings_patch
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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceSettingsUpdate'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Body_read_workspaces_api_accounts__account_id__workspaces_filter_post:
properties:
limit:
type: integer
maximum: 200.0
minimum: 0.0
title: Limit
default: 200
offset:
type: integer
minimum: 0.0
title: Offset
default: 0
workspaces:
anyOf:
- $ref: '#/components/schemas/WorkspaceFilter'
- type: 'null'
type: object
title: Body_read_workspaces_api_accounts__account_id__workspaces_filter_post
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
WorkspaceFilter:
properties:
id:
anyOf:
- $ref: '#/components/schemas/WorkspaceFilterId'
- type: 'null'
description: Filter criteria for Workspace.id
handle:
anyOf:
- $ref: '#/components/schemas/WorkspaceFilterHandle'
- type: 'null'
description: Filter criteria for Workspace.handle
additionalProperties: false
type: object
title: WorkspaceFilter
Body_transfer_workspace_api_accounts__account_id__workspaces__workspace_id__transfer_post:
properties:
to_account_id:
type: string
format: uuid
title: To Account Id
new_handle:
type: string
title: New Handle
type: object
required:
- to_account_id
title: Body_transfer_workspace_api_accounts__account_id__workspaces__workspace_id__transfer_post
WorkspaceFilterId:
properties:
any_:
anyOf:
- items:
type: string
format: uuid
type: array
- type: 'null'
title: Any
description: Only include workspaces matching these ids
additionalProperties: false
type: object
title: WorkspaceFilterId
WorkspaceCreate:
properties:
name:
type: string
maxLength: 5000
title: Name
description: The workspace name
description:
anyOf:
- type: string
maxLength: 5000
- type: 'null'
title: Description
description: A description of the workspace
default: ''
handle:
type: string
maxLength: 5000
title: Handle
description: A unique handle for the workspace
additionalProperties: false
type: object
required:
- name
- handle
title: WorkspaceCreate
description: Data used by the api to create a workspace
WorkspaceUpdate:
properties:
name:
anyOf:
- type: string
maxLength: 5000
- type: 'null'
title: Name
description: The workspace name
handle:
anyOf:
- type: string
maxLength: 5000
- type: 'null'
title: Handle
description: A unique handle for the workspace
description:
anyOf:
- type: string
maxLength: 5000
- type: 'null'
title: Description
description: A description of the workspace
default: ''
default_workspace_role_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Default Workspace Role Id
description: The default workspace role id.
additionalProperties: false
type: object
title: WorkspaceUpdate
description: Data used by the api to update a workspace
Workspace:
properties:
id:
type: string
format: uuid
title: Id
created:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created
updated:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated
account_id:
type: string
format: uuid
title: Account Id
description: The account id
name:
type: string
title: Name
description: The workspace name
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: A description of the workspace
default: ''
handle:
type: string
title: Handle
description: A unique handle for the workspace
default_workspace_role_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Default Workspace Role Id
description: The default workspace role id.
is_public:
type: boolean
title: Is Public
description: Whether the workspace is public.
default: false
type: object
required:
- account_id
- name
- handle
title: Workspace
description: An ORM representation of a Workspace
WorkspaceFilterHandle:
properties:
any_:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Any
description: Only include workspaces matching these handles
additionalProperties: false
type: object
title: WorkspaceFilterHandle
WorkspaceSettingsUpdate:
properties:
inherit_default_result_storage:
anyOf:
- type: boolean
- type: 'null'
title: Inherit Default Result Storage
description: Whether the workspace should inherit its default result storage from the account.
default_result_storage_block_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Default Result Storage Block Id
description: The block document ID of the workspace's default result storage block.
additionalProperties: false
type: object
title: WorkspaceSettingsUpdate
description: Data used by API to update workspace settings
WorkspaceSettings:
properties:
inherit_default_result_storage:
type: boolean
title: Inherit Default Result Storage
description: Whether the workspace should inherit its default result storage from the account.
default: true
default_result_storage_block_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Default Result Storage Block Id
description: The block document ID of the workspace's default result storage block.
type: object
title: WorkspaceSettings
Body_validate_transfer_workspace_api_accounts__account_id__workspaces__workspace_id__validate_transfer_post:
properties:
to_account_id:
type: string
format: uuid
title: To Account Id
new_handle:
type: string
title: New Handle
type: object
required:
- to_account_id
title: Body_validate_transfer_workspace_api_accounts__account_id__workspaces__workspace_id__validate_transfer_post