Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

On this pageOverview

Create an index

To restore from a backup, set spec.serverless.source_backup_id and specify the target cloud and region. Same-cloud cross-region restore is supported when available for the backup's source region. Cross-cloud restore is not supported. For guidance and examples, see Create an index.

Cloud regions

Section titled “Cloud regions”

For serverless indexes, the cloud and region fields in spec.serverless accept the following values:

Cloud Region Supported plans Availability phase
aws us-east-1 (Virginia) Starter, Builder, Standard, Enterprise General availability
aws us-west-2 (Oregon) Builder, Standard, Enterprise General availability
aws eu-west-1 (Ireland) Builder, Standard, Enterprise General availability
aws eu-central-1 (Frankfurt) Builder, Standard, Enterprise General availability
aws ap-southeast-1 (Singapore) Builder, Standard, Enterprise General availability
gcp us-central1 (Iowa) Builder, Standard, Enterprise General availability
gcp europe-west4 (Netherlands) Builder, Standard, Enterprise General availability
azure eastus2 (Virginia) Builder, Standard, Enterprise General availability

The cloud and region can't be changed after a serverless index is created.

For BYOC indexes, set spec.byoc.environment to the environment ID provisioned for your account instead. See Bring Your Own Cloud for details.

curl
# EXAMPLE REQUEST 1: Serverless index (on-demand)
PINECONE_API_KEY="YOUR_API_KEY"
curl -s "https://api.pinecone.io/indexes" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -d '{
        "name": "example-serverless-index",
        "vector_type": "dense",
        "dimension": 1536,
        "metric": "cosine",
        "spec": {
            "serverless": {
                "cloud": "aws",
                "region": "us-east-1"
            }
        },
        "tags": {
            "tag0": "value0"
        },
        "deletion_protection": "disabled"
      }'

# EXAMPLE REQUEST 2: Serverless index (dedicated)
PINECONE_API_KEY="YOUR_API_KEY"
curl "https://api.pinecone.io/indexes" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -d '{
		"name": "example-serverless-dedicated-index",
		"dimension": 1536,
		"metric": "cosine",
		"deletion_protection": "enabled",
		"tags": {
			"tag0": "value0"
		},
		"vector_type": "dense",
		"spec": {
			"serverless": {
				"cloud": "aws",
				"region": "us-east-1",
				"read_capacity": {
					"mode": "Dedicated",
					"dedicated": {
						"node_type": "b1",
						"scaling": "Manual",
						"manual": {
							"shards": 2,
							"replicas": 1
						}
					}
				}
			}
		}
	}'

# EXAMPLE REQUEST 3: BYOC index
PINECONE_API_KEY="YOUR_API_KEY"
curl -s "https://api.pinecone.io/indexes" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-04" \
  -d '{
        "name": "example-byoc-index",
        "vector_type": "dense",
        "dimension": 1536,
        "metric": "cosine",
        "spec": {
            "byoc": {
                "environment": "aws-us-east-1-b921"
            }
        },
        "tags": {
            "tag0": "value0"
        },
        "deletion_protection": "disabled"
      }'
curl
// EXAMPLE RESPONSE 1: Serverless index (on-demand)
{
  "name": "example-serverless-ondemand-index",
  "vector_type": "dense",
  "metric": "cosine",
  "dimension": 1536,
  "status": {
    "ready": false,
    "state": "Initializing"
  },
  "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
  "spec": {
    "serverless": {
      "region": "us-east-1",
      "cloud": "aws",
      "read_capacity": {
        "mode": "OnDemand",
        "status": {
          "state": "Ready",
          "current_shards": null,
          "current_replicas": null
        }
      }
    }
  },
  "deletion_protection": "disabled",
  "tags": {
    "tag0": "value0"
  }
}

// EXAMPLE RESPONSE 2: Serverless index (dedicated)
{
	"name": "example-serverless-dedicated-index",
	"vector_type": "dense",
	"metric": "cosine",
	"dimension": 1536,
	"status": {
		"ready": false,
		"state": "Initializing"
	},
	"host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io",
	"spec": {
		"serverless": {
			"region": "us-east-1",
			"cloud": "aws",
			"read_capacity": {
				"mode": "Dedicated",
				"dedicated": {
					"node_type": "b1",
					"scaling": "Manual",
					"manual": {
						"shards": 2,
						"replicas": 1
					}
				},
				"status": {
					"state": "Migrating",
					"current_shards": null,
					"current_replicas": null
				}
			}
		}
	},
	"deletion_protection": "enabled",
	"tags": {
		"tag0": "value0"
	}
}

// EXAMPLE RESPONSE 3: BYOC index
{
    "name": "example-byoc-index",
    "vector_type": "dense",
    "metric": "cosine",
    "dimension": 1536,
    "status": {
        "ready": true,
        "state": "Ready"
    },
    "host": "example-byoc-index-govk0nt.svc.private.aped-4627-b74a.pinecone.io",
    "spec": {
        "byoc": {
            "environment": "aws-us-east-1-b921"
        }
    },
    "deletion_protection": "disabled",
    "tags": {
        "tag0": "value0"
    }
}

POST /indexes

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-04

Body

Section titled “Body”

The desired configuration for the 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
dimension?integer

The dimensions of the vectors to be inserted in the index.

Required range: 1 <= x <= 20000. Example: 1536

Typeinteger
metric?string

The distance metric to be used for similarity search. You can use 'euclidean', 'cosine', or 'dotproduct'. If the 'vector_type' is 'sparse', the metric must be 'dotproduct'. If the vector_type is dense, the metric defaults to 'cosine'. Possible values: cosine, euclidean, or dotproduct.

Typestring
deletion_protection?string
Typestring
Defaultdisabled

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

tags?object

Custom user tags added to an index. Keys must be 80 characters or less. Values must be 120 characters or less. Keys must be alphanumeric, '', or '-'. Values must be alphanumeric, ';', '@', '', '-', '.', '+', or ' '. To unset a key, set the value to be an empty string.

Typeobject
specobjectrequired
Show child attributes
serverlessobjectrequired

Configuration needed to deploy a serverless index.

Typeobject
Show child attributes
cloudstringrequired

The public cloud where you would like your index hosted. Possible values: gcp, aws, or azure.

Example: aws

Typestring
regionstringrequired

The region where you would like your index to be created.

Example: us-east-1

Typestring
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
source_collection?string

The name of the collection to be used as the source for the index.

Example: movie-embeddings

Typestring
source_backup_id?string

The ID of a backup from which to restore the index. Mutually exclusive with source_collection. The target cloud and region may differ from the backup's source region for same-cloud cross-region restore. Cross-cloud restore is not supported.

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

Typestring
schema?object

Schema for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when schema is present, only fields which are present in the fields object with a filterable: true are indexed. Note that filterable: false is not currently supported.

Typeobject
Show child attributes
fieldsobjectrequired

A map of metadata field names to their configuration. The field name must be a valid metadata field name. The field name must be unique.

Typeobject
vector_type?string

The index vector type. You can use 'dense' or 'sparse'. If 'dense', the vector dimension must be specified. If 'sparse', the vector dimension should not be specified.

Typestring
Defaultdense

Response

Section titled “Response”

201 — The index has been successfully created.

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
dimension?integer

The dimensions of the vectors to be inserted in the index.

Required range: 1 <= x <= 20000. Example: 1536

Typeinteger
metricstringrequired

The distance metric to be used for similarity search. You can use 'euclidean', 'cosine', or 'dotproduct'. If the 'vector_type' is 'sparse', the metric must be 'dotproduct'. If the vector_type is dense, the metric defaults to 'cosine'. Possible values: cosine, euclidean, or dotproduct.

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
deletion_protection?string
Typestring
Defaultdisabled

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

tags?object

Custom user tags added to an index. Keys must be 80 characters or less. Values must be 120 characters or less. Keys must be alphanumeric, '', or '-'. Values must be alphanumeric, ';', '@', '', '-', '.', '+', or ' '. To unset a key, set the value to be an empty string.

Typeobject
embed?object

The embedding model and document fields mapped to embedding inputs.

Typeobject
Show child attributes
modelstringrequired

The name of the embedding model used to create the index.

Example: multilingual-e5-large

Typestring
metric?string

The distance metric to be used for similarity search. You can use 'euclidean', 'cosine', or 'dotproduct'. If not specified, the metric will be defaulted according to the model. Cannot be updated once set. Possible values: cosine, euclidean, or dotproduct.

Typestring
dimension?integer

The dimensions of the vectors to be inserted in the index.

Required range: 1 <= x <= 20000. Example: 1536

Typeinteger
vector_type?string

The index vector type. You can use 'dense' or 'sparse'. If 'dense', the vector dimension must be specified. If 'sparse', the vector dimension should not be specified.

Typestring
Defaultdense
field_map?object

Identifies the name of the text field from your document model that is embedded.

Typeobject
read_parameters?object

The read parameters for the embedding model.

Typeobject
write_parameters?object

The write parameters for the embedding model.

Typeobject
specobjectrequired
Show child attributes
serverlessobjectrequired

Configuration of a serverless index.

Typeobject
Show child attributes
cloudstringrequired

The public cloud where you would like your index hosted. Possible values: gcp, aws, or azure.

Example: aws

Typestring
regionstringrequired

The region where you would like your index to be created.

Example: us-east-1

Typestring
read_capacityobjectrequired
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
source_collection?string

The name of the collection to be used as the source for the index.

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
schema?object

Schema for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when schema is present, only fields which are present in the fields object with a filterable: true are indexed. Note that filterable: false is not currently supported.

Typeobject
Show child attributes
fieldsobjectrequired

A map of metadata field names to their configuration. The field name must be a valid metadata field name. The field name must be unique.

Typeobject
statusobjectrequired

The current status of the index

Typeobject
Show child attributes
readybooleanrequired

Whether the index is ready for use

Typeboolean
statestringrequired

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

Typestring
vector_typestringrequired

The index vector type. You can use 'dense' or 'sparse'. If 'dense', the vector dimension must be specified. If 'sparse', the vector dimension should not be specified.

Typestring
Defaultdense
Suggest an edit

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

Export
Documentation menu