Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

Configure an index

Configure an existing index. For guidance and examples, see Manage indexes.

Updates configuration on an existing index. You can update deletion_protection, tags, and read_capacity (for example, converting from OnDemand to Dedicated). The schema itself is immutable — to change field types or add new indexed fields, create a new index and re-upsert.

This is a partial update: only the fields you include in the request body are modified. Unspecified fields are left unchanged. To clear tags, send "tags": {}.

Python
# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

# Enable deletion protection
pc.indexes.configure(
    name="articles",
    deletion_protection="enabled",
)

# Convert read capacity from OnDemand to Dedicated
pc.indexes.configure(
    name="articles",
    read_capacity={
        "mode": "Dedicated",
        "dedicated": {
            "node_type": "b1",
            "scaling": "Manual",
            "manual": {"shards": 1, "replicas": 1},
        },
    },
)
curl
PINECONE_API_KEY="YOUR_API_KEY"

# Enable deletion protection
curl -X PATCH "https://api.pinecone.io/indexes/articles" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{ "deletion_protection": "enabled" }'

# Convert read capacity from OnDemand to Dedicated
curl -X PATCH "https://api.pinecone.io/indexes/articles" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "read_capacity": {
      "mode": "Dedicated",
      "dedicated": {
        "node_type": "b1",
        "scaling": "Manual",
        "manual": { "shards": 1, "replicas": 1 }
      }
    }
  }'

PATCH /indexes/{index_name}

200
{
  "deletion_protection": "disabled",
  "deployment": {
    "cloud": "aws",
    "deployment_type": "managed",
    "region": "us-east-1"
  },
  "host": "my-index-abc123.svc.pinecone.io",
  "name": "my-index",
  "read_capacity": {
    "mode": "OnDemand",
    "status": {
      "state": "Ready"
    }
  },
  "schema": {
    "fields": {
      "embedding": {
        "dimension": 1536,
        "metric": "cosine",
        "type": "dense_vector"
      },
      "title": {
        "full_text_search": {
          "language": "en",
          "stemming": false,
          "stop_words": false
        },
        "type": "string"
      }
    }
  },
  "status": {
    "ready": true,
    "state": "Ready"
  }
}
400
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Bad request. The request body included invalid request parameters."
  },
  "status": 400
}
403
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Increase your quota or upgrade to create more indexes."
  },
  "status": 403
}
404
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Index example-index not found."
  },
  "status": 404
}
422
{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Failed to deserialize the JSON body into the target type: missing field `metric` at line 1 column 16"
  },
  "status": 422
}
500
{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

Authorizations

Section titled “Authorizations”
Api-Keystringrequired

An API Key is required to call Pinecone APIs. Get yours from the console.

Headers

Section titled “Headers”
X-Pinecone-Api-Versionstringrequired

Required date-based version header

Typestring
Default2026-07

Path Parameters

Section titled “Path Parameters”
index_namestringrequired

The name of the index to configure.

Typestring

Body

Section titled “Body”
deployment?object

Deployment update parameters for pod-based indexes. Specify replicas, pod_type, or both. Deployment type, cloud/region, and environment cannot be changed after creation. Do not include a deployment_type field; it is not accepted.

Typeobject
Show child attributes
replicas?integer

The number of replicas. Replicas duplicate your index. They provide higher availability and throughput. Replicas can be scaled up or down as your needs change.

Required range: 1 <= x

Typeinteger
Default1
pod_type?string

The type of pod to use. One of s1, p1, or p2 appended with . and one of x1, x2, x4, or x8.

Typestring
Defaultp1.x1
schema?object

Schema updates to apply to an existing index. Only semantic_text field parameters can be updated after index creation. The model itself cannot be changed once set; only write_parameters and read_parameters may be updated if the model stays the same.

Typeobject
Show child attributes
fieldsobjectrequired

A map of semantic text field names to their updated parameters. Only fields of type semantic_text may be specified, and only one field per request.

Typeobject
read_capacity?object
Show child attributes
modestringrequired

The mode of the index. Possible values: OnDemand or Dedicated. Defaults to OnDemand. If set to Dedicated, dedicated.node_type, and dedicated.scaling must be specified.

Typestring
tags?object | null

Custom user tags added to an index, at most 20 per index. Keys must be 80 characters or less and alphanumeric, '', or '-'. Values must be 120 characters or less and consist of printable ASCII characters or spaces. To unset a key, set the value to be an empty string. null in responses when the index has no tags.

Typeobject | null
deletion_protection?string
Typestring
Defaultdisabled

Whether deletion protection is enabled/disabled for the index. Possible values: disabled or enabled.

Response

Section titled “Response”

200 — The configuration change was recorded and the updated index is returned. Changes that resize the index (replicas, shards, read capacity) are applied asynchronously; poll the index status to see when they take effect.

The IndexModel describes the configuration and status of a Pinecone index.

namestringrequired

The name of the index. 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-index

Typestring
hoststringrequired

The URL address where the index is hosted.

Example: semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io

Typestring
private_host?string

The private endpoint URL of an index.

Example: semantic-search-c01b5b5.svc.private.us-west1-gcp.pinecone.io

Typestring
statusobjectrequired

The current status of the index.

Typeobject
Show child attributes
readybooleanrequired

Whether the index is ready for use.

Typeboolean
statestringrequired

The current state of the index. Possible values: Initializing, InitializationFailed, Failed, ScalingUp, ScalingDown, ScalingUpPodSize, Terminating, Ready, or Disabled.

Typestring
deploymentobjectrequired

Deployment configuration for a pod-based index.

Typeobject
Show child attributes
deployment_typeenum<string>required

Identifies this as a pod-based deployment. Must be pod.

Available options: pod

Typeenum<string>
environmentstringrequired

The environment where the index is hosted.

Example: us-east1-gcp

Typestring
replicas?integer

The number of replicas. Replicas duplicate your index. They provide higher availability and throughput. Replicas can be scaled up or down as your needs change.

Required range: 1 <= x

Typeinteger
Default1
shards?integer

The number of shards. Shards split your data across multiple pods so you can fit more data into an index.

Required range: 1 <= x

Typeinteger
Default1
pod_typestringrequired

The type of pod to use. One of s1, p1, or p2 appended with . and one of x1, x2, x4, or x8.

Typestring
Defaultp1.x1
read_capacity?object
Show child attributes
modestringrequired

The mode of the index. Possible values: OnDemand or Dedicated. Defaults to OnDemand. If set to Dedicated, dedicated.node_type, and dedicated.scaling must be specified.

Typestring
statusobjectrequired

The current status of factors affecting the read capacity of a serverless index

Typeobject
Show child attributes
statestringrequired

The state describes the overall status of factors relating to the read capacity of an index. Available values: - Ready is the state most of the time - Scaling if the number of replicas or shards has been recently updated by calling the configure index endpoint - Migrating if the index is being migrated to a new node_type - Error if there is an error with the read capacity configuration. In that case, see error_message for more details.

current_replicas?integer | null

The number of replicas. Each replica has dedicated compute resources and data storage. Increasing this number will increase the total throughput of the index. null for OnDemand indexes and for a Dedicated index that has not finished provisioning.

Typeinteger | null
current_shards?integer | null

The number of shards. Each shard has dedicated storage. Increasing shards alleviates index fullness. null for OnDemand indexes and for a Dedicated index that has not finished provisioning.

Typeinteger | null
error_message?string

An optional error message indicating any issues with your read capacity configuration

Typestring
source_collection?string

The name of the collection this index was created from, if any.

Example: movie-embeddings

Typestring
source_backup_id?string

The ID of the backup this index was restored from, if any.

Example: 670e8400-e29b-41d4-a716-446655440000

Typestring
cmek_id?string

The ID of the customer-managed encryption key (CMEK) used to encrypt this index, if any.

Example: arn:aws:kms:us-east-1:123456789012:key/mrk-abc123

Typestring
schemaobjectrequired

The schema of a Pinecone index. The schema defines the typed fields that documents in the index can contain, including vector fields, semantic text fields, and metadata fields.

Typeobject
Show child attributes
fieldsobjectrequired

A map of field names to their configurations. Indexes that are served by the vectors API — created with the reserved _values / _sparse_values schema, or created by an earlier API version from dimension, metric, and vector_type — report their vector fields under the reserved names _values (dense) and _sparse_values (sparse), and any metadata fields configured for filtering as legacy fields carrying only filterable. Dense vectors-API indexes always report both _values and _sparse_values, regardless of how they were created.

Typeobject
tags?object | null

Custom user tags added to an index, at most 20 per index. Keys must be 80 characters or less and alphanumeric, '', or '-'. Values must be 120 characters or less and consist of printable ASCII characters or spaces. To unset a key, set the value to be an empty string. null in responses when the index has no tags.

Typeobject | null
deletion_protectionstringrequired
Typestring
Defaultdisabled

Whether deletion protection is enabled/disabled for the index. Possible values: disabled or enabled.

Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu