Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

On this pageOverview

Create an index

Create a Pinecone index. Define the schema for your index — dense vector, sparse vector, and full-text search fields — and, optionally, the deployment infrastructure (managed serverless or BYOC). To create an index with an integrated embedding model, use Create an index with integrated embedding.

The index schema cannot be modified after creation. Field types, dimensions, metrics, and text-analysis settings are permanent. Choose your schema carefully before creating an index.

To create an index from a backup, use Create index from backup.

For guidance and examples, see Create an index.

Creates a new schema-defined index. The schema declares each field and its type — dense vector, sparse vector, or full-text search. The index initializes asynchronously; poll GET /indexes/{index_name} until status.ready: true (and, for Dedicated read capacity, read_capacity.status.state: "Ready") before performing data plane operations.

Cloud regions

Section titled “Cloud regions”

For managed (serverless) indexes, the cloud and region fields in deployment 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 deployment.environment to the environment ID provisioned for your account instead. See Bring Your Own Cloud for details.

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

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

schema = (
    SchemaBuilder()
      .add_string_field(name="title", full_text_search={})
      .add_string_field(name="body", full_text_search={"language": "en", "stemming": True, "stop_words": True})
      .build()
)

index_model = pc.indexes.create(
    name="articles",
    schema=schema,
    read_capacity={"mode": "OnDemand"},
)

host = index_model.host
curl
PINECONE_API_KEY="YOUR_API_KEY"

# EXAMPLE REQUEST 1: On-demand read capacity (default)
curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "name": "articles",
    "deployment": {
      "deployment_type": "managed",
      "cloud": "aws",
      "region": "us-east-1"
    },
    "schema": {
      "fields": {
        "title": {
          "type": "string",
          "full_text_search": {}
        },
        "body": {
          "type": "string",
          "full_text_search": {}
        }
      }
    },
    "read_capacity": { "mode": "OnDemand" },
    "deletion_protection": "disabled"
  }'

# EXAMPLE REQUEST 2: Dedicated read capacity
curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "name": "articles-dedicated",
    "deployment": {
      "deployment_type": "managed",
      "cloud": "aws",
      "region": "us-east-1"
    },
    "schema": {
      "fields": {
        "content": {
          "type": "string",
          "full_text_search": {}
        }
      }
    },
    "read_capacity": {
      "mode": "Dedicated",
      "dedicated": {
        "node_type": "b1",
        "scaling": "Manual",
        "manual": { "shards": 1, "replicas": 1 }
      }
    },
    "deletion_protection": "disabled"
  }'

# EXAMPLE REQUEST 3: Multi-field schema (text + dense + sparse ranking fields)
curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "name": "articles-multifield",
    "deployment": {
      "deployment_type": "managed",
      "cloud": "aws",
      "region": "us-east-1"
    },
    "schema": {
      "fields": {
        "title":     { "type": "string",        "full_text_search": {} },
        "body":      { "type": "string",        "full_text_search": { "language": "en", "stemming": true, "stop_words": true } },
        "embedding": { "type": "dense_vector",  "dimension": 1536, "metric": "cosine" },
        "sparse_embedding": { "type": "sparse_vector" }
      }
    }
  }'

# EXAMPLE REQUEST 4: Classic vector index — reserved `_values` field, served by the Vectors API.
curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "name": "classic-index",
    "schema": {
      "fields": {
        "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" }
      }
    }
  }'

# EXAMPLE REQUEST 5: Bring-your-own-cloud (BYOC) deployment.
# BYOC indexes require Dedicated read capacity — OnDemand is rejected.
curl "https://api.pinecone.io/indexes" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "name": "byoc-index",
    "deployment": {
      "deployment_type": "byoc",
      "environment": "aws-us-east-1-b921"
    },
    "read_capacity": {
      "mode": "Dedicated",
      "dedicated": {
        "node_type": "b1",
        "scaling": "Manual",
        "manual": { "shards": 1, "replicas": 1 }
      }
    },
    "schema": {
      "fields": {
        "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" }
      }
    }
  }'

POST /indexes

201
{
  "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
}
402
{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Request failed. Pay all past due invoices to lift restrictions on your account."
  },
  "status": 402
}
403
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Increase your quota or upgrade to create more indexes."
  },
  "status": 403
}
404
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource cloud: aws region: us-west1 not found."
  },
  "status": 404
}
409
{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "Resource already exists."
  },
  "status": 409
}
412
{
  "error": {
    "code": "FAILED_PRECONDITION",
    "message": "Index creation failed. Indexes with full_text_search fields are not supported in CMEK-encrypted projects"
  },
  "status": 412
}

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

Body

Section titled “Body”
name?string

The name of the index. Must be unique within the project, start and end with an alphanumeric character, and contain only lower case alphanumeric characters or '-'. Generated automatically if not provided.

Required string length: 1 - 45. Example: example-index

Typestring
deployment?object

Deployment configuration for a serverless (managed) index. Serverless indexes scale automatically and you are billed only for the resources you use. This deployment type also covers full-text search indexes, which are serverless under the hood.

Typeobject
Show child attributes
deployment_typeenum<string>required

Identifies this as a managed (serverless) deployment. Must be managed.

Available options: managed

Typeenum<string>
cloudstringrequired

The public cloud where the index is hosted. Possible values: gcp, aws, or azure.

Example: aws

Typestring
regionstringrequired

The region where the index is hosted.

Example: us-east-1

Typestring
environment?string

The Pinecone environment hosting the index. Returned in responses; do not set it when creating an index.

Example: aped-4627-b74a

Typestring
schemaobjectrequired

The schema to use when creating a Pinecone index. Defines the fields the index searches over: dense vector, sparse vector, and full-text search fields. At least one of dense_vector, sparse_vector, or a string field with full_text_search must be present; an empty fields map is rejected. At most one dense_vector and one sparse_vector field, and at most 100 full_text_search fields. Metadata used for filtering is not declared in the schema; it is indexed automatically from the documents you upsert.

Typeobject
Show child attributes
fieldsobjectrequired

A map of field names to their configurations. Field names must be unique, non-empty strings of at most 64 bytes and must not start with $, which introduces a filter operator. Names starting with _ are reserved: this covers _id, _values, _sparse_values, and every other underscore-prefixed name. Two reserved names are accepted, and only as the whole schema: _values (type dense_vector) and/or _sparse_values (type sparse_vector) with no other fields. Such a schema creates a classic vector index, which is read and written through the vectors API rather than the documents API — the same index that earlier API versions created from dimension, metric, and vector_type. Reserved fields do not accept a description. Any other field named with a leading _, or a reserved field combined with other fields, is rejected.

Typeobject
cmek_id?string

The ID of a customer-managed encryption key (CMEK) to use for this index. Requires CMEK to be enabled for your organization. Encrypted indexes cannot have full_text_search fields: a request that sets cmek_id and declares one is rejected, and a project that enforces CMEK rejects any schema with a full_text_search field with 412.

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

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

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