# 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 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "example-workspace",
  "spec": {
    "byoc": {
      "environment": "aws-us-east-1-b921.byoc"
    }
  }
}'
```

```json title="201"
{
  "name": "example-workspace",
  "spec": {
    "byoc": {
      "environment": "aws-us-east-1-b921.byoc"
    }
  },
  "host": "production-c01b5b5.wksp.prod.pinecone.io",
  "created_at": "2026-06-21T00:00:00.000Z",
  "updated_at": "2026-06-21T00:00:00.000Z",
  "status": {
    "ready": true,
    "state": "Ready"
  }
}
```
:::

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Headers

- `X-Pinecone-Api-Version` (header, string, required) — Required date-based version header

## Body

- `name` (body, string, required) — 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 '-'.
- `spec` (body, object, required) — 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.

## Response

- `201` — The workspace create request has been accepted. The workspace is being provisioned asynchronously and starts in the `Initializing` state.
- `400` — Bad request. The request body included invalid request parameters.
- `401` — Unauthorized. Possible causes: Invalid API key.
- `403` — Forbidden. The API key does not have permission to perform this action, or a project limit (such as the maximum number of workspaces) has been reached.
- `409` — Workspace of given name already exists.
- `422` — Unprocessable entity. The request body could not be deserialized.
- `500` — Internal server error.

## 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.