> ## 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. This is where you specify the measure of similarity, the dimension of vectors to be stored in the index, which cloud provider you would like to deploy with, and more.
For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index).
```python Python theme={null}
# pip install "pinecone[grpc]"
from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec
pc = Pinecone(api_key="YOUR_API_KEY")
pc.create_index(
name="docs-example1",
dimension=1536,
metric="cosine",
spec=ServerlessSpec(
cloud="aws",
region="us-east-1",
),
deletion_protection="disabled"
)
```
```javascript JavaScript theme={null}
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone'
const pc = new Pinecone({
apiKey: 'YOUR_API_KEY'
});
await pc.createIndex({
name: 'docs-example1',
dimension: 1536,
metric: 'cosine',
spec: {
serverless: {
cloud: 'aws',
region: 'us-east-1'
}
},
deletionProtection: 'disabled',
});
```
```java Java theme={null}
import io.pinecone.clients.Pinecone;
public class CreateServerlessIndexExample {
public static void main(String[] args) {
Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
pc.createServerlessIndex("docs-example1", "cosine", 1536, "aws", "us-east-1", DeletionProtection.disabled);
}
}
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"github.com/pinecone-io/go-pinecone/v4/pinecone"
)
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: "YOUR_API_KEY",
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
deletionProtection := pinecone.DeletionProtectionDisabled
idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{
Name: "docs-example1",
Dimension: 1536,
Metric: pinecone.Cosine,
Cloud: pinecone.Aws,
Region: "us-east-1",
DeletionProtection: &deletionProtection,
})
if err != nil {
log.Fatalf("Failed to create serverless index: %v", err)
} else {
fmt.Printf("Successfully created serverless index: %v", idx.Name)
}
}
```
```csharp C# theme={null}
using Pinecone;
var pinecone = new PineconeClient("YOUR_API_KEY");
var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest
{
Name = "docs-example1",
Dimension = 1536,
Metric = MetricType.Cosine,
Spec = new ServerlessIndexSpec
{
Serverless = new ServerlessSpec
{
Cloud = ServerlessSpecCloud.Aws,
Region = "us-east-1",
}
},
DeletionProtection = DeletionProtection.Disabled
});
```
```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
# Serverless index
curl -X POST "https://api.pinecone.io/indexes" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2025-04" \
-d '{
"name": "docs-example1",
"vector_type": "dense",
"dimension": 1536,
"metric": "cosine",
"spec": {
"serverless": {
"cloud": "aws",
"region": "us-east-1"
}
},
"tags": {
"example": "tag"
},
"deletion_protection": "disabled"
}'
# BYOC index
curl -X POST"https://api.pinecone.io/indexes" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2025-04" \
-d '{
"name": "example-byoc-index",
"vector_type": "dense",
"dimension": 1536,
"metric": "cosine",
"spec": {
"byoc": {
"environment": "aws-us-east-1-b921"
}
},
"tags": {
"example": "tag"
},
"deletion_protection": "disabled"
}'
```
```bash CLI theme={null}
# Target the project where you'd like to create the index.
pc target -o "example-org" -p "example-project"
# Create the index.
pc index create \
--name "docs-example1" \
--dimension 1536 \
--metric "cosine" \
--cloud "aws" \
--region "us-east-1" \
--deletion_protection "disabled" \
--tags "example=tag,example2=tag2"
```
```shell Response theme={null}
# Serverless index
{
"name": "docs-example1",
"vector_type": "dense",
"metric": "cosine",
"dimension": 1536,
"status": {
"ready": true,
"state": "Ready"
},
"host": "example-serverless-index-govk0nt.svc.aped-4627-b74a.pinecone.io",
"spec": {
"serverless": {
"region": "us-east-1",
"cloud": "aws"
}
},
"deletion_protection": "disabled",
"tags": {
"example": "tag"
}
}
# BYOC index
{
"name": "example-byoc-index",
"vector_type": "dense",
"metric": "cosine",
"dimension": 1536,
"status": {
"ready": true,
"state": "Ready"
},
"host": "example-byoc-index-govk0nt.svc.private.aped-4627-b74a.pinecone.io",
"spec": {
"byoc": {
"environment": "aws-us-east-1-b921"
}
},
"deletion_protection": "disabled",
"tags": {
"example": "tag"
}
}
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-04/db_control_2025-04.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: 2025-04
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. This is where you specify the measure of
similarity, the dimension of vectors to be stored in the index, which
cloud provider you would like to deploy with, and more.
For guidance and examples, see [Create an
index](https://docs.pinecone.io/guides/index-data/create-an-index).
operationId: create_index
requestBody:
description: The desired configuration for the index.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIndexRequest'
examples:
serverless-index:
summary: Creating a serverless index
value:
deletion_protection: enabled
dimension: 1536
metric: cosine
name: movie-recommendations
spec:
serverless:
cloud: gcp
region: us-east1
source_collection: movie-embeddings
serverless-sparse-index:
summary: Creating a sparse serverless index
value:
deletion_protection: enabled
metric: dotproduct
name: sparse-index
spec:
serverless:
cloud: gcp
region: us-east1
vector_type: sparse
pod-index:
summary: Creating a pod-based index
value:
deletion_protection: enabled
dimension: 1536
metric: cosine
name: movie-recommendations
spec:
pod:
environment: us-east-1-aws
metadata_config:
indexed:
- genre
- title
- imdb_rating
pod_type: p1.x1
pods: 1
replicas: 1
shards: 1
source_collection: movie-embeddings
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.
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
dimension:
example: 1536
description: The dimensions of the vectors to be inserted in the index.
type: integer
format: int32
minimum: 1
maximum: 20000
metric:
description: >-
The distance metric to be used for similarity search. You can use
'euclidean', 'cosine', or 'dotproduct'. If the 'vector_type' is
'sparse', the metric must be 'dotproduct'. If the `vector_type` is
`dense`, the metric defaults to 'cosine'.
type: string
enum:
- cosine
- euclidean
- dotproduct
deletion_protection:
$ref: '#/components/schemas/DeletionProtection'
tags:
$ref: '#/components/schemas/IndexTags'
spec:
$ref: '#/components/schemas/IndexSpec'
vector_type:
description: >-
The index vector type. You can use 'dense' or 'sparse'. If 'dense',
the vector dimension must be specified. If 'sparse', the vector
dimension should not be specified.
default: dense
type: string
required:
- name
- spec
IndexModel:
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
dimension:
example: 1536
description: The dimensions of the vectors to be inserted in the index.
type: integer
format: int32
minimum: 1
maximum: 20000
metric:
description: >-
The distance metric to be used for similarity search. You can use
'euclidean', 'cosine', or 'dotproduct'. If the 'vector_type' is
'sparse', the metric must be 'dotproduct'. If the `vector_type` is
`dense`, the metric defaults to 'cosine'.
type: string
enum:
- cosine
- euclidean
- dotproduct
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
deletion_protection:
$ref: '#/components/schemas/DeletionProtection'
tags:
$ref: '#/components/schemas/IndexTags'
embed:
$ref: '#/components/schemas/ModelIndexEmbed'
spec:
example:
pod:
environment: us-east-1-aws
metadata_config:
indexed:
- genre
- title
- imdb_rating
pod_type: p1.x1
pods: 1
replicas: 1
shards: 1
type: object
properties:
byoc:
$ref: '#/components/schemas/ByocSpec'
pod:
$ref: '#/components/schemas/PodSpec'
serverless:
$ref: '#/components/schemas/ServerlessSpec'
status:
example:
ready: true
state: ScalingUpPodSize
type: object
properties:
ready:
type: boolean
state:
type: string
enum:
- Initializing
- InitializationFailed
- ScalingUp
- ScalingDown
- ScalingUpPodSize
- ScalingDownPodSize
- Terminating
- Ready
- Disabled
required:
- ready
- state
vector_type:
description: >-
The index vector type. You can use 'dense' or 'sparse'. If 'dense',
the vector dimension must be specified. If 'sparse', the vector
dimension should not be specified.
default: dense
type: string
required:
- name
- metric
- status
- spec
- host
- vector_type
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:
type: string
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
message:
example: >-
Index name must contain only lowercase alphanumeric characters
or hyphens, and must not begin or end with a hyphen.
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
DeletionProtection:
description: >
Whether [deletion
protection](http://docs.pinecone.io/guides/manage-data/manage-indexes#configure-deletion-protection)
is enabled/disabled for the index.
default: disabled
type: string
enum:
- disabled
- enabled
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
IndexSpec:
description: >
The spec object defines how the index should be deployed.
For serverless indexes, you set only the [cloud and
region](http://docs.pinecone.io/guides/index-data/create-an-index#cloud-regions)
where the index should be hosted. For pod-based indexes, you set the
[environment](http://docs.pinecone.io/guides/indexes/pods/understanding-pod-based-indexes#pod-environments)
where the index should be hosted, the [pod type and
size](http://docs.pinecone.io/guides/indexes/pods/understanding-pod-based-indexes#pod-types)
to use, and other index characteristics. For [BYOC
indexes](http://docs.pinecone.io/guides/production/bring-your-own-cloud),
you set the environment name provided to you during onboarding.
type: object
properties:
serverless:
$ref: '#/components/schemas/ServerlessSpec'
pod:
$ref: '#/components/schemas/PodSpec'
byoc:
$ref: '#/components/schemas/ByocSpec'
additionalProperties: false
oneOf:
- required:
- serverless
- required:
- pod
- required:
- byoc
ModelIndexEmbed:
example:
field_map:
text: your-text-field
metric: cosine
model: multilingual-e5-large
read_parameters:
input_type: query
truncate: NONE
write_parameters:
input_type: passage
description: The embedding model and document fields mapped to embedding inputs.
type: object
properties:
model:
example: multilingual-e5-large
description: The name of the embedding model used to create the index.
type: string
metric:
description: >-
The distance metric to be used for similarity search. You can use
'euclidean', 'cosine', or 'dotproduct'. If not specified, the metric
will be defaulted according to the model. Cannot be updated once
set.
type: string
enum:
- cosine
- euclidean
- dotproduct
dimension:
example: 1536
description: The dimensions of the vectors to be inserted in the index.
type: integer
format: int32
minimum: 1
maximum: 20000
vector_type:
description: >-
The index vector type. You can use 'dense' or 'sparse'. If 'dense',
the vector dimension must be specified. If 'sparse', the vector
dimension should not be specified.
default: dense
type: string
field_map:
example:
text: your-text-field
description: >-
Identifies the name of the text field from your document model that
is embedded.
type: object
read_parameters:
description: The read parameters for the embedding model.
type: object
write_parameters:
description: The write parameters for the embedding model.
type: object
required:
- model
ByocSpec:
example:
environment: aws-us-east-1-b921
description: Configuration needed to deploy an index in a BYOC environment.
type: object
properties:
environment:
example: aws-us-east-1-b921
description: The environment where the index is hosted.
type: string
required:
- environment
PodSpec:
example:
environment: us-east1-gcp
metadata_config:
indexed:
- genre
- title
- imdb_rating
pod_type: p1.x1
pods: 1
replicas: 1
shards: 1
source_collection: movie-embeddings
description: Configuration needed to deploy a pod-based index.
type: object
properties:
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
pods:
example: 1
description: >-
The number of pods to be used in the index. This should be equal to
`shards` x `replicas`.'
default: 1
type: integer
minimum: 1
metadata_config:
example:
indexed:
- genre
- title
- imdb_rating
description: >-
Configuration for the behavior of Pinecone's internal metadata
index. By default, all metadata is indexed; when `metadata_config`
is present, only specified metadata fields are indexed. These
configurations are only valid for use with pod-based indexes.
type: object
properties:
indexed:
description: >-
By default, all metadata is indexed; to change this behavior,
use this property to specify an array of metadata fields that
should be indexed.
type: array
items:
type: string
source_collection:
example: movie-embeddings
description: The name of the collection to be used as the source for the index.
type: string
required:
- environment
- pod_type
ServerlessSpec:
description: Configuration needed to deploy a serverless index.
type: object
properties:
cloud:
example: aws
description: The public cloud where you would like your index hosted.
type: string
enum:
- gcp
- aws
- azure
region:
example: us-east-1
description: The region where you would like your index to be created.
type: string
source_collection:
type: string
description: The name of the collection to be used as the source for the index.
required:
- cloud
- region
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/).
````