> ## 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 — including vector fields, semantic text fields, and metadata fields — and the deployment infrastructure (managed serverless or BYOC).
**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.
For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index).
[Full-text search](/guides/search/full-text-search) is in [public
preview](/release-notes/feature-availability) and uses API version
`2026-01.alpha`. APIs may continue to evolve before general availability.
Creates a new schema-defined index for [full-text search](/guides/search/full-text-search). The index initializes asynchronously; poll [`GET /indexes/{index_name}`](/reference/api/2026-01.alpha/control-plane/describe_index) until `status.ready: true` (and, for `Dedicated` read capacity, `read_capacity.status.state: "Ready"`) before performing data plane operations.
Document-shaped 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).
```python Python theme={null}
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
from pinecone.preview import 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.preview.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-01.alpha" \
-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-01.alpha" \
-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)
# Metadata fields like `category`, `tags`, and `year` are NOT declared in the schema —
# upsert them on documents and Pinecone auto-indexes them for filtering.
curl "https://api.pinecone.io/indexes" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-01.alpha" \
-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" }
}
}
}'
```
```jsonc curl theme={null}
// Status: 201 Created
{
"id": "e51ea4e1-2dda-4607-94dc-9054b1fa8492",
"name": "articles",
"host": "articles-jweaq8m.svc.aped-4627-b74a.pinecone.io",
"status": {
"ready": false,
"state": "Initializing"
},
"deployment": {
"deployment_type": "managed",
"cloud": "aws",
"region": "us-east-1",
"environment": "aped-4627-b74a"
},
"schema": {
"version": "v1",
"fields": {
"title": { "type": "string", "full_text_search": { "language": "en", "stemming": false, "stop_words": false, "lowercase": true, "max_token_length": 40 } },
"body": { "type": "string", "full_text_search": { "language": "en", "stemming": false, "stop_words": false, "lowercase": true, "max_token_length": 40 } }
}
},
"read_capacity": {
"mode": "OnDemand",
"status": { "state": "Ready" }
},
"tags": null,
"deletion_protection": "disabled"
}
```
Responses show the full resolved analyzer config for each `full_text_search` field. `language`, `stemming`, and `stop_words` reflect request settings or defaults; `lowercase` and `max_token_length` are server-applied and cannot be overridden.
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-01.alpha/db_control_2026-01.alpha.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-01.alpha
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 — including
vector fields, semantic text fields, and metadata fields — and the
deployment infrastructure (managed serverless or BYOC).
**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.
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-01.alpha
type: string
style: simple
requestBody:
description: The desired configuration for the index.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIndexRequest'
examples:
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
semantic-text-serverless:
summary: Semantic text index with integrated embedding
value:
deployment:
cloud: aws
deployment_type: managed
region: us-east-1
name: semantic-index
schema:
fields:
content:
model: multilingual-e5-large
type: semantic_text
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: Invalid API key.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Unauthorized
value:
error:
code: UNAUTHENTICATED
message: Invalid API key.
status: 401
'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: You've exceed your pod quota.
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: Cannot create serverless index with invalid spec.
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
'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'
source_collection:
example: movie-embeddings
description: >-
The name of a collection from which to create the index. The
collection must have been created from a pod-based index with a
compatible schema.
type: string
source_backup_id:
example: 670e8400-e29b-41d4-a716-446655440000
description: >-
The ID of a backup from which to restore the index. Mutually
exclusive with `source_collection`.
type: string
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.
type: string
read_capacity:
$ref: '#/components/schemas/ReadCapacity'
tags:
$ref: '#/components/schemas/IndexTags'
deletion_protection:
$ref: '#/components/schemas/DeletionProtection'
required:
- schema
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`,
`ScalingUp`, `ScalingDown`, `ScalingUpPodSize`,
`ScalingDownPodSize`, `Terminating`, `Ready`, or `Disabled`.
x-enum:
- Initializing
- InitializationFailed
- ScalingUp
- ScalingDown
- ScalingUpPodSize
- ScalingDownPodSize
- 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: QUOTA_EXCEEDED
message: >-
The index exceeds the project quota of 5 pods by 2 pods. Upgrade
your account or change the project settings to increase the quota.
status: 429
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`, `QUOTA_EXCEEDED`, `NOT_FOUND`,
`ALREADY_EXISTS`, `PERMISSION_DENIED`, `UNAUTHENTICATED`,
`RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`,
`OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`,
`DATA_LOSS`, `FORBIDDEN`, `UNPROCESSABLE_ENTITY`, or
`PAYMENT_REQUIRED`.
x-enum:
- OK
- UNKNOWN
- INVALID_ARGUMENT
- DEADLINE_EXCEEDED
- QUOTA_EXCEEDED
- NOT_FOUND
- ALREADY_EXISTS
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- FAILED_PRECONDITION
- ABORTED
- OUT_OF_RANGE
- UNIMPLEMENTED
- INTERNAL
- UNAVAILABLE
- DATA_LOSS
- FORBIDDEN
- UNPROCESSABLE_ENTITY
- PAYMENT_REQUIRED
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
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.
- `pod`: Dedicated pod-based infrastructure. - `managed`: Serverless
infrastructure managed by Pinecone, including
full-text search indexes.
- `byoc`: Bring-your-own-compute.
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'
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 typed
fields that documents in the index can contain, including vector fields,
semantic text fields, and metadata fields.
At least one primary field (`dense_vector`, `sparse_vector`,
`semantic_text`, or a `string` field with `full_text_search`) must be
present.
type: object
properties:
fields:
description: >-
A map of field names to their configurations. Field names must be
unique, non-empty strings and must not use the reserved names `_id`,
`_values`, or `_sparse_values`.
type: object
additionalProperties:
$ref: '#/components/schemas/CreateIndexSchemaField'
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`.
discriminator:
propertyName: mode
mapping:
OnDemand:
$ref: '#/components/schemas/ReadCapacityOnDemandSpec'
Dedicated:
$ref: '#/components/schemas/ReadCapacityDedicatedSpec'
oneOf:
- $ref: '#/components/schemas/ReadCapacityOnDemandSpec'
- $ref: '#/components/schemas/ReadCapacityDedicatedSpec'
IndexTags:
example:
tag0: val0
tag1: val1
description: >-
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.
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. Field names must be
unique, non-empty strings and must not use the reserved names `_id`,
`_values`, or `_sparse_values`.
type: object
additionalProperties:
$ref: '#/components/schemas/IndexSchemaField'
required:
- fields
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
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
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.
Supported field types:
- `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 (use `full_text_search`
object)
or metadata filtering.
- `string_list`: String array field for metadata filtering. - `float`:
Numeric field for metadata filtering. Also accepts `"number"` as the
type value. - `boolean`: Boolean field for metadata filtering.
Schema constraints enforced at creation time:
- At most one `dense_vector` field. - At most one `sparse_vector` field.
- At most one `semantic_text` field; `semantic_text` cannot be combined
with
`dense_vector`, `sparse_vector`, or full-text search string fields.
- At least one primary field (`dense_vector`, `sparse_vector`,
`semantic_text`,
or a `string` field with `full_text_search`) must be present.
- Only `dense_vector`, `sparse_vector`, `semantic_text`, and `string`
with
`full_text_search` are accepted. The types `float`, `boolean`,
`string_list`, and `string` without `full_text_search` are not supported
and will be rejected. Include those values as document metadata instead —
they are indexed automatically at upsert time.
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/StringField'
string_list:
$ref: '#/components/schemas/StringListField'
float:
$ref: '#/components/schemas/FloatField'
boolean:
$ref: '#/components/schemas/BooleanField'
oneOf:
- $ref: '#/components/schemas/DenseVectorField'
- $ref: '#/components/schemas/SparseVectorField'
- $ref: '#/components/schemas/SemanticTextField'
- $ref: '#/components/schemas/StringField'
- $ref: '#/components/schemas/StringListField'
- $ref: '#/components/schemas/FloatField'
- $ref: '#/components/schemas/BooleanField'
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
additionalProperties: false
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
additionalProperties: true
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
dimension:
example: 1536
description: The number of dimensions in the dense vectors stored in this field.
type: integer
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
required:
- type
SemanticTextField:
example:
model: multilingual-e5-large
type: semantic_text
title: Semantic text
description: >-
A semantic text field configuration. Backed by an integrated embedding
model that embeds text at write and query time, enabling semantic
similarity search without separate embedding calls.
type: object
properties:
type:
description: Identifies this as a semantic text field. Must be `semantic_text`.
type: string
enum:
- semantic_text
model:
example: multilingual-e5-large
description: The name of the integrated embedding model to use for this field.
type: string
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:
example:
input_type: passage
description: >-
Model-specific parameters applied at write time, such as
`input_type`.
type: object
read_parameters:
example:
input_type: query
description: >-
Model-specific parameters applied at query time, such as
`input_type`.
type: object
required:
- type
- model
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.
type: string
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
additionalProperties: false
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:
description: Optional description for this field.
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:
description: Optional description for this field.
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:
description: Optional description for this field.
type: string
filterable:
description: Whether this field is indexed for metadata filtering.
type: boolean
required:
- type
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'
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-04/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.
type: string
current_replicas:
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.
type: integer
format: int32
current_shards:
description: >-
The number of shards. Each shard has dedicated storage. Increasing
shards alleiviates index fullness.
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
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:
description: Optional description for this field.
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
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:
description: Optional description for this field.
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/).
````