Create a virtual data plane

curl --request POST \
  --url https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "cluster_id": "<string>",
  "dataplane_creator": "jsmith@example.com"
}
'

import requests

url = "https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes"

payload = {
    "name": "<string>",
    "cluster_id": "<string>",
    "dataplane_creator": "jsmith@example.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    cluster_id: '<string>',
    dataplane_creator: 'jsmith@example.com'
  })
};

fetch('https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'cluster_id' => '<string>',
    'dataplane_creator' => 'jsmith@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"cluster_id\": \"<string>\",\n  \"dataplane_creator\": \"jsmith@example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"cluster_id\": \"<string>\",\n  \"dataplane_creator\": \"jsmith@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"cluster_id\": \"<string>\",\n  \"dataplane_creator\": \"jsmith@example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "cluster_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

Virtual Dataplanes

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.

POST

orgs

{org_id}

virtual_dataplanes

Create a virtual data plane

curl --request POST \
  --url https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "cluster_id": "<string>",
  "dataplane_creator": "jsmith@example.com"
}
'

import requests

url = "https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes"

payload = {
    "name": "<string>",
    "cluster_id": "<string>",
    "dataplane_creator": "jsmith@example.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    cluster_id: '<string>',
    dataplane_creator: 'jsmith@example.com'
  })
};

fetch('https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'cluster_id' => '<string>',
    'dataplane_creator' => 'jsmith@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"cluster_id\": \"<string>\",\n  \"dataplane_creator\": \"jsmith@example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"cluster_id\": \"<string>\",\n  \"dataplane_creator\": \"jsmith@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cp.us.honeyhive.ai/v1/orgs/{org_id}/virtual_dataplanes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"cluster_id\": \"<string>\",\n  \"dataplane_creator\": \"jsmith@example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "cluster_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

org_id

string

required

The unique identifier of the organization the virtual data plane is created in

Body

application/json

Request body for creating a virtual dataplane

name

string

required

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.

Maximum string length: 200

cluster_id

string

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.

Minimum string length: 1

dataplane_creator

string<email>

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.

Response

Virtual data plane created successfully

The created virtual dataplane

success

boolean

required

data

object

required

Virtual dataplane object

Show child attributes

Data Plane API

Control Plane API

Create a virtual data plane

Authorizations

Path Parameters

Body

Response