> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a workspace > Create a workspace in a virtual data plane. The parent virtual data plane is identified by the `virtual_dataplane_id` path parameter alone; the `x-hh-dataplane-id` header does not participate. Your organization's virtual data plane ids are listed on the API keys page of your organization settings in the HoneyHive app. Most organizations have exactly one. The new workspace contains no projects. Create one with `POST /v1/workspaces/{workspace_id}/projects` if you need it, because a workspace with no projects has nowhere to log events. The optional `workspace_creator` field names the user (by email) who receives the workspace-creator membership on the new workspace. The named user must already be a member of the virtual data plane. When omitted, the workspace is created without any membership. The field is only accepted on API-key-initiated requests. User-initiated creation always makes the calling user the creator, so sending the field returns a 400. The roles that membership carries come from your organization's role configuration. An organization that grants no role on workspace creation is a supported case: the request still succeeds and the named user receives no access. A 200 response is not by itself confirmation that the named user was granted anything. A `workspace_creator` who is already signed in does not see the new workspace immediately. A session captures its scope tree and permission grants when it is created, so a membership granted afterwards is not reflected in it. Creating the workspace marks that user's sessions for refresh, and the refresh takes effect on their next request to the control plane, so an idle browser tab may need a page reload. ## OpenAPI ````yaml https://raw.githubusercontent.com/honeyhiveai/honeyhive-openapi/main/control_plane_openapi.yaml post /v1/virtual_dataplanes/{virtual_dataplane_id}/workspaces openapi: 3.1.0 info: title: HoneyHive Control Plane API description: > Manage HoneyHive control-plane resources: workspaces, projects and alerts. Authentication requires a fine-grained control-plane API key (values start with `hh_fgcp_`), sent as `Authorization: Bearer `. Project API keys used with the Data Plane API will not work here. Create a key in the HoneyHive app under an organization's or workspace's **Settings → API Keys**, or see [Authorization](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript#authorization) for details. license: name: MIT url: https://opensource.org/licenses/MIT version: 1.9.0 servers: - url: https://api.cp.us.honeyhive.ai security: - BearerAuth: [] tags: - name: Alerts description: > Define and manage alerts. Alerts evaluate event metrics on a schedule and trigger notifications when configured thresholds are crossed. - name: Projects description: > Create and manage projects within a workspace. A project is the container for the events, datasets, evaluations, and alerts logged against it. - name: Virtual Dataplanes description: > Create and manage virtual data planes. A virtual data plane is a logical tenant boundary inside an organization, hosted on a physical cluster; several virtual data planes commonly share one cluster. Workspaces live inside a virtual data plane. - name: Workspaces description: > Read and manage workspaces. A workspace groups the projects belonging to one team or environment, and owns the API keys and AI provider secrets its projects share. paths: /v1/virtual_dataplanes/{virtual_dataplane_id}/workspaces: post: tags: - Workspaces summary: Create a workspace description: > Create a workspace in a virtual data plane. The parent virtual data plane is identified by the `virtual_dataplane_id` path parameter alone; the `x-hh-dataplane-id` header does not participate. Your organization's virtual data plane ids are listed on the API keys page of your organization settings in the HoneyHive app. Most organizations have exactly one. The new workspace contains no projects. Create one with `POST /v1/workspaces/{workspace_id}/projects` if you need it, because a workspace with no projects has nowhere to log events. The optional `workspace_creator` field names the user (by email) who receives the workspace-creator membership on the new workspace. The named user must already be a member of the virtual data plane. When omitted, the workspace is created without any membership. The field is only accepted on API-key-initiated requests. User-initiated creation always makes the calling user the creator, so sending the field returns a 400. The roles that membership carries come from your organization's role configuration. An organization that grants no role on workspace creation is a supported case: the request still succeeds and the named user receives no access. A 200 response is not by itself confirmation that the named user was granted anything. A `workspace_creator` who is already signed in does not see the new workspace immediately. A session captures its scope tree and permission grants when it is created, so a membership granted afterwards is not reflected in it. Creating the workspace marks that user's sessions for refresh, and the refresh takes effect on their next request to the control plane, so an idle browser tab may need a page reload. operationId: createWorkspace parameters: - in: path name: virtual_dataplane_id required: true schema: type: string description: >- The unique identifier of the virtual data plane the workspace is created in requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostWorkspaceRequest' responses: '200': description: Workspace created successfully content: application/json: schema: $ref: '#/components/schemas/CreateWorkspaceResponse' '400': description: Invalid request body, or an unknown/ineligible `workspace_creator` '404': description: Virtual data plane not found components: schemas: PostWorkspaceRequest: type: object properties: name: type: string maxLength: 200 description: >- Workspace display name. Allowed characters are letters, digits, space, underscore, hyphen, apostrophe and ampersand. The name must contain at least one letter or digit, and must not start with a space. description: type: string description: Workspace description workspace_creator: type: string format: email description: >- Email of the user to grant the workspace-creator membership to (API key actors only). A signed-in user does not see the new workspace until their session refreshes, which happens on their next request to the control plane. required: - name additionalProperties: false description: Request body for creating a workspace CreateWorkspaceResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/WorkspaceItem' required: - success - data additionalProperties: false description: The created workspace WorkspaceItem: type: object properties: id: type: string name: type: string description: Workspace display name description: type: string description: Workspace description created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string - type: 'null' required: - id - name - description - created_at additionalProperties: false description: Workspace object securitySchemes: BearerAuth: type: http scheme: bearer ```` ## Related topics - [Workspaces](/v2/cli-reference/ref/workspaces.md) - [Workspaces Methods](/v2/control-plane-sdk-reference/typescript/ref/workspaces/index.md) - [CreateWorkspaceRequest](/v2/control-plane-sdk-reference/typescript/ref/workspaces/CreateWorkspaceRequest.md)