---
title: "PATCH /v1/namespaces/{namespace}/metadata"
method: PATCH
path: "/v1/namespaces/{namespace}/metadata"
---

# PATCH /v1/namespaces/{namespace}/metadata

`PATCH /v1/namespaces/{namespace}/metadata`

Update metadata configuration for a namespace.

## Path parameters

- `namespace` string, required

## Request body

- NamespaceMetadataPatch — Request to update namespace metadata configuration.
  - `pinning` union — Configuration for namespace pinning. - Missing field: no change to pinning configuration - `null` or `false`: explicitly remove pinning - `true`: enable pinning with default configuration - Object: set pinning configuration
    - boolean
    - PinningConfig — Configuration for namespace pinning.
      - `replicas` integer — The number of read replicas to provision. Defaults to 1 if not specified.

## Response `200`

The updated metadata of the namespace.

- NamespaceMetadata — Metadata about a namespace.
  - `schema` object, required — The schema of the namespace.
  - `approx_row_count` integer, required — The approximate number of rows in the namespace.
  - `approx_logical_bytes` integer, required — The approximate number of logical bytes in the namespace.
  - `created_at` string, date-time, required — The timestamp when the namespace was created.
  - `updated_at` string, date-time, required — The timestamp when the namespace was last modified by a write operation.
  - `encryption` union, required — The encryption configuration for a namespace.
    - object — Encrypt the namespace with a customer-managed encryption key (CMEK).
      - `mode` 'customer-managed', required
      - `key_name` string, required — The identifier of the CMEK key to use for encryption. For GCP, the fully-qualified resource name of the key. For AWS, the ARN of the key.
    - object — Use the default server-side encryption (SSE).
      - `mode` 'default', required
  - `index` union, required
    - object
      - `status` 'up-to-date', required
    - object
      - `status` 'updating', required
      - `unindexed_bytes` integer, required — The number of bytes in the namespace that are in the write-ahead log but have not yet been indexed.
  - `pinning` PinningConfigResponse — Configuration for namespace pinning.
    - `replicas` integer — The number of read replicas to provision. Defaults to 1 if not specified.
    - `status` PinningStatus — Operational status for a pinned namespace.
      - `updated_at` string, date-time, required — The timestamp of the latest pinning status snapshot.
      - `ready_replicas` integer, required — The number of replicas that are warm and serving traffic.
      - `utilization` number, required — Aggregate utilization for the pinned namespace, reported as a value between 0.0 and 1.0.
  - `sharding` ShardingConfig — Configuration for namespace sharding, which partitions a namespace's documents across multiple internal shards to scale indexing and query throughput beyond a single machine. Sharding can only be configured on a namespace's inaugural write, and cannot be added to or changed on an existing namespace.
    - `num_shards` integer, required — The number of shards to partition the namespace into.

## Other responses

- `default` — An error response.

---

[API](https://skmtc.net/turbopuffer/apis/turbopuffer-api.md) · [All operations](https://skmtc.net/turbopuffer/apis/turbopuffer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/turbopuffer/turbopuffer-api/versions/245e887f04ab/schema)