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: 202601-alpha servers: - url: https://api.pinecone.io description: Production API endpoints 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: 202601-alpha 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 a serverless and a pod-based index. value: indexes: - deletion_protection: disabled deployment: cloud: aws deployment_type: managed region: us-east-1 host: movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io name: movie-recommendations read_capacity: mode: OnDemand status: state: Ready schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string status: ready: true state: Ready - deletion_protection: disabled deployment: deployment_type: pod environment: us-east1-gcp pod_type: p1.x1 replicas: 2 shards: 2 host: legacy-pod-index-a31f9c1.svc.us-east1-gcp.pinecone.io name: legacy-pod-index schema: fields: embedding: dimension: 768 metric: dotproduct type: dense_vector status: ready: true state: Ready one-index: summary: A list containing one serverless index. value: indexes: - deletion_protection: disabled deployment: cloud: aws deployment_type: managed region: us-east-1 host: movie-embeddings-c01b5b5.svc.us-east1-gcp.pinecone.io name: movie-embeddings read_capacity: mode: OnDemand status: state: Ready schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector status: ready: false state: Initializing 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. Define the schema for your index — including vector fields, semantic text fields, and metadata fields — and the deployment infrastructure (managed serverless, pod-based, 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: 202601-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 genre: filterable: true type: string 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 category: filterable: 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 pod-index: summary: Pod-based index value: deletion_protection: enabled deployment: deployment_type: pod environment: us-east1-gcp pod_type: p1.x1 replicas: 1 shards: 1 name: movie-recommendations schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string year: filterable: true type: float 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 /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: 202601-alpha 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: serverless-dense: summary: A serverless dense vector index value: deletion_protection: disabled deployment: cloud: aws deployment_type: managed region: us-east-1 host: movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io name: movie-recommendations read_capacity: mode: OnDemand status: state: Ready schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string title: filterable: true type: string status: ready: true state: Ready serverless-fts: summary: A serverless full-text search index value: deletion_protection: disabled deployment: cloud: aws deployment_type: managed region: us-east-1 host: article-search-d12e6e6.svc.us-east1-gcp.pinecone.io name: article-search read_capacity: mode: OnDemand status: state: Ready schema: fields: body: full_text_search: language: en stemming: true stop_words: true type: string category: filterable: true type: string title: full_text_search: language: en type: string status: ready: true state: Ready pod-based: summary: A pod-based index value: deletion_protection: disabled deployment: deployment_type: pod environment: us-east-1-aws pod_type: p1.x1 replicas: 1 shards: 1 host: movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io name: movie-recommendations schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string status: ready: true state: Ready 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: 202601-alpha 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: 202601-alpha 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 configuration changes to apply to the index. content: application/json: schema: $ref: '#/components/schemas/ConfigureIndexRequest' examples: scale-replicas: summary: Scale a pod-based index to 4 replicas value: deployment: replicas: 4 upgrade-pod-type: summary: Upgrade pod size value: deployment: pod_type: p1.x2 update-read-capacity: summary: Switch to dedicated read capacity value: read_capacity: dedicated: manual: replicas: 2 shards: 2 node_type: t1 scaling: Manual mode: Dedicated update-semantic-text-params: summary: Update semantic text field inference parameters value: schema: fields: content: read_parameters: input_type: query truncate: NONE type: semantic_text write_parameters: input_type: passage disable-deletion-protection: summary: Disable deletion protection value: deletion_protection: disabled update-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: 202601-alpha 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 for the given index. content: application/json: schema: $ref: '#/components/schemas/BackupList' examples: backups: summary: A list of backups for an index. value: data: - backup_id: bkp_123abc cloud: aws created_at: 2025-03-15T10:30:00Z description: Monthly backup of production index name: backup_2025_03_15 namespace_count: 3 record_count: 120000 region: us-east-1 schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string 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: 2025-03-20T15:45:00Z description: Pre-deployment safety backup name: backup_2025_03_20 namespace_count: 4 record_count: 125000 region: us-east-1 schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string 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: default: 202601-alpha type: string style: simple - in: path name: index_name description: Name of the index to backup required: true schema: type: string style: simple requestBody: description: The desired configuration for the backup. content: application/json: schema: $ref: '#/components/schemas/CreateBackupRequest' examples: backup-index-no-name: summary: Creating a backup of an index with no name value: {} backup-index-with-name: summary: Creating a backup of an index with a name value: name: backup-index backup-index-with-name-and-description: summary: Creating a backup of an index with a name and description value: description: Backup of the index name: backup-index required: true responses: '201': description: The backup has been successfully created. content: application/json: schema: $ref: '#/components/schemas/BackupModel' '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 backup 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 backups. status: 403 '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/create-for-model: post: tags: - Manage Indexes summary: Create an index with integrated embedding description: |- Create a serverless index with an integrated embedding model. Pinecone automatically embeds text written to the specified field at write time and embeds queries at read time using the same model. This is a convenience wrapper around [Create Index](#tag/Manage-Indexes/operation/create_index) that constructs a `semantic_text` schema field from the model parameters you provide. For full control over schema composition (e.g., combining semantic text with metadata fields), use Create Index directly. For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index#integrated-embedding). operationId: create_index_for_model parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple requestBody: description: The desired configuration for the index and associated embedding model. content: application/json: schema: $ref: '#/components/schemas/CreateIndexForModelRequest' examples: index-for-model: summary: Creating a serverless index for the specified model value: deletion_protection: enabled deployment: cloud: aws deployment_type: managed region: us-east-1 field: content model: multilingual-e5-large name: multilingual-e5-large-index read_parameters: input_type: query truncate: NONE write_parameters: input_type: passage required: true responses: '201': description: The index has been successfully created. content: application/json: schema: $ref: '#/components/schemas/IndexModel' examples: created: summary: Index created with integrated embedding value: deletion_protection: enabled deployment: cloud: aws deployment_type: managed region: us-east-1 host: multilingual-e5-large-index-c01b5b5.svc.us-east1.pinecone.io name: multilingual-e5-large-index read_capacity: mode: OnDemand status: state: Ready schema: fields: content: metric: cosine model: multilingual-e5-large read_parameters: input_type: query truncate: NONE type: semantic_text write_parameters: input_type: passage status: ready: false state: Initializing '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 '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 /backups: get: tags: - Manage Indexes summary: List backups for all indexes in a project description: List all backups for a project. operationId: list_project_backups parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha 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 for the given project. content: application/json: schema: $ref: '#/components/schemas/BackupList' examples: backups: summary: A list of project backups. value: data: - backup_id: 670e8400-e29b-41d4-a716-446655440000 cloud: aws created_at: 2025-03-15T10:30:00Z description: Monthly backup of production index name: backup_2025_03_15 namespace_count: 3 record_count: 120000 region: us-east-1 schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string size_bytes: 10000000 source_index_id: idx_456 source_index_name: my-index status: Ready tags: environment: production type: monthly - backup_id: 670e8400-e29b-41d4-a716-446655440001 cloud: aws created_at: 2025-03-20T15:45:00Z description: Pre-deployment safety backup name: backup_2025_03_20 namespace_count: 4 record_count: 125000 region: us-east-1 schema: fields: body: full_text_search: language: en type: string title: full_text_search: language: en type: string size_bytes: 10500000 source_index_id: idx_789 source_index_name: my-fts-index status: Ready tags: environment: production type: pre-deploy '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 /backups/{backup_id}: get: tags: - Manage Indexes summary: Describe a backup description: Get a description of a backup. operationId: describe_backup parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple - in: path name: backup_id description: The ID of the backup to describe. required: true schema: type: string example: 670e8400-e29b-41d4-a716-446655440000 style: simple responses: '200': description: Configuration information and deployment status of the backup. content: application/json: schema: $ref: '#/components/schemas/BackupModel' examples: backup: summary: A backup of a dense vector index value: backup_id: 670e8400-e29b-41d4-a716-446655440000 cloud: aws created_at: 2025-03-15T10:30:00Z description: Monthly backup of production index name: backup_2025_03_15 namespace_count: 3 record_count: 120000 region: us-east-1 schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string title: filterable: true type: string size_bytes: 10000000 source_index_id: 670e8400-e29b-41d4-a716-446655440001 source_index_name: my-index status: Ready tags: environment: production type: monthly '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: Backup not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: backup-not-found: summary: Backup not found value: error: code: NOT_FOUND message: Backup bkp_123abc 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 a backup description: Delete a backup. operationId: delete_backup parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple - in: path name: backup_id description: The ID of the backup to delete. required: true schema: type: string example: 670e8400-e29b-41d4-a716-446655440000 style: simple responses: '202': description: The request to delete the backup 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 '404': description: Backup not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: backup-not-found: summary: Backup not found value: error: code: NOT_FOUND message: Backup bkp_123abc not found. status: 404 '412': description: There is a pending restore job created from this backup. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: pending-restore: summary: There is a pending restore job from this backup. value: error: code: FAILED_PRECONDITION message: 'Unable to delete backup. There are pending restore jobs for this backup: [''670e8400-e29b-41d4-a716-446655440000'']' 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 /backups/{backup_id}/create-index: post: tags: - Manage Indexes summary: Create an index from a backup description: Create an index from a backup. operationId: create_index_from_backup_operation parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple - in: path name: backup_id description: The ID of the backup to create an index from. required: true schema: type: string example: 670e8400-e29b-41d4-a716-446655440000 style: simple requestBody: description: The desired configuration for the index created from a backup. content: application/json: schema: $ref: '#/components/schemas/CreateIndexFromBackupRequest' required: true responses: '202': description: The request to create the index has been accepted. content: application/json: schema: $ref: '#/components/schemas/CreateIndexFromBackupResponse' '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: Backup not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: backup-not-found: summary: Backup not found value: error: code: NOT_FOUND message: Backup bkp_123abc not found. status: 404 '409': description: Index of given name already exists. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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 /restore-jobs: get: tags: - Manage Indexes summary: List restore jobs description: List all restore jobs for a project. operationId: list_restore_jobs parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha 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 restore jobs that you have previously created. content: application/json: schema: $ref: '#/components/schemas/RestoreJobList' examples: paginated-restore-jobs: summary: A list containing restore jobs. value: data: - backup_id: 670e8400-e29b-41d4-a716-446655440000 completed_at: 2024-03-15T10:35:00Z created_at: 2024-03-15T10:30:00Z percent_complete: 100 restore_job_id: 670e8400-e29b-41d4-a716-446655440001 status: Completed target_index_id: idx_456 target_index_name: my-index pagination: next: dXNlcl9pZD11c2VyXzE= non-paginated-restore-jobs: summary: A list containing restore jobs. value: data: - backup_id: 670e8400-e29b-41d4-a716-446655440000 completed_at: 2024-03-15T10:35:00Z created_at: 2024-03-15T10:30:00Z percent_complete: 100 restore_job_id: 670e8400-e29b-41d4-a716-446655440001 status: Completed target_index_id: idx_456 target_index_name: my-index pagination: null no-restore-jobs: summary: An empty list. value: data: [] pagination: null '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 /restore-jobs/{job_id}: get: tags: - Manage Indexes summary: Describe a restore job description: Get a description of a restore job. operationId: describe_restore_job parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple - in: path name: job_id description: The ID of the restore job to describe. required: true schema: type: string example: 670e8400-e29b-41d4-a716-446655440000 style: simple responses: '200': description: Configuration information and deployment status of the restore job. content: application/json: schema: $ref: '#/components/schemas/RestoreJobModel' '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: Restore job not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: restore-job-not-found: summary: Restore job not found value: error: code: NOT_FOUND message: Restore job 670e8400-e29b-41d4-a716-446655440002 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 /collections: get: tags: - Manage Indexes summary: List collections description: | List all collections in a project. Serverless indexes do not support collections. operationId: list_collections parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple responses: '200': description: List all the collections in your current project. content: application/json: schema: $ref: '#/components/schemas/CollectionList' examples: multiple-collections: summary: Multiple collections with different states value: collections: - dimension: 3 environment: us-east1-gcp name: small-collection size: 3126700 status: Ready vector_count: 99 - dimension: 3 environment: us-east1-gcp name: small-collection-new size: 3126700 status: Initializing vector_count: 99 - dimension: 1536 environment: us-east1-gcp name: big-collection size: 160087040000000 status: Ready vector_count: 10000000 no-collections: summary: No collections created yet value: collections: [] '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 a collection description: "Create a Pinecone collection.\n \nServerless indexes do not support collections.\n" operationId: create_collection parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple requestBody: description: The desired configuration for the collection. content: application/json: schema: $ref: '#/components/schemas/CreateCollectionRequest' examples: creating-collection: summary: Creating a collection value: name: example-collection source: example-source-index required: true responses: '201': description: The collection has been successfully created. content: application/json: schema: $ref: '#/components/schemas/CollectionModel' '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 collections quota. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Forbidden value: error: code: FORBIDDEN message: Collection exceeds quota. Maximum allowed on your account is 1. Currently have 1. status: 403 '409': description: Collection of given name already exists. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: collection-name-already-exists: summary: Collection 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 /collections/{collection_name}: get: tags: - Manage Indexes summary: Describe a collection description: | Get a description of a collection. Serverless indexes do not support collections. operationId: describe_collection parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple - in: path name: collection_name description: The name of the collection to be described. required: true schema: type: string example: tiny-collection style: simple responses: '200': description: Configuration information and status of the collection. content: application/json: schema: $ref: '#/components/schemas/CollectionModel' examples: tiny-collection: summary: A small collection. value: dimension: 3 environment: us-east1-gcp name: tiny-collection size: 3126700 status: Ready vector_count: 99 '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: Collection not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: collection-not-found: summary: Collection not found. value: error: code: NOT_FOUND message: Collection example-collection 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 a collection description: | Delete an existing collection. Serverless indexes do not support collections. operationId: delete_collection parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 202601-alpha type: string style: simple - in: path name: collection_name description: The name of the collection. required: true schema: type: string example: test-collection style: simple responses: '202': description: The collection has been successfully deleted. '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: Collection not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: collection-not-found: summary: Collection not found. value: error: code: NOT_FOUND message: Collection example-collection 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 components: schemas: BackupList: description: The list of backups that exist in the project. type: object properties: data: description: List of backup objects type: array items: $ref: '#/components/schemas/BackupModel' pagination: $ref: '#/components/schemas/PaginationResponse' BackupModel: description: The BackupModel describes the configuration and status of a Pinecone backup. type: object properties: backup_id: example: 670e8400-e29b-41d4-a716-446655440001 description: Unique identifier for the backup. type: string source_index_name: example: my-index description: Name of the index from which the backup was taken. type: string source_index_id: example: 670e8400-e29b-41d4-a716-446655440000 description: ID of the index from which the backup was taken. type: string name: example: backup-2025-02-04 description: Optional user-defined name for the backup. type: string description: example: Backup before bulk update. description: Optional description providing context for the backup. type: string status: example: Ready description: Current status of the backup. x-enum: - Initializing - Ready - Failed type: string cloud: example: aws description: Cloud provider where the backup is stored. type: string region: example: us-east-1 description: Cloud region where the backup is stored. type: string schema: $ref: '#/components/schemas/IndexSchema' record_count: example: 120000 description: Total number of records in the backup. type: integer namespace_count: example: 3 description: Number of namespaces in the backup. type: integer size_bytes: example: 10000000 description: Size of the backup in bytes. type: integer tags: $ref: '#/components/schemas/IndexTags' created_at: example: 2025-02-04T10:30:00Z description: Timestamp when the backup was created. type: string format: date-time required: - backup_id - source_index_name - source_index_id - status - cloud - region BooleanField: example: filterable: true type: boolean title: Boolean description: A boolean field configuration. Can be indexed for use in metadata filter expressions. 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: example: true description: Whether this field should be indexed for use in filter expressions. type: boolean required: - type 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 CollectionList: description: The list of collections that exist in the project. type: object properties: collections: description: List of collections in the project type: array items: $ref: '#/components/schemas/CollectionModel' CollectionModel: description: The CollectionModel describes the configuration and status of a Pinecone collection. type: object properties: name: example: example-collection description: The name of the collection. type: string size: example: 10000000 description: The size of the collection in bytes. type: integer format: int64 status: example: Initializing description: |- The status of the collection. Possible values: `Initializing`, `Ready`, or `Terminating`. x-enum: - Initializing - Ready - Terminating type: string dimension: example: 1536 description: The dimension of the vectors stored in each record held in the collection. type: integer format: int32 minimum: 1 maximum: 20000 vector_count: example: 120000 description: The number of records stored in the collection. type: integer format: int32 environment: example: us-east1-gcp description: The environment where the collection is hosted. type: string required: - name - status - environment ConfigureIndexRequest: description: |- Configuration updates to apply to an existing index. All fields are optional; only the fields you include are modified. - `deployment`: Update pod-based scaling parameters (`replicas`, `pod_type`). Deployment type and cloud/region cannot be changed. - `schema`: Update `semantic_text` field embedding parameters. Only `write_parameters` and `read_parameters` may be changed; the model cannot be changed after creation. - `read_capacity`: Update read capacity mode or dedicated node configuration for managed and BYOC indexes. Not applicable to pod-based indexes. - `tags`: Update or delete index tags. Setting a tag value to `""` removes the tag. - `deletion_protection`: Enable or disable deletion protection. type: object properties: deployment: $ref: '#/components/schemas/PatchIndexDeploymentRequest' schema: $ref: '#/components/schemas/PatchIndexSchema' read_capacity: $ref: '#/components/schemas/ReadCapacity' tags: $ref: '#/components/schemas/IndexTags' deletion_protection: $ref: '#/components/schemas/DeletionProtection' CreateBackupRequest: description: The configuration needed to create a backup of an index. type: object properties: name: description: The name of the backup. type: string description: description: A description of the backup. type: string CreateCollectionRequest: description: The configuration needed to create a Pinecone collection. type: object properties: name: description: | The name of the collection to be created. 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 source: example: example-source-index description: The name of the index to be used as the source for the collection. type: string required: - name - source CreateIndexForModelRequest: description: Configuration for creating an index with an integrated embedding model. The server constructs a `semantic_text` schema field named `field` using the provided model parameters. type: object properties: name: example: example-index description: The name of the index. Auto-generated if not provided. Resource name must be 1-45 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or '-'. 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/ManagedDeployment' field: example: content description: The name of the schema field that will hold the embedded text. This becomes a `semantic_text` field in the index schema. type: string model: example: multilingual-e5-large description: The name of the embedding model to use. Refer to the [model guide](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models) for available models and details. type: string 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'. Possible values: `cosine`, `euclidean`, or `dotproduct`. x-enum: - cosine - euclidean - dotproduct type: string write_parameters: example: input_type: passage description: Model-specific parameters applied when embedding documents at write time. type: object read_parameters: example: input_type: query truncate: NONE description: Model-specific parameters applied when embedding queries at read time. type: object read_capacity: $ref: '#/components/schemas/ReadCapacity' tags: $ref: '#/components/schemas/IndexTags' deletion_protection: $ref: '#/components/schemas/DeletionProtection' required: - model - field CreateIndexFromBackupRequest: description: The configuration needed to create a Pinecone index from a backup. 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 tags: $ref: '#/components/schemas/IndexTags' deletion_protection: $ref: '#/components/schemas/DeletionProtection' required: - name CreateIndexFromBackupResponse: description: The response for creating an index from a backup. type: object properties: restore_job_id: example: 670e8400-e29b-41d4-a716-446655440000 description: The ID of the restore job that was created. type: string index_id: example: 123e4567-e89b-12d3-a456-426614174000 description: The ID of the index that was created from the backup. type: string required: - restore_job_id - index_id 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 CreateIndexSchema: example: fields: embedding: dimension: 1536 metric: cosine type: dense_vector genre: filterable: true type: string year: filterable: true type: float 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 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 (use `filterable`). - `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. discriminator: propertyName: type mapping: dense_vector: '#/components/schemas/DenseVectorField' sparse_vector: '#/components/schemas/SparseVectorField' semantic_text: '#/components/schemas/SemanticTextField' string: '#/components/schemas/StringField' string_list: '#/components/schemas/StringListField' float: '#/components/schemas/FloatField' boolean: '#/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' 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 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 additionalProperties: false 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 FloatField: example: filterable: true type: float title: Float description: A numeric (floating-point) field configuration. Can be indexed for use in metadata filter expressions. 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: example: true description: Whether this field should be indexed for use in filter expressions. type: boolean required: - type additionalProperties: false 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: '#/components/schemas/PodDeployment' managed: '#/components/schemas/ManagedDeployment' byoc: '#/components/schemas/ByocDeployment' oneOf: - $ref: '#/components/schemas/PodDeployment' - $ref: '#/components/schemas/ManagedDeployment' - $ref: '#/components/schemas/ByocDeployment' 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: '#/components/schemas/PodDeployment' managed: '#/components/schemas/ManagedDeployment' byoc: '#/components/schemas/ByocDeployment' oneOf: - $ref: '#/components/schemas/PodDeployment' - $ref: '#/components/schemas/ManagedDeployment' - $ref: '#/components/schemas/ByocDeployment' IndexList: description: The list of indexes that exist in the project. type: object properties: indexes: description: List of indexes in the project type: array items: $ref: '#/components/schemas/IndexModel' 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 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 IndexSchema: example: fields: embedding: dimension: 1536 metric: cosine type: dense_vector title: full_text_search: language: en 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 IndexSchemaField: description: |- The configuration of a single field in the index schema. 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 or metadata filtering. - `string_list`: String array field for metadata filtering. - `float`: Numeric field for metadata filtering. - `boolean`: Boolean field for metadata filtering. discriminator: propertyName: type mapping: dense_vector: '#/components/schemas/DenseVectorField' sparse_vector: '#/components/schemas/SparseVectorField' semantic_text: '#/components/schemas/SemanticTextField' string: '#/components/schemas/StringField' string_list: '#/components/schemas/StringListField' float: '#/components/schemas/FloatField' boolean: '#/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' 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 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 PaginationResponse: example: next: dXNlcl9pZD11c2VyXzE= description: The pagination object that is returned with paginated responses. type: object properties: next: example: dXNlcl9pZD11c2VyXzE= description: The token to use to retrieve the next page of results. type: string required: - next PatchIndexDeploymentRequest: example: replicas: 4 title: Pod-based description: Deployment update parameters for pod-based indexes. Specify `replicas`, `pod_type`, or both. Deployment type, cloud/region, and environment cannot be changed after creation. Do not include a `deployment_type` field; it is not accepted. type: object properties: 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 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 additionalProperties: false PatchIndexSchema: example: fields: content: read_parameters: input_type: query truncate: NONE type: semantic_text write_parameters: input_type: passage description: Schema updates to apply to an existing index. Only `semantic_text` field parameters can be updated after index creation. The model itself cannot be changed once set; only `write_parameters` and `read_parameters` may be updated if the model stays the same. type: object properties: fields: description: A map of semantic text field names to their updated parameters. Only fields of type `semantic_text` may be specified. type: object additionalProperties: $ref: '#/components/schemas/PatchSemanticTextField' required: - fields PatchSemanticTextField: description: Updated parameters for a semantic text field. type: object properties: type: description: The field type. Must be `semantic_text`. type: string enum: - semantic_text model: example: multilingual-e5-large description: The name of the embedding model. Cannot be changed once set; only specify to confirm the current model when also updating parameters. type: string write_parameters: example: input_type: passage description: Updated model-specific parameters applied at write time. type: object read_parameters: example: input_type: query truncate: NONE description: Updated model-specific parameters applied at query time. type: object required: - type additionalProperties: false 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 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: '#/components/schemas/ReadCapacityOnDemandSpec' Dedicated: '#/components/schemas/ReadCapacityDedicatedSpec' oneOf: - $ref: '#/components/schemas/ReadCapacityOnDemandSpec' - $ref: '#/components/schemas/ReadCapacityDedicatedSpec' 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' 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 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 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 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 ReadCapacityResponse: description: Response containing read capacity configuration discriminator: propertyName: mode mapping: OnDemand: '#/components/schemas/ReadCapacityOnDemandSpecResponse' Dedicated: '#/components/schemas/ReadCapacityDedicatedSpecResponse' oneOf: - $ref: '#/components/schemas/ReadCapacityOnDemandSpecResponse' - $ref: '#/components/schemas/ReadCapacityDedicatedSpecResponse' 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. \n\nAvailable values:\n- `Ready` is the state most of the time\n- `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)\n- `Migrating` if the index is being migrated to a new `node_type`\n- `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 RestoreJobList: description: The list of restore jobs that exist in the project. type: object properties: data: description: List of restore job objects type: array items: $ref: '#/components/schemas/RestoreJobModel' pagination: $ref: '#/components/schemas/PaginationResponse' required: - data RestoreJobModel: description: The RestoreJobModel describes the status of a restore job. type: object properties: restore_job_id: example: 670e8400-e29b-41d4-a716-446655440001 description: Unique identifier for the restore job type: string backup_id: example: 670e8400-e29b-41d4-a716-446655440000 description: Backup used for the restore type: string target_index_name: example: sample-index description: Name of the index into which data is being restored type: string target_index_id: example: 670e8400-e29b-41d4-a716-446655440002 description: ID of the index type: string status: example: Completed description: Status of the restore job type: string created_at: example: 2025-02-04T13:00:00Z description: Timestamp when the restore job started type: string format: date-time completed_at: example: 2025-02-04T14:00:00Z description: Timestamp when the restore job finished type: string format: date-time percent_complete: example: 42.2 description: The progress made by the restore job out of 100 type: number format: float minimum: 0.0 maximum: 100.0 required: - restore_job_id - backup_id - target_index_name - target_index_id - status - created_at 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 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 additionalProperties: false 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 additionalProperties: false StringField: example: full_text_search: language: en type: string title: String description: |- A string field configuration. A string field operates in one of two mutually exclusive modes: - **Full-text search mode**: Include a `full_text_search` object. The field is indexed for full-text search using the specified text-analysis settings. - **Metadata filtering mode**: Set `filterable: true` (or omit `full_text_search`). The field is indexed for use in filter expressions. Providing both `full_text_search` and `filterable` in the same field definition is not allowed and 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. Mutually exclusive with `filterable`. `stop_words` requires `stemming: true`. 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 lowercase: readOnly: true description: Whether to lowercase tokens during text analysis. Defaults to `true`. Read-only; set by the server. default: true type: boolean max_term_len: readOnly: true description: The maximum token length to index. Tokens exceeding this length are truncated. Defaults to `40`. Read-only; set by the server. default: 40 type: integer additionalProperties: false filterable: example: true description: Whether this field should be indexed for use in filter expressions. Mutually exclusive with `full_text_search`. default: false type: boolean required: - type additionalProperties: false StringListField: example: filterable: true type: string_list title: String array description: A string array field configuration. Stores arrays of strings and can be indexed for use in metadata filter expressions. 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: example: true description: Whether this field should be indexed for use in filter expressions. type: boolean required: - type additionalProperties: false 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/). security: - ApiKeyAuth: [] tags: - name: Manage Indexes description: Actions that manage indexes externalDocs: description: More Pinecone.io API docs url: https://docs.pinecone.io/introduction