---
title: "Create a keyspace"
method: POST
path: "/organizations/{organization}/databases/{database}/branches/{branch}/keyspaces"
tags: ["Database branch keyspaces"]
---

# Create a keyspace

`POST /organizations/{organization}/databases/{database}/branches/{branch}/keyspaces`

### Authorization
A service token   must have at least one of the following access   in order to use this API endpoint:

**Service Token Accesses**
 `create_branch`

## Path parameters

- `organization` string, required
- `database` string, required
- `branch` string, required

## Request body

- object
  - `name` string, required — The name of the keyspace
  - `cluster_size` string, required — The database cluster size name (e.g., 'PS_10', 'PS_80'). Use the 'List available cluster sizes' endpoint to get available options for your organization. /v1/organizations/:organization/cluster-size-skus
  - `extra_replicas` integer — The number of additional replicas beyond the included default
  - `shards` integer — The number of shards. Default: 1

## Response `200`

Returns a created keyspace

- object
  - `id` string, required — The ID of the keyspace
  - `name` string, required — Name of the keyspace
  - `shards` integer, required — The number of keyspace shards
  - `sharded` boolean, required — If the keyspace is sharded
  - `replicas` integer, required — Total number of replicas in the keyspace
  - `extra_replicas` integer, required — Number of extra replicas in the keyspace
  - `created_at` string, required — When the keyspace was created
  - `updated_at` string, required — When the keyspace was last updated
  - `cluster_name` string, required — The SKU representing the keyspace cluster size
  - `cluster_display_name` string, required — The SKU representing the keyspace cluster size for display
  - `resizing` boolean, required — Is the keyspace currently resizing
  - `resize_in_progress` boolean, required — True if the keyspace has an unfinished resize request
  - `resize_pending` boolean, required — Is the keyspace awaiting a resize
  - `config_change_in_progress` boolean, required — Is the keyspace undergoing a config change
  - `ready` boolean, required — Is the keyspace provisioned and serving traffic
  - `metal` boolean, required — Is the keyspace running on metal instances
  - `default` boolean, required — Is this the default keyspace for the branch
  - `imported` boolean, required — Is this keyspace used in an import
  - `vector_pool_allocation` number, nullable, required — Percentage of buffer pool memory allocated to vector indexes
  - `node_ttl_strategy` 'node_ttl_follow_maintenance' | 'node_ttl_always' | 'node_ttl_off', required — Controls when node TTL drains are allowed
  - `replication_durability_constraints` object, required
    - `strategy` 'available' | 'lag' | 'always', nullable — The replication durability strategy
  - `vreplication_flags` object, required
    - `optimize_inserts` boolean, required — Enable optimized inserts
    - `allow_no_blob_binlog_row_image` boolean, required — Allow no blob binlog row image
    - `vplayer_batching` boolean, required — Enable VPlayer batching
  - `mysqld_options` object, required — MySQL daemon configuration options
  - `vttablet_options` object, required — VTTablet configuration options

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

## Changes

- **2026-08-12** `fd4480152110` — 1 info
  - added the required property `resize_in_progress` to the response with the `200` status
- **2026-06-01** `72506953f367` — 3 breaking, 1 info
  - the response property `replication_durability_constraints/strategy` became nullable for the status `200`
  - the response property `vector_pool_allocation` became nullable for the status `200`
  - the response property `replication_durability_constraints/strategy` became optional for the status `200`
  - added the required property `config_change_in_progress` to the response with the `200` status
- **2026-02-24** `3c33e46f8ff2` — 1 breaking, 2 info
  - removed the required property `mysqld_options/binlog_row_value_options` from the response with the `200` status
  - added the required property `node_ttl_strategy` to the response with the `200` status
  - added the required property `vttablet_options` to the response with the `200` status
- **2026-02-10** `ed1825db11c6` — 1 info
  - added the required property `mysqld_options` to the response with the `200` status
- **2025-12-09** `d710019068fb` — 2 breaking
  - the `extra_replicas` request property type/format changed from `number`/`` to `integer`/``
  - the `shards` request property type/format changed from `number`/`` to `integer`/``

[Full history](https://skmtc.dev/planetscale/apis/planetscale-api/changes/organizations/:organization/databases/:database/branches/:branch/keyspaces/post.md)

---

[API](https://skmtc.dev/planetscale/apis/planetscale-api.md) · [All operations](https://skmtc.dev/planetscale/apis/planetscale-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/planetscale/planetscale-api/revisions/6d28c038c4fd/schema)