Create an index

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

The index is a document index, read and written through the Documents API. To enable integrated embedding on a field, declare a string field with embed (dense) and/or sparse_embed (sparse): Pinecone embeds the field’s text when documents are written and the query text when a search scores the field. BYOC indexes cannot declare embed or sparse_embed.

The index schema cannot be modified after creation. Field types, dimensions, metrics, embedding models, 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.

Create a legacy integrated index creates legacy integrated indexes, which require the legacy Records API.

POST /indexes

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

201

Example

{
  "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": {
      "title": {
        "full_text_search": {
          "language": "en",
          "stemming": false,
          "stop_words": false
        },
        "store_text": true,
        "type": "string"
      },
      "your_vector": {
        "dimension": 1536,
        "metric": "cosine",
        "type": "dense_vector"
      }
    }
  },
  "status": {
    "ready": true,
    "state": "Ready"
  }
}

The index initializes asynchronously. Before sending data plane requests, poll Describe an index until status.ready is true (and, for Dedicated read capacity, until read_capacity.status.state is "Ready"). The response shows each full_text_search field’s resolved analyzer settings (language, stemming, and stop_words), including any defaults applied at creation.

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.

On the Starter plan, you can create serverless indexes in the us-east-1 region of AWS only. To create indexes in other regions, upgrade to the Builder, Standard, or Enterprise plan.

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

Authorizations

Api-Key · string · header · required

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

Headers

X-Pinecone-Api-Version · string · default: 2026-07 · required

Required date-based version header

Body

application/json

Configuration for a new index.

The schema field is required and defines the typed fields for the index. The deployment field selects infrastructure and defaults to managed (serverless) on AWS us-east-1 if omitted. The name is auto-generated if not provided.

schema · object · required

The schema to use when creating a Pinecone index. Defines the fields the index searches over: dense vector, sparse vector, and string fields searched by full-text search or by embeddings Pinecone derives from their text.

At least one of dense_vector, sparse_vector, or a string field with full_text_search, embed, or sparse_embed must be present; an empty fields map is rejected. An index has one dense vector slot and one sparse vector slot: at most one field may be a dense_vector field or carry embed, and at most one may be a sparse_vector field or carry sparse_embed. 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.

Show child attributes

Example:

{
  "fields": {
    "body": {
      "full_text_search": { "language": "en" },
      "type": "string"
    },
    "your_vector": {
      "dimension": 1536,
      "metric": "cosine",
      "type": "dense_vector"
    }
  }
}

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"

deployment · Serverless · object

The deployment configuration for index creation. The deployment_type field selects the infrastructure model. Defaults to managed (serverless) in us-east-1 on aws if omitted.

• managed: Serverless infrastructure managed by Pinecone, including full-text search indexes.
• byoc: Bring-your-own-compute.

Serverless

BYOC

Show child attributes

Example:

{
  "cloud": "aws",
  "deployment_type": "managed",
  "region": "us-east-1"
}

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"

read_capacity · On-demand · object

By default the index will be created with read capacity mode OnDemand. If you prefer to allocate dedicated read nodes for your workload, you must specify mode Dedicated and additional configurations for node_type and scaling. BYOC indexes do not support OnDemand: a byoc deployment must set mode: Dedicated explicitly, since omitting read_capacity defaults to OnDemand and is rejected.

On-demand

Dedicated

Show child attributes

Example:

{ "mode": "OnDemand" }

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.

Show child attributes

Example:

{ "tag0": "val0", "tag1": "val1" }

deletion_protection · string · default: disabled

Whether deletion protection is enabled/disabled for the index.

Possible values: disabled or enabled.

Response

201

application/json

The index has been successfully created.

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

name · string · required

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"

host · string · required

The URL address where the index is hosted.

Example:

"semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io"

status · object · required

The current status of the index.

Show child attributes

Example:

{ "ready": true, "state": "Ready" }

deployment · Pod-based · object · required

The deployment configuration of a Pinecone index. The deployment_type field indicates which infrastructure model the index uses.

• pod: Dedicated pod-based infrastructure. Suitable for workloads that require predictable performance.
• managed: Serverless infrastructure managed by Pinecone, including full-text search indexes. Scales automatically; billed per usage.
• byoc: Bring-your-own-compute. Runs in customer-managed infrastructure.

Pod-based

Serverless

BYOC

Show child attributes

Example:

{
  "deployment_type": "pod",
  "environment": "us-east1-gcp",
  "pod_type": "p1.x1",
  "replicas": 1,
  "shards": 1
}

schema · object · required

The schema of a Pinecone index. The schema defines the typed fields that documents in the index can contain, including vector fields, string fields searched by full-text search or by embeddings, and metadata fields.

Show child attributes

Example:

{
  "fields": {
    "body": {
      "embed": {
        "dimension": 1024,
        "metric": "cosine",
        "model": "llama-text-embed-v2"
      },
      "full_text_search": {
        "language": "en",
        "stemming": false,
        "stop_words": false
      },
      "sparse_embed": { "model": "pinecone-sparse-english-v0" },
      "store_text": true,
      "type": "string"
    },
    "title": {
      "full_text_search": {
        "language": "en",
        "stemming": false,
        "stop_words": false
      },
      "store_text": true,
      "type": "string"
    }
  }
}

deletion_protection · string · default: disabled · required

Whether deletion protection is enabled/disabled for the index.

Possible values: disabled or enabled.

private_host · string

The private endpoint URL of an index.

Example:

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

read_capacity · On-demand · object

Response containing read capacity configuration

On-demand

Dedicated

Show child attributes

Example:

{
  "mode": "OnDemand",
  "status": { "state": "Ready" }
}

source_collection · string

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

Example:

"movie-embeddings"

source_backup_id · string

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

Example:

"670e8400-e29b-41d4-a716-446655440000"

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"

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.

Show child attributes

Example:

{ "tag0": "val0", "tag1": "val1" }