> ## 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 an index for vectors created with an external embedding model.
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]"
# Serverless index
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"
)
# Pod-based index
from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec
pc = Pinecone(api_key="YOUR_API_KEY")
pc.create_index(
name="docs-example2",
dimension=1536,
metric="cosine",
spec=PodSpec(
environment="us-west1-gcp",
pod_type="p1.x1",
pods=1,
),
deletion_protection="disabled"
)
```
```javascript JavaScript theme={null}
// npm install @pinecone-database/pinecone
// Serverles index
import { Pinecone } from '@pinecone-database/pinecone'
const pc = new Pinecone({
apiKey: 'YOUR_API_KEY'
});
await pc.createIndex({
name: 'serverless-index',
dimension: 1536,
metric: 'cosine',
spec: {
serverless: {
cloud: 'aws',
region: 'us-east-1'
}
},
deletionProtection: 'disabled',
});
// Pod-based index
await pc.createIndex({
name: 'docs-example2',
dimension: 1536,
metric: 'cosine',
spec: {
pod: {
environment: 'us-west1-gcp',
podType: 'p1.x1',
pods: 1
}
},
deletionProtection: 'disabled',
});
```
```java Java theme={null}
import io.pinecone.clients.Pinecone;
import org.openapitools.db_control.client.model.IndexModel;
import org.openapitools.db_control.client.model.DeletionProtection;
// Serverless index
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);
}
}
// Pod-based index
public class CreatePodIndexExample {
public static void main(String[] args) {
Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
pc.createPodsIndex("docs-example2", 1536, "us-west1-gcp",
"p1.x1", "cosine", DeletionProtection.disabled);
}
}
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"github.com/pinecone-io/go-pinecone/v2/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
// Serverless index
idx1, 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", idx1.Name)
} else {
fmt.Printf("Successfully created serverless index: %v", idx1.Name)
}
// Pod-based index
idx2, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{
Name: "docs-example2",
Dimension: 1536,
Metric: pinecone.Cosine,
Environment: "us-east1-gcp",
PodType: "p1.x1",
DeletionProtection: &deletionProtection,
})
if err != nil {
log.Fatalf("Failed to create pod-based index: %v", idx2.Name)
} else {
fmt.Printf("Successfully created pod-based index: %v", idx2.Name)
}
}
```
```csharp C# theme={null}
using Pinecone;
var pinecone = new PineconeClient("YOUR_API_KEY");
// Serverless index
var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest
{
Name = "docs-example1",
Dimension = 1536,
Metric = CreateIndexRequestMetric.Cosine,
Spec = new ServerlessIndexSpec
{
Serverless = new ServerlessSpec
{
Cloud = ServerlessSpecCloud.Aws,
Region = "us-east-1",
}
},
DeletionProtection = DeletionProtection.Disabled
});
// Pod-based index
var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest
{
Name = "pod index",
Dimension = 1536,
Metric = CreateIndexRequestMetric.Cosine,
Spec = new PodIndexSpec
{
Pod = new PodSpec
{
Environment = "us-east1-gcp",
PodType = "p1.x1",
Pods = 1,
}
},
DeletionProtection = DeletionProtection.Disabled
});
```
```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
# Serverless index
curl -s 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: 2024-07" \
-d '{
"name": "serverless-index",
"dimension": 1536,
"metric": "cosine",
"spec": {
"serverless": {
"cloud": "aws",
"region": "us-east-1"
}
},
"deletion_protection": "disabled"
}'
# Pod-based index
curl -s 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: 2024-07" \
-d '{
"name": "pod-index",
"dimension": 1536,
"metric": "cosine",
"spec": {
"pod": {
"environment": "us-west1-gcp",
"pod_type": "p1.x1",
"pods": 1
}
},
"deletion_protection": "disabled"
}'
```
```jsonc curl theme={null}
# Serverless index
{
"name": "docs-example1",
"metric": "cosine",
"dimension": 1536,
"status": {
"ready": true,
"state": "Ready"
},
"host": "docs-example1-4zo0ijk.svc.dev-us-west2-aws.pinecone.io",
"spec": {
"serverless": {
"region": "us-east-1",
"cloud": "aws"
}
}
}
# Pod-based index
{
"name": "docs-example2",
"metric": "cosine",
"dimension": 1536,
"status": {
"ready": true,
"state": "Ready"
},
"host": "docs-example2-4zo0ijk.svc.us-west1-gcp.pinecone.io",
"spec": {
"pod": {
"replicas": 1,
"shards": 1,
"pods": 1,
"pod_type": "p1.x1",
"environment": "us-west1-gcp"
}
}
}
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2024-07/control_2024-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: 2024-07
servers:
- url: https://api.pinecone.io
description: Production API endpoints
security:
- ApiKeyAuth: []
tags:
- name: Inference
description: Generate embeddings for input data.
- 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 an index for vectors created with an external embedding model.
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
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 on metric.
value:
error:
code: INVALID_ARGUMENT
message: Metric must be cosine, euclidean, or dotproduct.
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
'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'.
default: cosine
type: string
enum:
- cosine
- euclidean
- dotproduct
deletion_protection:
$ref: '#/components/schemas/DeletionProtection'
spec:
$ref: '#/components/schemas/IndexSpec'
required:
- name
- dimension
- 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'.
default: 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
deletion_protection:
$ref: '#/components/schemas/DeletionProtection'
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:
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
required:
- ready
- state
required:
- name
- dimension
- metric
- status
- spec
- host
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
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
IndexSpec:
description: >
The spec object defines how the index should be deployed.
For serverless indexes, you define 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 define 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.
type: object
properties:
serverless:
$ref: '#/components/schemas/ServerlessSpec'
pod:
$ref: '#/components/schemas/PodSpec'
additionalProperties: false
oneOf:
- required:
- serverless
- required:
- pod
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
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/).
````