OpenAPI Specification
openapi: 3.0.3
info:
title: Pinecone Admin API Keys Manage Indexes API
description: 'Provides an API for managing a Pinecone organization and its resources.
'
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-10
servers:
- url: https://api.pinecone.io
description: Production API endpoints
security:
- BearerAuth: []
tags:
- name: Manage Indexes
description: Actions that manage indexes
paths:
/indexes:
get:
tags:
- Manage Indexes
summary: List indexes
description: List all indexes in a project.
operationId: list_indexes
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2025-10
type: string
style: simple
responses:
'200':
description: This operation returns a list of all the indexes that you have previously created, and which are associated with the given project
content:
application/json:
schema:
$ref: '#/components/schemas/IndexList'
examples:
multiple-indexes:
summary: A list containing one serverless index and one pod-based index.
value:
indexes:
- dimension: 384
host: semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io
metric: cosine
name: semantic-search
spec:
pod:
environment: us-west1-gcp
pod_type: p1.x1
pods: 4
replicas: 2
shards: 2
status:
ready: true
state: Ready
vector_type: dense
- dimension: 200
host: image-search-a31f9c1.svc.us-east1-gcp.pinecone.io
metric: dotproduct
name: image-search
spec:
serverless:
cloud: aws
read_capacity:
mode: OnDemand
status:
state: Ready
region: us-east-1
status:
ready: false
state: Initializing
vector_type: dense
- host: sparse-index-1a2b3c4d.svc.us-east1-gcp.pinecone.io
metric: dotproduct
name: sparse-index
spec:
serverless:
cloud: aws
read_capacity:
mode: OnDemand
status:
state: Ready
region: us-east-1
status:
ready: true
state: Ready
vector_type: sparse
one-index:
summary: A list containing one serverless index.
value:
indexes:
- dimension: 1536
host: movie-embeddings-c01b5b5.svc.us-east1-gcp.pinecone.io
metric: cosine
name: movie-embeddings
spec:
serverless:
cloud: aws
read_capacity:
mode: OnDemand
status:
state: Ready
region: us-east-1
status:
ready: false
state: Initializing
vector_type: dense
no-indexes:
summary: No indexes created yet.
value:
indexes: []
'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
'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
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.\n \nFor guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index).\n"
operationId: create_index
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2025-10
type: string
style: simple
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
read_capacity:
mode: OnDemand
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
read_capacity:
mode: OnDemand
region: us-east1
vector_type: sparse
serverless-dedicated-index:
summary: Creating an index with dedicated capacity
value:
deletion_protection: enabled
metric: cosine
name: dedicated-index
spec:
serverless:
cloud: gcp
read_capacity:
dedicated:
manual:
replicas: 3
shards: 2
node_type: b1
scaling: Manual
mode: Dedicated
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
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
'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
'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
'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
/indexes/{index_name}:
get:
tags:
- Manage Indexes
summary: Describe an index
description: Get a description of an index.
operationId: describe_index
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2025-10
type: string
style: simple
- in: path
name: index_name
description: The name of the index to be described.
required: true
schema:
type: string
example: test-index
style: simple
responses:
'200':
description: Configuration information and deployment status of the index.
content:
application/json:
schema:
$ref: '#/components/schemas/IndexModel'
examples:
movie-recommendations-serverless:
summary: A serverless index
value:
dimension: 1536
host: movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io
metric: cosine
name: movie-recommendations
spec:
serverless:
cloud: aws
read_capacity:
mode: OnDemand
status:
state: Ready
region: us-east-1
schema:
fields:
genre:
filterable: true
title:
filterable: true
status:
ready: false
state: Initializing
vector_type: dense
movie-recommendations-pod:
summary: A pod-based index
value:
dimension: 1536
host: movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io
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
status:
ready: false
state: Initializing
vector_type: dense
links:
UpsertVector:
operationId: upsert
server:
url: $response.body#/host
UpdateVector:
operationId: update
server:
url: $response.body#/host
QueryVector:
operationId: query
server:
url: $response.body#/host
FetchVector:
operationId: fetch
server:
url: $response.body#/host
DeleteOneVector:
operationId: delete1
server:
url: $response.body#/host
DeleteVector:
operationId: delete
server:
url: $response.body#/host
'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
'404':
description: Index not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-not-found:
summary: Index not found
value:
error:
code: NOT_FOUND
message: Index example-index not found.
status: 404
'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
delete:
tags:
- Manage Indexes
summary: Delete an index
description: Delete an existing index.
operationId: delete_index
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2025-10
type: string
style: simple
- in: path
name: index_name
description: The name of the index to delete.
required: true
schema:
type: string
example: test-index
style: simple
responses:
'202':
description: The request to delete the index has been accepted.
'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: Forbidden. Deletion protection enabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
deletion-protection:
summary: Forbidden
value:
error:
code: FORBIDDEN
message: Deletion protection is enabled for this index. Disable deletion protection before retrying.
status: 403
'404':
description: Index not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-not-found:
summary: Index not found
value:
error:
code: NOT_FOUND
message: Index example-index not found.
status: 404
'412':
description: There is a pending collection created from this index.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
pending-collection:
summary: There is a pending collection from this index.
value:
error:
code: FAILED_PRECONDITION
message: 'Unable to delete an index. There are pending collections for this index: [''test-collection'']'
status: 412
'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
patch:
tags:
- Manage Indexes
summary: Configure an index
description: Configure an existing index. For guidance and examples, see [Manage indexes](https://docs.pinecone.io/guides/manage-data/manage-indexes).
operationId: configure_index
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2025-10
type: string
style: simple
- in: path
name: index_name
description: The name of the index to configure.
required: true
schema:
type: string
example: test-index
style: simple
requestBody:
description: The desired pod size and replica configuration for the index.
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigureIndexRequest'
examples:
vertical-scaling:
summary: Vertical scaling with pod size
value:
spec:
pod:
pod_type: p1.x2
horizontal-scaling:
summary: Horizontal scaling with replicas
value:
spec:
pod:
replicas: 4
scaling-both:
summary: Scaling both pod size and number of replicas
value:
spec:
pod:
pod_type: p1.x2
replicas: 4
disable-deletion-protection:
summary: Disable deletion protection for the index
value:
delete_protection: disabled
update-index-tags:
summary: Update tag0 and delete tag1
value:
tags:
tag0: new-val
tag1: ''
required: true
responses:
'202':
description: The request to configure the index has been accepted. Check the index status to see when the change has been applied.
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: Index not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-not-found:
summary: Index not found
value:
error:
code: NOT_FOUND
message: Index example-index not found.
status: 404
'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
/indexes/{index_name}/backups:
get:
tags:
- Manage Indexes
summary: List backups for an index
description: List all backups for an index.
operationId: list_index_backups
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2025-10
type: string
style: simple
- in: path
name: index_name
description: Name of the backed up index
required: true
schema:
type: string
style: simple
- in: query
name: limit
description: The number of results to return per page.
schema:
default: 10
type: integer
minimum: 1
maximum: 100
style: form
- in: query
name: paginationToken
description: The token to use to retrieve the next page of results.
schema:
type: string
style: form
responses:
'200':
description: This operation returns a list of all the backups that you have previously created, and which are associated with the given index.
content:
application/json:
schema:
$ref: '#/components/schemas/BackupList'
examples:
backups:
summary: A list containing backups.
value:
data:
- backup_id: bkp_123abc
cloud: aws
created_at: 2024-03-15 10:30:00+00:00
description: Monthly backup of production index
dimension: 1536
metric: cosine
name: backup_2024_03_15
namespace_count: 3
record_count: 120000
region: us-east-1
schema:
fields:
genre:
filterable: true
title:
filterable: true
size_bytes: 10000000
source_index_id: idx_456
source_index_name: my-index
status: Ready
tags:
environment: production
type: monthly
- backup_id: bkp_789xyz
cloud: aws
created_at: 2024-03-20 15:45:00+00:00
description: Pre-deployment safety backup
dimension: 1536
metric: cosine
name: backup_2024_03_20
namespace_count: 4
record_count: 125000
region: us-east-1
schema:
fields:
genre:
filterable: true
title:
filterable: true
size_bytes: 10500000
source_index_id: idx_456
source_index_name: my-index
status: Ready
tags:
environment: production
type: pre-deploy
pagination:
next: dXNlcl9pZD11c2VyXzE=
'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
'404':
description: Index not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-not-found:
summary: Index not found
value:
error:
code: NOT_FOUND
message: Index example-index not found.
status: 404
'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
post:
tags:
- Manage Indexes
summary: Create a backup of an index
description: 'Create a backup of an index.
'
operationId: create_backup
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinecone/refs/heads/main/openapi/pinecone-manage-indexes-api-openapi.yml