> ## 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 virtual data plane > Create a virtual data plane in an organization. The parent organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. Your organization's id is listed on the API keys page of your organization settings in the HoneyHive app. A virtual data plane is a logical tenant boundary hosted on a physical cluster, and several of them commonly share one cluster. Workspaces are created inside it. `cluster_id` is optional, and omitting it is the common case: the new virtual data plane is placed on the same cluster as the organization's existing ones. Two situations require it explicitly, and both return a 400 that says so rather than guessing: an organization whose existing virtual data planes span more than one cluster, and an organization that has none yet. Every response includes `cluster_id`, so reading an existing virtual data plane tells you which value to send. A cluster admits an organization only if your control plane administrator configured it to, so a `cluster_id` you can read from a sibling virtual data plane is not necessarily one you may place a new virtual data plane on. A cluster that does not admit this organization returns a 403. When you named the cluster, the fix is a configuration change your administrator makes. When this endpoint inferred the cluster, send an explicit `cluster_id` to place the virtual data plane on another cluster. Deployments differ in who places virtual data planes. Where HoneyHive assigns them to organizations automatically, this endpoint returns a 403 for every request and the placement is not yours to make. Deployments whose administrators own the scope tree are the ones this endpoint serves. The optional `dataplane_creator` field names the user (by email) who receives the dataplane-creator membership on the new virtual data plane. The named user must already be a member of the organization. When omitted, it 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 dataplane 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 `dataplane_creator` who is already signed in does not see the new virtual data plane immediately. A session captures its scope tree and permission grants when it is created, so a membership granted afterwards is not reflected in it; the refresh takes effect on their next request to the control plane. ## OpenAPI ````yaml https://raw.githubusercontent.com/honeyhiveai/honeyhive-openapi/main/control_plane_openapi.yaml post /v1/orgs/{org_id}/virtual_dataplanes 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/orgs/{org_id}/virtual_dataplanes: post: tags: - Virtual Dataplanes summary: Create a virtual data plane description: > Create a virtual data plane in an organization. The parent organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. Your organization's id is listed on the API keys page of your organization settings in the HoneyHive app. A virtual data plane is a logical tenant boundary hosted on a physical cluster, and several of them commonly share one cluster. Workspaces are created inside it. `cluster_id` is optional, and omitting it is the common case: the new virtual data plane is placed on the same cluster as the organization's existing ones. Two situations require it explicitly, and both return a 400 that says so rather than guessing: an organization whose existing virtual data planes span more than one cluster, and an organization that has none yet. Every response includes `cluster_id`, so reading an existing virtual data plane tells you which value to send. A cluster admits an organization only if your control plane administrator configured it to, so a `cluster_id` you can read from a sibling virtual data plane is not necessarily one you may place a new virtual data plane on. A cluster that does not admit this organization returns a 403. When you named the cluster, the fix is a configuration change your administrator makes. When this endpoint inferred the cluster, send an explicit `cluster_id` to place the virtual data plane on another cluster. Deployments differ in who places virtual data planes. Where HoneyHive assigns them to organizations automatically, this endpoint returns a 403 for every request and the placement is not yours to make. Deployments whose administrators own the scope tree are the ones this endpoint serves. The optional `dataplane_creator` field names the user (by email) who receives the dataplane-creator membership on the new virtual data plane. The named user must already be a member of the organization. When omitted, it 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 dataplane 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 `dataplane_creator` who is already signed in does not see the new virtual data plane immediately. A session captures its scope tree and permission grants when it is created, so a membership granted afterwards is not reflected in it; the refresh takes effect on their next request to the control plane. operationId: createVirtualDataplane parameters: - in: path name: org_id required: true schema: type: string description: >- The unique identifier of the organization the virtual data plane is created in requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostVirtualDataplaneRequest' responses: '200': description: Virtual data plane created successfully content: application/json: schema: $ref: '#/components/schemas/CreateVirtualDataplaneResponse' '400': description: >- Invalid request body, an unknown or ineligible `dataplane_creator`, `cluster_id` omitted when it could not be inferred, or the named cluster is disabled '403': description: >- The caller may not create a virtual data plane here: the permission is missing at this organization, the API key's root scope does not contain it, this deployment assigns virtual data planes automatically, or the cluster (named or inferred) does not admit this organization '404': description: Organization or cluster not found components: schemas: PostVirtualDataplaneRequest: type: object properties: name: type: string maxLength: 200 description: >- Virtual dataplane 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. cluster_id: type: string minLength: 1 description: >- Physical cluster to host this virtual dataplane. Omit to place it alongside the existing virtual dataplanes in this org; required when the org has none yet, or when its virtual dataplanes span more than one cluster. dataplane_creator: type: string format: email description: >- Email of the user to grant the dataplane-creator membership to (API key actors only). A signed-in user does not see the new dataplane until their session refreshes, which happens on their next request to the control plane. required: - name additionalProperties: false description: Request body for creating a virtual dataplane CreateVirtualDataplaneResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/VirtualDataplaneItem' required: - success - data additionalProperties: false description: The created virtual dataplane VirtualDataplaneItem: type: object properties: id: type: string name: type: string description: Virtual dataplane display name cluster_id: type: string description: Identifier of the physical cluster hosting this dataplane created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string required: - id - name - cluster_id - created_at - updated_at additionalProperties: false description: Virtual dataplane object securitySchemes: BearerAuth: type: http scheme: bearer ```` ## Related topics - [Virtual Dataplanes](/v2/cli-reference/ref/virtual-dataplanes.md) - [Virtual Dataplanes Methods](/v2/control-plane-sdk-reference/typescript/ref/virtual-dataplanes/index.md) - [Delete a virtual data plane](/v2/control-plane-api-reference-autogen/virtual-dataplanes/delete-a-virtual-data-plane.md)