# Create a workspace

Workspaces are created asynchronously. On success the workspace is returned in the `Initializing` state with `ready` set to `false`. Poll [Describe workspace](#operation/describe_workspace) until the workspace reaches the `Ready` state before using it.

`POST /workspaces`

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://api.pinecone.io/workspaces \
  --header 'Api-Key: <api-key>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "production",
  "spec": {
    "byoc": {
      "environment": "aws-us-east-1-b921.byoc"
    }
  }
}'
```

```python title="Python"
import requests

url = "https://api.pinecone.io/workspaces"

payload = {
  "name": "production",
  "spec": {
    "byoc": {
      "environment": "aws-us-east-1-b921.byoc"
    }
  }
}
headers = {
    "Api-Key": "<api-key>",
    "X-Pinecone-Api-Version": "<x-pinecone-api-version>",
    "Content-Type": "application/json"
}

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

print(response.text)
```

```javascript title="JavaScript"
const options = {method: "POST", headers: {"Api-Key": "<api-key>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>", "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 title="PHP"
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pinecone.io/workspaces",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"name\":\"production\",\"spec\":{\"byoc\":{\"environment\":\"aws-us-east-1-b921.byoc\"}}}",
  CURLOPT_HTTPHEADER => [
    "Api-Key: <api-key>",
    "X-Pinecone-Api-Version: <x-pinecone-api-version>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

```go title="Go"
package main

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

func main() {

	url := "https://api.pinecone.io/workspaces"

	payload := strings.NewReader("{\"name\":\"production\",\"spec\":{\"byoc\":{\"environment\":\"aws-us-east-1-b921.byoc\"}}}")

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

	req.Header.Add("Api-Key", "<api-key>")
	req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
	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))

}
```

```java title="Java"
HttpResponse<String> response = Unirest.post("https://api.pinecone.io/workspaces")
  .header("Api-Key", "<api-key>")
  .header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
  .header("Content-Type", "application/json")
  .body("{\"name\":\"production\",\"spec\":{\"byoc\":{\"environment\":\"aws-us-east-1-b921.byoc\"}}}")
  .asString();
```

```ruby title="Ruby"
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["Api-Key"] = '<api-key>'
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\"name\":\"production\",\"spec\":{\"byoc\":{\"environment\":\"aws-us-east-1-b921.byoc\"}}}"

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

:::code-group
```json title="201"
{
  "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"
}
```

```json title="400"
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Workspace name must be 1-45 characters, contain only lowercase alphanumeric characters or '-', and start and end with an alphanumeric character."
  },
  "status": 400
}
```

```json title="401"
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}
```

```json title="403"
{
  "error": {
    "code": "FORBIDDEN",
    "message": "This project has reached its workspace limit. Delete an existing workspace or contact support to raise the limit."
  },
  "status": 403
}
```

```json title="409"
{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A workspace named 'production' already exists in this project. Choose a different name."
  },
  "status": 409
}
```

```json title="422"
{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Failed to deserialize the JSON body into the target type: missing field `spec` at line 1 column 20"
  },
  "status": 422
}
```

```json title="500"
{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - |  |

An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/).

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-07` | Required date-based version header |

#### Body

The desired configuration for the workspace.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | - | 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 '-'. Required string length: 1 - 45. Example: example-workspace |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `object` | - | 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. |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `byoc` | `object` | - | Configuration needed to create a workspace in a BYOC (Bring Your Own Cloud) environment. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `environment` | `string` | - | The BYOC environment where the workspace's contexts are hosted. Example: aws-us-east-1-b921.byoc |
:::
::::

#### Response

`201` — 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.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | - | 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 '-'. Required string length: 1 - 45. Example: example-workspace |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `object` | - | 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. |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `byoc` | `object` | - | Configuration needed to create a workspace in a BYOC (Bring Your Own Cloud) environment. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `environment` | `string` | - | The BYOC environment where the workspace's contexts are hosted. Example: aws-us-east-1-b921.byoc |
:::
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `host` | `string` | - | The URL address where the workspace is hosted. Example: production-c01b5b5.wksp.prod.pinecone.io |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | - | The date and time the workspace was created. Example: 2026-06-21T00:00:00.000Z |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `updated_at` | `string` | - | The date and time the workspace was last updated. Example: 2026-06-21T00:00:00.000Z |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `object` | - | The current status of the workspace. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ready` | `boolean` | - | Whether the workspace is ready for use. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `string` | - | The state of the workspace. Possible values: Initializing, InitializationFailed, Ready, or Terminating. |
:::

## Related pages

- [List workspaces](./control-plane-list-workspaces.md)
- [Describe a workspace](./control-plane-describe-a-workspace.md)
- [Delete a workspace](./control-plane-delete-a-workspace.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.