> ## 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="serverless-index",
dimension=1536,
metric="cosine",
spec=ServerlessSpec(
cloud="aws",
region="us-east-1"
)
)
# Pod-based index
from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec
pc = Pinecone(api_key="YOUR_API_KEY")
pc.create_index(
name="pod-index",
dimension=1536,
metric="cosine",
spec=PodSpec(
environment="us-west1-gcp",
pod_type="p1.x1",
pods=1
)
)
```
```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'
}
}
});
// Pod-based index
await pc.createIndex({
name: 'pod-index',
dimension: 1536,
metric: 'cosine',
spec: {
pod: {
environment: 'us-west1-gcp',
podType: 'p1.x1',
pods: 1
}
}
});
```
```java Java theme={null}
import io.pinecone.clients.Pinecone;
// Serverless index
public class CreateServerlessIndexExample {
public static void main(String[] args) {
Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
pc.createServerlessIndex("serverless-index", "cosine", 1536, "aws", "us-east-1");
}
}
// Pod-based index
public class CreatePodIndexExample {
public static void main(String[] args) {
Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
pc.createPodsIndex("pod-index", 1536, "us-west1-gcp",
"p1.x1", "cosine");
}
}
```
```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-04" \
-d '{
"name": "serverless-index",
"dimension": 1536,
"metric": "cosine",
"spec": {
"serverless": {
"cloud": "aws",
"region": "us-east-1"
}
}
}'
# 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-04" \
-d '{
"name": "pod-index",
"dimension": 1536,
"metric": "cosine",
"spec": {
"pod": {
"environment": "us-west1-gcp",
"pod_type": "p1.x1",
"pods": 1
}
}
}'
```
```jsonc curl theme={null}
# Serverless index
{
"name": "serverless-index",
"metric": "cosine",
"dimension": 1536,
"status": {
"ready": true,
"state": "Ready"
},
"host": "serverless-index-4zo0ijk.svc.dev-us-west2-aws.pinecone.io",
"spec": {
"serverless": {
"region": "us-east-1",
"cloud": "aws"
}
}
}
# Pod-based index
{
"name": "pod-index",
"metric": "cosine",
"dimension": 1536,
"status": {
"ready": true,
"state": "Ready"
},
"host": "pod-index-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-04/control_2024-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.
version: 2024-04
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
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:
servers:
- url: https://api.pinecone.io
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.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIndexRequest'
examples:
serverless-index:
summary: Creating a serverless index
value:
name: movie-recommendations
dimension: 1536
metric: cosine
spec:
serverless:
cloud: gcp
region: us-east1
pod-index:
summary: Creating a pod-based index
value:
name: movie-recommendations
dimension: 1536
metric: cosine
spec:
pod:
environment: us-east-1-aws
replicas: 1
shards: 1
pod_type: p1.x1
pods: 1
metadata_config:
indexed:
- genre
- title
- imdb_rating
source_collection: movie-embeddings
responses:
'201':
description: The index has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/IndexModel'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403PodQuotaExceeded'
'404':
$ref: '#/components/responses/404ServerlessSpecNotFound'
'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:
status: 409
error:
code: ALREADY_EXISTS
message: Resource already exists.
'422':
$ref: '#/components/responses/422UnprocessableEntity'
'500':
$ref: '#/components/responses/500InternalServerError'
components:
schemas:
CreateIndexRequest:
type: object
description: The configuration needed to create a Pinecone index.
required:
- name
- dimension
- spec
properties:
name:
$ref: '#/components/schemas/IndexName'
dimension:
$ref: '#/components/schemas/IndexDimension'
metric:
$ref: '#/components/schemas/IndexMetric'
spec:
type: object
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/indexing-overview#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.
additionalProperties: false
properties:
serverless:
$ref: '#/components/schemas/ServerlessSpec'
pod:
type: object
description: Configuration needed to deploy a pod-based index.
required:
- environment
- pod_type
properties:
environment:
type: string
description: The environment where the index is hosted.
example: us-east1-gcp
replicas:
$ref: '#/components/schemas/PodSpecReplicas'
pod_type:
$ref: '#/components/schemas/PodSpecPodType'
pods:
type: integer
description: >-
The number of pods to be used in the index. This should be
equal to `shards` x `replicas`.
example: 1
minimum: 1
shards:
$ref: '#/components/schemas/PodSpecShards'
metadata_config:
type: object
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.
properties:
indexed:
type: array
description: >-
By default, all metadata is indexed; to change this
behavior, use this property to specify an array of
metadata fields which should be indexed.
items:
type: string
example:
indexed:
- genre
- title
- imdb_rating
source_collection:
type: string
description: >-
The name of the collection to be used as the source for the
index.
example: movie-embeddings
oneOf:
- required:
- serverless
- required:
- pod
IndexModel:
type: object
description: >-
The IndexModel describes the configuration and status of a Pinecone
index.
required:
- name
- dimension
- metric
- status
- spec
- host
properties:
name:
$ref: '#/components/schemas/IndexName'
dimension:
$ref: '#/components/schemas/IndexDimension'
metric:
$ref: '#/components/schemas/IndexMetric'
host:
$ref: '#/components/schemas/IndexHost'
spec:
type: object
properties:
pod:
$ref: '#/components/schemas/PodSpec'
serverless:
$ref: '#/components/schemas/ServerlessSpec'
example:
pod:
environment: us-east-1-aws
replicas: 1
shards: 1
pod_type: p1.x1
pods: 1
metadata_config:
indexed:
- genre
- title
- imdb_rating
status:
type: object
required:
- ready
- state
example:
ready: true
state: ScalingUpPodSize
properties:
ready:
type: boolean
state:
type: string
enum:
- Initializing
- InitializationFailed
- ScalingUp
- ScalingDown
- ScalingUpPodSize
- ScalingDownPodSize
- Terminating
- Ready
ErrorResponse:
type: object
description: The response shape used for all error responses.
required:
- status
- error
properties:
status:
type: integer
description: The HTTP status code of the error.
example: 500
error:
type: object
description: Detailed information about the error that occurred.
required:
- code
- message
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
message:
type: string
example: >-
Index name must contain only lowercase alphanumeric characters
or hyphens, and must not begin or end with a hyphen.
details:
description: >-
Additional information about the error. This field is not
guaranteed to be present.
type: object
example:
code: INVALID_ARGUMENT
message: >-
Index name must contain only lowercase alphanumeric characters or
hyphens, and must not begin or end with a hyphen.
example:
status: 429
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.
IndexName:
type: string
minLength: 1
maxLength: 45
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 '-'.
example: example-index
IndexDimension:
type: integer
description: The dimensions of the vectors to be inserted in the index.
minimum: 1
maximum: 20000
example: 1536
format: int32
IndexMetric:
type: string
description: >-
The distance metric to be used for similarity search. You can use
'euclidean', 'cosine', or 'dotproduct'.
enum:
- cosine
- euclidean
- dotproduct
default: cosine
ServerlessSpec:
type: object
required:
- cloud
- region
description: Configuration needed to deploy a serverless index.
properties:
cloud:
type: string
enum:
- gcp
- aws
- azure
description: The public cloud where you would like your index hosted.
example: aws
region:
type: string
description: 'The region where you would like your index to be created. '
example: us-east-1
PodSpecReplicas:
type: integer
format: int32
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
minimum: 1
PodSpecPodType:
type: string
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
PodSpecShards:
type: integer
format: int32
description: >-
The number of shards. Shards split your data across multiple pods so you
can fit more data into an index.
default: 1
minimum: 1
IndexHost:
type: string
description: The URL address where the index is hosted.
example: semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io
PodSpec:
type: object
description: Configuration needed to deploy a pod-based index.
required:
- environment
- pods
- replicas
- shards
- pod_type
example:
environment: us-east1-gcp
replicas: 1
shards: 1
pod_type: p1.x1
pods: 1
metadata_config:
indexed:
- genre
- title
- imdb_rating
source_collection: movie-embeddings
properties:
environment:
type: string
description: The environment where the index is hosted.
example: us-east1-gcp
replicas:
$ref: '#/components/schemas/PodSpecReplicas'
shards:
$ref: '#/components/schemas/PodSpecShards'
pod_type:
$ref: '#/components/schemas/PodSpecPodType'
pods:
type: integer
description: >-
The number of pods to be used in the index. This should be equal to
`shards` x `replicas`.'
default: 1
example: 1
minimum: 1
metadata_config:
type: object
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.
properties:
indexed:
type: array
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.
items:
type: string
example:
indexed:
- genre
- title
- imdb_rating
source_collection:
type: string
description: The name of the collection to be used as the source for the index.
example: movie-embeddings
responses:
400BadRequest:
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:
status: 400
error:
code: INVALID_ARGUMENT
message: Metric must be cosine, euclidean, or dotproduct.
401Unauthorized:
description: 'Unauthorized. Possible causes: Invalid API key.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Unauthorized
value:
status: 401
error:
code: UNAUTHENTICATED
message: Invalid API key.
403PodQuotaExceeded:
description: You've exceed your pod quota.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Forbidden
value:
status: 403
error:
code: FORBIDDEN
message: Increase your quota or upgrade to create more indexes.
404ServerlessSpecNotFound:
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:
status: 404
error:
code: NOT_FOUND
message: 'Resource cloud: aws region: us-west1 not found.'
422UnprocessableEntity:
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:
status: 422
error:
code: INVALID_ARGUMENT
message: >-
Failed to deserialize the JSON body into the target type:
missing field `metric` at line 1 column 16
500InternalServerError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internal-server-error:
summary: Internal server error
value:
status: 500
error:
code: UNKNOWN
message: Internal server error
securitySchemes:
ApiKeyAuth:
type: apiKey
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
in: header
````