> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_for_model). If `deployment` is omitted, the index is deployed as a managed (serverless) index on `aws` in `us-east-1`.
**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](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_from_backup).
For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/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](/guides/search/full-text-search). The index initializes asynchronously; poll [`GET /indexes/{index_name}`](/reference/api/2026-07/control-plane/describe_index) until `status.ready: true` (and, for `Dedicated` read capacity, `read_capacity.status.state: "Ready"`) before performing data plane operations.
To create a classic vector index (read and written through the Vectors API), use the reserved `_values` (dense) and/or `_sparse_values` (sparse) schema fields. These replace the top-level `dimension`, `metric`, and `vector_type` of earlier API versions, and are REST-only for now.
Document schemas do not support `semantic_text` fields. To combine semantic ranking with full-text search, declare a `dense_vector` field and provide vector values when you upsert documents. For integrated embedding indexes that use the Records API, see [Create an index](/guides/index-data/create-an-index).
## Cloud regions
For managed (serverless) indexes, the `cloud` and `region` fields in `deployment` accept the following values:
| Cloud | Region | [Supported plans](https://www.pinecone.io/pricing/) | [Availability phase](/release-notes/feature-availability) |
| ------- | ---------------------------- | --------------------------------------------------- | --------------------------------------------------------- |
| `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 cannot 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](/guides/organizations/manage-billing/upgrade-billing-plan).
For BYOC indexes, set `deployment.environment` to the environment ID provisioned for your account instead. See [Bring your own cloud](/guides/production/bring-your-own-cloud) for details.
```python Python theme={null}
# 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
```
```shell curl theme={null}
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" }
}
}
}'
```
Responses show each `full_text_search` field's resolved analyzer config: `language`, `stemming`, and `stop_words` reflect your request settings or the defaults applied at index creation.
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /indexes
openapi: 3.0.3
info:
title: Pinecone Control Plane API
description: >-
Pinecone is a vector database that makes it easy to search and retrieve
billions of high-dimensional vectors.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-07
servers:
- url: https://api.pinecone.io
description: Production API endpoints
security:
- ApiKeyAuth: []
tags:
- name: Manage Indexes
description: Actions that manage indexes
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/indexes:
post:
tags:
- Manage Indexes
summary: Create an index
description: >
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](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_for_model).
If `deployment` is omitted, the index is deployed as a managed
(serverless) index on `aws` in `us-east-1`.
**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](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_from_backup).
For guidance and examples, see [Create an
index](https://docs.pinecone.io/guides/index-data/create-an-index).
operationId: create_index
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-07
type: string
style: simple
requestBody:
description: The desired configuration for the index.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIndexRequest'
examples:
default-deployment:
summary: Dense vector index using the default deployment
value:
schema:
fields:
embedding:
dimension: 1536
metric: cosine
type: dense_vector
classic-vectors-api:
summary: Classic dense index served by the vectors API
value:
name: classic-index
schema:
fields:
_values:
dimension: 1536
metric: cosine
type: dense_vector
dense-serverless:
summary: Dense vector serverless index
value:
deletion_protection: enabled
deployment:
cloud: aws
deployment_type: managed
region: us-east-1
name: movie-recommendations
schema:
fields:
embedding:
dimension: 1536
metric: cosine
type: dense_vector
sparse-serverless:
summary: Sparse vector serverless index
value:
deployment:
cloud: aws
deployment_type: managed
region: us-east-1
name: sparse-index
schema:
fields:
sparse_embedding:
type: sparse_vector
hybrid-serverless:
summary: Hybrid dense + sparse serverless index
value:
deployment:
cloud: gcp
deployment_type: managed
region: us-central1
name: hybrid-index
schema:
fields:
embedding:
dimension: 768
metric: dotproduct
type: dense_vector
sparse_embedding:
type: sparse_vector
fts-serverless:
summary: Full-text search serverless index
value:
deployment:
cloud: aws
deployment_type: managed
region: us-east-1
name: fts-index
schema:
fields:
body:
full_text_search:
language: en
stemming: true
stop_words: true
type: string
dedicated-read-capacity:
summary: Serverless index with dedicated read capacity
value:
deployment:
cloud: aws
deployment_type: managed
region: us-east-1
name: dedicated-index
read_capacity:
dedicated:
manual:
replicas: 2
shards: 2
node_type: t1
scaling: Manual
mode: Dedicated
schema:
fields:
embedding:
dimension: 1536
metric: cosine
type: dense_vector
required: true
responses:
'201':
description: The index has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/IndexModel'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-metric-validation-error:
summary: Validation error
value:
error:
code: INVALID_ARGUMENT
message: >-
Bad request. The request body included invalid request
parameters.
status: 400
'401':
description: 'Unauthorized. Possible causes: missing or invalid API key.'
content:
text/plain:
schema:
$ref: '#/components/schemas/UnauthorizedMessage'
'402':
description: >-
Payment required. Organization is on a paid plan and is delinquent
on payment.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
payment-required:
summary: Payment required
value:
error:
code: PAYMENT_REQUIRED
message: >-
Request failed. Pay all past due invoices to lift
restrictions on your account.
status: 402
'403':
description: >-
Forbidden. Possible causes: the project's index quota is exhausted,
dedicated read capacity is not enabled for the organization, or
(when configuring) the index's read capacity is not yet `Ready`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Forbidden
value:
error:
code: FORBIDDEN
message: Increase your quota or upgrade to create more indexes.
status: 403
'404':
description: Unknown cloud or region when creating a serverless index.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serverless-spec-cloud-not-found:
summary: Unknown cloud or region when creating a serverless index.
value:
error:
code: NOT_FOUND
message: 'Resource cloud: aws region: us-west1 not found.'
status: 404
'409':
description: Index of given name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-name-already-exists:
summary: Index name needs to be unique.
value:
error:
code: ALREADY_EXISTS
message: Resource already exists.
status: 409
'412':
description: The project's encryption settings do not allow this index.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
cmek-full-text-search:
summary: >-
Full-text search fields are not supported in CMEK-encrypted
projects.
value:
error:
code: FAILED_PRECONDITION
message: >-
Index creation failed. Indexes with full_text_search
fields are not supported in CMEK-encrypted projects
status: 412
'422':
description: Unprocessable entity. The request body could not be deserialized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing-field:
summary: Unprocessable entity
value:
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':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internal-server-error:
summary: Internal server error
value:
error:
code: UNKNOWN
message: Internal server error
status: 500
components:
schemas:
CreateIndexRequest:
description: >-
The configuration needed to create a Pinecone 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.
type: object
properties:
name:
example: example-index
description: >-
The name of the index. Must be unique within the project. Resource
name must be 1-45 characters long, start and end with an
alphanumeric character, and consist only of lower case alphanumeric
characters or '-'. If not provided, a name is generated
automatically. Callers that require retry-safe behavior should
provide an explicit name — a duplicate request with the same name
returns 409, making success detectable on retry.
type: string
minLength: 1
maxLength: 45
deployment:
$ref: '#/components/schemas/IndexDeploymentRequest'
schema:
$ref: '#/components/schemas/CreateIndexSchema'
cmek_id:
example: arn:aws:kms:us-east-1:123456789012:key/mrk-abc123
description: >-
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`.
type: string
read_capacity:
$ref: '#/components/schemas/ReadCapacity'
tags:
$ref: '#/components/schemas/IndexTags'
deletion_protection:
$ref: '#/components/schemas/DeletionProtection'
required:
- schema
additionalProperties: false
IndexModel:
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:
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
description: >-
The IndexModel describes the configuration and status of a Pinecone
index.
type: object
properties:
name:
example: example-index
description: >
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 '-'.
type: string
minLength: 1
maxLength: 45
host:
example: semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io
description: The URL address where the index is hosted.
type: string
private_host:
example: semantic-search-c01b5b5.svc.private.us-west1-gcp.pinecone.io
description: The private endpoint URL of an index.
type: string
status:
example:
ready: true
state: Ready
description: The current status of the index.
type: object
properties:
ready:
description: Whether the index is ready for use.
type: boolean
state:
description: >-
The current state of the index.
Possible values: `Initializing`, `InitializationFailed`,
`Failed`, `ScalingUp`, `ScalingDown`, `ScalingUpPodSize`,
`Terminating`, `Ready`, or `Disabled`.
x-enum:
- Initializing
- InitializationFailed
- Failed
- ScalingUp
- ScalingDown
- ScalingUpPodSize
- Terminating
- Ready
- Disabled
type: string
required:
- ready
- state
deployment:
$ref: '#/components/schemas/IndexDeployment'
read_capacity:
$ref: '#/components/schemas/ReadCapacityResponse'
source_collection:
example: movie-embeddings
description: The name of the collection this index was created from, if any.
type: string
source_backup_id:
example: 670e8400-e29b-41d4-a716-446655440000
description: The ID of the backup this index was restored from, if any.
type: string
cmek_id:
example: arn:aws:kms:us-east-1:123456789012:key/mrk-abc123
description: >-
The ID of the customer-managed encryption key (CMEK) used to encrypt
this index, if any.
type: string
schema:
$ref: '#/components/schemas/IndexSchema'
tags:
$ref: '#/components/schemas/IndexTags'
deletion_protection:
$ref: '#/components/schemas/DeletionProtection'
required:
- name
- host
- status
- deployment
- schema
- deletion_protection
ErrorResponse:
example:
error:
code: INVALID_ARGUMENT
message: >-
Index name must contain only lowercase alphanumeric characters or
hyphens, and must not begin or end with a hyphen.
status: 400
description: The response shape used for all error responses.
type: object
properties:
status:
example: 500
description: The HTTP status code of the error.
type: integer
error:
example:
code: INVALID_ARGUMENT
message: >-
Index name must contain only lowercase alphanumeric characters or
hyphens, and must not begin or end with a hyphen.
description: Detailed information about the error that occurred.
type: object
properties:
code:
description: >-
The error code.
Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`,
`DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`,
`PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`,
`FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`,
`FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`,
`PAYLOAD_TOO_LARGE`, or `UNPROCESSABLE_ENTITY`.
x-enum:
- OK
- UNKNOWN
- INVALID_ARGUMENT
- DEADLINE_EXCEEDED
- NOT_FOUND
- ALREADY_EXISTS
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- FAILED_PRECONDITION
- ABORTED
- OUT_OF_RANGE
- INTERNAL
- FORBIDDEN
- PAYMENT_REQUIRED
- SERVICE_UNAVAILABLE
- PAYLOAD_TOO_LARGE
- UNPROCESSABLE_ENTITY
type: string
message:
example: >-
Index name must contain only lowercase alphanumeric characters
or hyphens, and must not begin or end with a hyphen.
description: A human-readable description of the error
type: string
details:
description: >-
Additional information about the error. This field is not
guaranteed to be present.
type: object
required:
- code
- message
required:
- status
- error
UnauthorizedMessage:
example: Invalid API key
description: >-
The plain-text body of a `401` response. Authentication failures are
rejected before the request reaches the API, so they carry a short
message rather than an `ErrorResponse`.
type: string
IndexDeploymentRequest:
description: >-
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.
discriminator:
propertyName: deployment_type
mapping:
managed:
$ref: '#/components/schemas/ManagedDeployment'
byoc:
$ref: '#/components/schemas/ByocDeployment'
oneOf:
- $ref: '#/components/schemas/ManagedDeployment'
- $ref: '#/components/schemas/ByocDeployment'
CreateIndexSchema:
example:
fields:
body:
full_text_search:
language: en
type: string
embedding:
dimension: 1536
metric: cosine
type: dense_vector
description: >-
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.
type: object
properties:
fields:
description: >-
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.
The map may not be empty: a schema with no fields is rejected with
`Schema must contain at least one of the following field types:
dense_vector, sparse_vector, string with full_text_search`.
type: object
additionalProperties:
$ref: '#/components/schemas/CreateIndexSchemaField'
minProperties: 1
required:
- fields
ReadCapacity:
description: >-
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.
discriminator:
propertyName: mode
mapping:
OnDemand:
$ref: '#/components/schemas/ReadCapacityOnDemandSpec'
Dedicated:
$ref: '#/components/schemas/ReadCapacityDedicatedSpec'
oneOf:
- $ref: '#/components/schemas/ReadCapacityOnDemandSpec'
- $ref: '#/components/schemas/ReadCapacityDedicatedSpec'
IndexTags:
nullable: true
example:
tag0: val0
tag1: val1
description: >-
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.
type: object
additionalProperties:
type: string
DeletionProtection:
description: >-
Whether [deletion
protection](http://docs.pinecone.io/guides/manage-data/manage-indexes#configure-deletion-protection)
is enabled/disabled for the index.
Possible values: `disabled` or `enabled`.
default: disabled
x-enum:
- disabled
- enabled
type: string
IndexDeployment:
description: >-
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.
discriminator:
propertyName: deployment_type
mapping:
pod:
$ref: '#/components/schemas/PodDeployment'
managed:
$ref: '#/components/schemas/ManagedDeployment'
byoc:
$ref: '#/components/schemas/ByocDeployment'
oneOf:
- $ref: '#/components/schemas/PodDeployment'
- $ref: '#/components/schemas/ManagedDeployment'
- $ref: '#/components/schemas/ByocDeployment'
ReadCapacityResponse:
description: Response containing read capacity configuration
discriminator:
propertyName: mode
mapping:
OnDemand:
$ref: '#/components/schemas/ReadCapacityOnDemandSpecResponse'
Dedicated:
$ref: '#/components/schemas/ReadCapacityDedicatedSpecResponse'
oneOf:
- $ref: '#/components/schemas/ReadCapacityOnDemandSpecResponse'
- $ref: '#/components/schemas/ReadCapacityDedicatedSpecResponse'
IndexSchema:
example:
fields:
embedding:
dimension: 1536
metric: cosine
type: dense_vector
title:
full_text_search:
language: en
stemming: false
stop_words: false
type: string
description: >-
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.
type: object
properties:
fields:
description: >-
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.
type: object
additionalProperties:
$ref: '#/components/schemas/IndexSchemaField'
required:
- fields
ManagedDeployment:
example:
cloud: aws
deployment_type: managed
region: us-east-1
title: Serverless
description: >-
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.
type: object
properties:
deployment_type:
description: >-
Identifies this as a managed (serverless) deployment. Must be
`managed`.
type: string
enum:
- managed
cloud:
example: aws
description: |-
The public cloud where the index is hosted.
Possible values: `gcp`, `aws`, or `azure`.
x-enum:
- gcp
- aws
- azure
type: string
region:
example: us-east-1
description: The region where the index is hosted.
type: string
environment:
readOnly: true
example: aped-4627-b74a
description: >-
The Pinecone environment hosting the index. Returned in responses;
do not set it when creating an index.
type: string
required:
- deployment_type
- cloud
- region
additionalProperties: false
ByocDeployment:
example:
deployment_type: byoc
environment: aws-us-east-1-b921
title: BYOC
description: Deployment configuration for a bring-your-own-compute (BYOC) index.
type: object
properties:
deployment_type:
description: Identifies this as a BYOC deployment. Must be `byoc`.
type: string
enum:
- byoc
environment:
example: aws-us-east-1-b921
description: The BYOC environment where the index is hosted.
type: string
required:
- deployment_type
- environment
additionalProperties: false
CreateIndexSchemaField:
description: >-
The configuration of a single field in the index schema at creation
time. The `type` property determines how the field is stored and
searched.
Field types accepted at creation time:
- `dense_vector`: Fixed-dimension floating-point vectors for ANN search.
- `sparse_vector`: Sparse vectors for keyword or hybrid search. -
`string` with a `full_text_search` object: String field for full-text
search.
Schema constraints enforced at creation time:
- At most one `dense_vector` field. - At most one `sparse_vector` field.
- At least one of `dense_vector`, `sparse_vector`, or a `string` field
with
`full_text_search` must be present.
Other field types seen in `IndexSchemaField` responses cannot be
declared here:
- `semantic_text` cannot be declared in a schema. Create an index with
an
integrated embedding model through the create-for-model operation instead;
it appears as a `semantic_text` field when the index is described.
- `float` (also spelled `number`), `boolean`, `string_list`, and
`string`
without `full_text_search` are metadata types and are rejected. Include the
values as document metadata and they are indexed for filtering automatically.
Every field accepts an optional `description` of at most 256 bytes.
discriminator:
propertyName: type
mapping:
dense_vector:
$ref: '#/components/schemas/DenseVectorField'
sparse_vector:
$ref: '#/components/schemas/SparseVectorField'
string:
$ref: '#/components/schemas/StringField'
oneOf:
- $ref: '#/components/schemas/DenseVectorField'
- $ref: '#/components/schemas/SparseVectorField'
- $ref: '#/components/schemas/StringField'
ReadCapacityOnDemandSpec:
example:
mode: OnDemand
title: On-demand
type: object
properties:
mode:
description: >-
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.
type: string
required:
- mode
ReadCapacityDedicatedSpec:
example:
dedicated:
manual:
replicas: 1
shards: 1
node_type: t1
scaling: Manual
mode: Dedicated
title: Dedicated
type: object
properties:
mode:
description: >-
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.
type: string
dedicated:
$ref: '#/components/schemas/ReadCapacityDedicatedConfig'
required:
- mode
- dedicated
PodDeployment:
example:
deployment_type: pod
environment: us-east1-gcp
pod_type: p1.x1
replicas: 1
shards: 1
title: Pod-based
description: Deployment configuration for a pod-based index.
type: object
properties:
deployment_type:
description: Identifies this as a pod-based deployment. Must be `pod`.
type: string
enum:
- pod
environment:
example: us-east1-gcp
description: The environment where the index is hosted.
type: string
replicas:
description: >-
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.
default: 1
type: integer
format: int32
minimum: 1
shards:
description: >-
The number of shards. Shards split your data across multiple pods so
you can fit more data into an index.
default: 1
type: integer
format: int32
minimum: 1
pod_type:
description: >-
The type of pod to use. One of `s1`, `p1`, or `p2` appended with `.`
and one of `x1`, `x2`, `x4`, or `x8`.
default: p1.x1
type: string
required:
- deployment_type
- environment
- pod_type
additionalProperties: false
ReadCapacityOnDemandSpecResponse:
example:
mode: OnDemand
status:
state: Ready
title: On-demand
type: object
properties:
mode:
description: >-
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.
type: string
status:
$ref: '#/components/schemas/ReadCapacityStatus'
required:
- mode
- status
additionalProperties: false
ReadCapacityDedicatedSpecResponse:
example:
dedicated:
manual:
replicas: 2
shards: 2
node_type: t1
scaling: Manual
mode: Dedicated
status:
current_replicas: 2
current_shards: 2
state: Ready
title: Dedicated
type: object
properties:
mode:
description: >-
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.
type: string
dedicated:
$ref: '#/components/schemas/ReadCapacityDedicatedConfig'
status:
$ref: '#/components/schemas/ReadCapacityStatus'
required:
- mode
- dedicated
- status
additionalProperties: false
IndexSchemaField:
description: >-
The configuration of a single field in the index schema.
Most fields carry a `type` property that identifies the field type:
- `dense_vector`: Fixed-dimension floating-point vectors for ANN search.
- `sparse_vector`: Sparse vectors for keyword or hybrid search. -
`semantic_text`: Text field backed by an integrated embedding model. -
`string`: String field for full-text search or metadata filtering. -
`string_list`: String array field. - `float`: Numeric field. -
`integer`: Legacy numeric field from older indexes (pre-dating float
normalization). Will not appear in new indexes.
- `boolean`: Boolean field.
Fields in older indexes may omit `type` entirely. These are legacy
metadata fields from before typed schemas were introduced.
anyOf:
- $ref: '#/components/schemas/TypedIndexSchemaField'
- $ref: '#/components/schemas/LegacyMetadataField'
DenseVectorField:
example:
dimension: 1536
metric: cosine
type: dense_vector
title: Dense vector
description: >-
A dense vector field configuration. Stores fixed-dimension
floating-point vectors for approximate nearest-neighbor (ANN) search.
type: object
properties:
type:
description: Identifies this as a dense vector field. Must be `dense_vector`.
type: string
enum:
- dense_vector
description:
nullable: true
description: >-
Optional description for this field, at most 256 bytes. `null` in
responses when none was set.
type: string
maxLength: 256
dimension:
example: 1536
description: The number of dimensions in the dense vectors stored in this field.
type: integer
format: int32
minimum: 1
maximum: 20000
metric:
example: cosine
description: |-
The distance metric used for similarity search.
Possible values: `cosine`, `dotproduct`, or `euclidean`.
x-enum:
- cosine
- dotproduct
- euclidean
type: string
required:
- type
- dimension
- metric
SparseVectorField:
example:
type: sparse_vector
title: Sparse vector
description: >-
A sparse vector field configuration. Stores sparse vectors for keyword
or hybrid search.
type: object
properties:
type:
description: Identifies this as a sparse vector field. Must be `sparse_vector`.
type: string
enum:
- sparse_vector
description:
nullable: true
description: >-
Optional description for this field, at most 256 bytes. `null` in
responses when none was set.
type: string
maxLength: 256
required:
- type
StringField:
example:
full_text_search:
language: en
type: string
title: String
description: >-
A string field configuration for full-text search. The
`full_text_search` object is required; a string field without it will be
rejected.
type: object
properties:
type:
description: Identifies this as a string field. Must be `string`.
type: string
enum:
- string
description:
description: Optional description for this field, at most 256 bytes.
type: string
maxLength: 256
full_text_search:
description: >-
Full-text search configuration. When present, the field is indexed
for full-text search.
`stop_words` requires `stemming: true`. `ngram` cannot be combined
with `stemming` or `stop_words`.
type: object
properties:
language:
example: en
description: >-
The language for text analysis. Defaults to `en` if not
specified.
default: en
type: string
stemming:
description: >-
Whether to apply stemming during text analysis. Defaults to
`false`.
default: false
type: boolean
stop_words:
description: >-
Whether to filter stop words during text analysis. Requires
`stemming: true`. Defaults to `false`.
default: false
type: boolean
ngram:
description: >-
Character n-gram tokenization for substring matching. When
present, the field is tokenized into character n-grams instead
of words. Cannot be combined with `stemming` or `stop_words`.
type: object
properties:
min_gram:
example: 2
description: >-
Minimum n-gram length. Must be at least 1 and no greater
than `max_gram`.
type: integer
minimum: 1
maximum: 10
max_gram:
example: 3
description: >-
Maximum n-gram length. Must be no less than `min_gram` and
at most 10.
type: integer
minimum: 1
maximum: 10
prefix_only:
description: >-
When `true`, only prefix n-grams anchored at the start of
the token are generated (e.g. for autocomplete). Defaults to
`false`.
default: false
type: boolean
required:
- min_gram
- max_gram
additionalProperties: false
additionalProperties: false
required:
- type
- full_text_search
additionalProperties: false
ReadCapacityDedicatedConfig:
description: >-
Configuration for dedicated read capacity. See [this
guide](https://docs.pinecone.io/guides/index-data/dedicated-read-nodes)
for more details on how to configure dedicated read capacity.
type: object
properties:
node_type:
description: >-
The type of machines to use. Available options: `b1` and `t1`. `t1`
includes increased processing power and memory.
type: string
scaling:
description: The type of scaling strategy to use.
type: string
manual:
$ref: '#/components/schemas/ScalingConfigManual'
required:
- node_type
- scaling
- manual
ReadCapacityStatus:
description: >-
The current status of factors affecting the read capacity of a
serverless index
type: object
properties:
state:
description: >-
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](https://docs.pinecone.io/reference/api/2026-07/control-plane/configure_index)
- `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.
x-enum:
- Ready
- Scaling
- Migrating
- Error
type: string
current_replicas:
nullable: true
description: >-
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.
type: integer
format: int32
current_shards:
nullable: true
description: >-
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.
type: integer
format: int32
error_message:
description: >-
An optional error message indicating any issues with your read
capacity configuration
type: string
required:
- state
TypedIndexSchemaField:
title: Typed field
description: >-
A schema field that carries a `type` discriminator. This covers all
field types in current use. See `IndexSchemaField` for the full union
that also includes legacy untyped fields.
discriminator:
propertyName: type
mapping:
dense_vector:
$ref: '#/components/schemas/DenseVectorField'
sparse_vector:
$ref: '#/components/schemas/SparseVectorField'
semantic_text:
$ref: '#/components/schemas/SemanticTextField'
string:
$ref: '#/components/schemas/ResponseStringField'
string_list:
$ref: '#/components/schemas/StringListField'
float:
$ref: '#/components/schemas/FloatField'
integer:
$ref: '#/components/schemas/IntegerField'
boolean:
$ref: '#/components/schemas/BooleanField'
oneOf:
- $ref: '#/components/schemas/DenseVectorField'
- $ref: '#/components/schemas/SparseVectorField'
- $ref: '#/components/schemas/SemanticTextField'
- $ref: '#/components/schemas/ResponseStringField'
- $ref: '#/components/schemas/StringListField'
- $ref: '#/components/schemas/FloatField'
- $ref: '#/components/schemas/IntegerField'
- $ref: '#/components/schemas/BooleanField'
LegacyMetadataField:
example:
filterable: true
title: Legacy metadata
description: >-
A legacy metadata field from indexes created before typed schema fields
were introduced. The original data type of the field (string, float,
boolean, etc.) was not recorded. Only the `filterable` flag is
available. This field type will not appear in new indexes; it may appear
in responses for older indexes pending schema migration.
type: object
properties:
filterable:
description: Whether this field is indexed for metadata filtering.
type: boolean
required:
- filterable
additionalProperties: false
ScalingConfigManual:
description: The config to use for manual read capacity scaling.
type: object
properties:
replicas:
description: >-
The number of replicas to use. Replicas duplicate the compute
resources and data of an index, allowing higher query throughput and
availability. Setting replicas to 0 disables the index but can be
used to reduce costs while usage is paused.
type: integer
format: int32
minimum: 0
shards:
description: >-
The number of shards to use. Shards determine the storage capacity
of an index, with each shard providing 250 GB of storage.
type: integer
format: int32
minimum: 1
required:
- replicas
- shards
SemanticTextField:
example:
model: multilingual-e5-large
type: semantic_text
title: Semantic text
description: >-
A semantic text field, as returned when describing an index created with
an integrated embedding model. Backed by an integrated embedding model
that embeds text at write and query time, enabling semantic similarity
search without separate embedding calls. Cannot be declared when
creating an index; use the create-for-model operation.
type: object
properties:
type:
description: Identifies this as a semantic text field. Must be `semantic_text`.
type: string
enum:
- semantic_text
description:
nullable: true
description: >-
Optional description for this field, at most 256 bytes. `null` in
responses when none was set.
type: string
maxLength: 256
model:
example: multilingual-e5-large
description: The name of the integrated embedding model to use for this field.
type: string
dimension:
nullable: true
example: 1024
description: >-
The dimension of the vectors the model produces. `null` for models
that produce sparse vectors.
type: integer
format: int32
metric:
example: cosine
description: >-
The distance metric used for similarity search. Defaults to the
model's preferred metric if not specified.
Possible values: `cosine`, `dotproduct`, or `euclidean`.
x-enum:
- cosine
- dotproduct
- euclidean
type: string
write_parameters:
nullable: true
example:
input_type: passage
description: >-
Model-specific parameters applied at write time, such as
`input_type`.
type: object
read_parameters:
nullable: true
example:
input_type: query
description: >-
Model-specific parameters applied at query time, such as
`input_type`.
type: object
required:
- type
- model
ResponseStringField:
example:
full_text_search:
language: en
stemming: false
stop_words: false
type: string
title: String
description: >-
A string field as returned in index schema responses. String fields
configured for full-text search include a `full_text_search` object;
string fields used for metadata filtering only include a `filterable`
flag.
type: object
properties:
type:
description: Identifies this as a string field. Must be `string`.
type: string
enum:
- string
description:
nullable: true
description: Optional description for this field. `null` when none was set.
type: string
full_text_search:
description: >-
Full-text search configuration. Present when the field is indexed
for full-text search.
type: object
properties:
language:
example: en
description: The language used for text analysis. Defaults to `en`.
default: en
type: string
stemming:
description: Whether stemming is applied during text analysis.
type: boolean
stop_words:
description: >-
Whether stop words are filtered during text analysis. Only
`true` if `stemming: true`.
type: boolean
ngram:
description: >-
Character n-gram tokenization configuration. Present only when
the field is configured for n-gram substring matching.
type: object
properties:
min_gram:
example: 2
description: Minimum n-gram length.
type: integer
max_gram:
example: 3
description: Maximum n-gram length.
type: integer
prefix_only:
description: >-
Whether only prefix n-grams anchored at the start of the
token are generated.
type: boolean
required:
- min_gram
- max_gram
- prefix_only
additionalProperties: false
required:
- language
- stemming
- stop_words
additionalProperties: false
filterable:
description: Whether this field is indexed for metadata filtering.
type: boolean
required:
- type
StringListField:
example:
filterable: true
type: string_list
title: String array
description: >-
A string array field configuration. String array values are not declared
in the index schema; include them as document metadata instead — they
are indexed automatically at upsert time.
type: object
properties:
type:
description: Identifies this as a string array field. Must be `string_list`.
type: string
enum:
- string_list
description:
nullable: true
description: Optional description for this field. `null` when none was set.
type: string
filterable:
description: Whether this field is indexed for metadata filtering.
type: boolean
required:
- type
FloatField:
example:
type: float
title: Float
description: >-
A numeric (floating-point) field configuration. Numeric values are not
declared in the index schema; include them as document metadata instead
— they are indexed automatically at upsert time.
type: object
properties:
type:
description: Identifies this as a float field. Must be `float`.
type: string
enum:
- float
description:
nullable: true
description: Optional description for this field. `null` when none was set.
type: string
filterable:
description: Whether this field is indexed for metadata filtering.
type: boolean
required:
- type
IntegerField:
example:
filterable: true
type: integer
title: Integer
description: >-
A legacy integer field configuration. Integer fields were used in older
index schemas before numeric values were normalized to `float` at upsert
time. New indexes will not produce this field type; it may appear in
responses for indexes created before that normalization was introduced.
type: object
properties:
type:
description: Identifies this as an integer field. Must be `integer`.
type: string
enum:
- integer
description:
nullable: true
description: Optional description for this field. `null` when none was set.
type: string
filterable:
description: Whether this field is indexed for metadata filtering.
type: boolean
required:
- type
BooleanField:
example:
type: boolean
title: Boolean
description: >-
A boolean field configuration. Boolean values are not declared in the
index schema; include them as document metadata instead — they are
indexed automatically at upsert time.
type: object
properties:
type:
description: Identifies this as a boolean field. Must be `boolean`.
type: string
enum:
- boolean
description:
nullable: true
description: Optional description for this field. `null` when none was set.
type: string
filterable:
description: Whether this field is indexed for metadata filtering.
type: boolean
required:
- type
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
````