curl --request POST \
--url https://api.pinecone.io/workspaces \
--header 'Api-Key: <api-key>' \
--header 'Content-Type: application/json' \
--header 'X-Pinecone-Api-Version: <x-pinecone-api-version>' \
--data '
{
"name": "production",
"spec": {
"byoc": {
"environment": "aws-us-east-1-b921.byoc"
}
}
}
'import requests
url = "https://api.pinecone.io/workspaces"
payload = {
"name": "production",
"spec": { "byoc": { "environment": "aws-us-east-1-b921.byoc" } }
}
headers = {
"X-Pinecone-Api-Version": "<x-pinecone-api-version>",
"Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Pinecone-Api-Version': '<x-pinecone-api-version>',
'Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({name: 'production', spec: {byoc: {environment: 'aws-us-east-1-b921.byoc'}}})
};
fetch('https://api.pinecone.io/workspaces', 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.pinecone.io/workspaces",
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' => 'production',
'spec' => [
'byoc' => [
'environment' => 'aws-us-east-1-b921.byoc'
]
]
]),
CURLOPT_HTTPHEADER => [
"Api-Key: <api-key>",
"Content-Type: application/json",
"X-Pinecone-Api-Version: <x-pinecone-api-version>"
],
]);
$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.pinecone.io/workspaces"
payload := strings.NewReader("{\n \"name\": \"production\",\n \"spec\": {\n \"byoc\": {\n \"environment\": \"aws-us-east-1-b921.byoc\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
req.Header.Add("Api-Key", "<api-key>")
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.pinecone.io/workspaces")
.header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
.header("Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"production\",\n \"spec\": {\n \"byoc\": {\n \"environment\": \"aws-us-east-1-b921.byoc\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pinecone.io/workspaces")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'
request["Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"production\",\n \"spec\": {\n \"byoc\": {\n \"environment\": \"aws-us-east-1-b921.byoc\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2026-06-01T00:00:00.000Z",
"host": "production-c01b5b5.wksp.aws-us-east-1-b921.byoc.pinecone.io",
"name": "production",
"spec": {
"byoc": {
"environment": "aws-us-east-1-b921.byoc"
}
},
"status": {
"ready": false,
"state": "Initializing"
},
"updated_at": "2026-06-01T00:00:00.000Z"
}Create a workspace
Create a Nexus workspace. The workspace name must be unique within the project.
Workspaces are created asynchronously. On success the workspace is returned in the Initializing state with ready set to false. Poll Describe workspace until the workspace reaches the Ready state before using it.
curl --request POST \
--url https://api.pinecone.io/workspaces \
--header 'Api-Key: <api-key>' \
--header 'Content-Type: application/json' \
--header 'X-Pinecone-Api-Version: <x-pinecone-api-version>' \
--data '
{
"name": "production",
"spec": {
"byoc": {
"environment": "aws-us-east-1-b921.byoc"
}
}
}
'import requests
url = "https://api.pinecone.io/workspaces"
payload = {
"name": "production",
"spec": { "byoc": { "environment": "aws-us-east-1-b921.byoc" } }
}
headers = {
"X-Pinecone-Api-Version": "<x-pinecone-api-version>",
"Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Pinecone-Api-Version': '<x-pinecone-api-version>',
'Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({name: 'production', spec: {byoc: {environment: 'aws-us-east-1-b921.byoc'}}})
};
fetch('https://api.pinecone.io/workspaces', 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.pinecone.io/workspaces",
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' => 'production',
'spec' => [
'byoc' => [
'environment' => 'aws-us-east-1-b921.byoc'
]
]
]),
CURLOPT_HTTPHEADER => [
"Api-Key: <api-key>",
"Content-Type: application/json",
"X-Pinecone-Api-Version: <x-pinecone-api-version>"
],
]);
$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.pinecone.io/workspaces"
payload := strings.NewReader("{\n \"name\": \"production\",\n \"spec\": {\n \"byoc\": {\n \"environment\": \"aws-us-east-1-b921.byoc\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
req.Header.Add("Api-Key", "<api-key>")
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.pinecone.io/workspaces")
.header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
.header("Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"production\",\n \"spec\": {\n \"byoc\": {\n \"environment\": \"aws-us-east-1-b921.byoc\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pinecone.io/workspaces")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'
request["Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"production\",\n \"spec\": {\n \"byoc\": {\n \"environment\": \"aws-us-east-1-b921.byoc\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2026-06-01T00:00:00.000Z",
"host": "production-c01b5b5.wksp.aws-us-east-1-b921.byoc.pinecone.io",
"name": "production",
"spec": {
"byoc": {
"environment": "aws-us-east-1-b921.byoc"
}
},
"status": {
"ready": false,
"state": "Initializing"
},
"updated_at": "2026-06-01T00:00:00.000Z"
}Authorizations
Headers
Required date-based version header
Body
The desired configuration for the workspace.
The configuration needed to create a workspace.
The name of the workspace. Resource name must be 1-45 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or '-'.
1 - 45"example-workspace"
The spec object defines the environment in which the workspace's contexts are created. Workspaces are created in a customer-managed BYOC (Bring Your Own Cloud) environment.
Show child attributes
Show child attributes
Response
The workspace create request has been accepted. The workspace is being provisioned asynchronously and starts in the Initializing state.
Describes a workspace, a project-scoped grouping of contexts.
The name of the workspace. Resource name must be 1-45 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or '-'.
1 - 45"example-workspace"
The spec object defines the environment in which the workspace's contexts are created. Workspaces are created in a customer-managed BYOC (Bring Your Own Cloud) environment.
Show child attributes
Show child attributes
The URL address where the workspace is hosted.
"production-c01b5b5.wksp.prod.pinecone.io"
The date and time the workspace was created.
"2026-06-21T00:00:00.000Z"
The date and time the workspace was last updated.
"2026-06-21T00:00:00.000Z"
The current status of the workspace.
Show child attributes
Show child attributes
{ "ready": true, "state": "Ready" }
Was this page helpful?