openapi: 3.0.3
info:
  title: Pinecone Control Plane API
  description: >-
    Pinecone is a vector database that makes it easy to search and retrieve
    billions of high-dimensional vectors.
  version: '2024-04'
  contact:
    name: Pinecone Support
    url: https://support.pinecone.io
    email: support@pinecone.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
tags:
  - name: Manage Indexes
    description: Actions that manage indexes
servers:
  - url: 'https://api.pinecone.io'
    description: Production API endpoints
externalDocs:
  description: More Pinecone.io API docs
  url: 'https://docs.pinecone.io/introduction'
paths:
  /indexes:
    get:
      operationId: list_indexes
      summary: 'List indexes'
      description: This operation returns a list of all indexes in a project.
      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:
                      - name: 'semantic-search'
                        dimension: 384
                        metric: 'cosine'
                        host: 'semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io'
                        status:
                          ready: true
                          state: 'Ready'
                        spec:
                          pod:
                            environment: 'us-west1-gcp'
                            replicas: 2
                            shards: 2
                            pod_type: 'p1.x1'
                            pods: 4
                      - name: 'image-search'
                        dimension: 200
                        metric: 'dotproduct'
                        host: 'image-search-a31f9c1.svc.us-east1-gcp.pinecone.io'
                        status:
                          ready: false
                          state: 'Initializing'
                        spec:
                          serverless:
                            cloud: 'aws'
                            region: 'us-east-1'
                one-index:
                  summary: 'A list containing one serverless index.'
                  value:
                    indexes:
                      - name: 'movie-embeddings'
                        dimension: 1536
                        metric: 'cosine'
                        host: 'movie-embeddings-c01b5b5.svc.us-east1-gcp.pinecone.io'
                        status:
                          ready: false
                          state: 'Initializing'
                        spec:
                          serverless:
                            cloud: 'aws'
                            region: 'us-east-1'
                no-indexes:
                  summary: 'No indexes created yet.'
                  value:
                    indexes: []
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    post:
      operationId: create_index
      summary: 'Create an index'
      description: >
        Create an index for vectors created with an external embedding model.


        For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index).
      requestBody:
        description: The desired configuration for the index.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIndexRequest'
            examples:
              serverless-index:
                summary: Creating a serverless index
                value:
                  name: 'movie-recommendations'
                  dimension: 1536
                  metric: 'cosine'
                  spec:
                    serverless:
                      cloud: 'gcp'
                      region: 'us-east1'
              pod-index:
                summary: Creating a pod-based index
                value:
                  name: 'movie-recommendations'
                  dimension: 1536
                  metric: 'cosine'
                  spec:
                    pod:
                      environment: 'us-east-1-aws'
                      replicas: 1
                      shards: 1
                      pod_type: 'p1.x1'
                      pods: 1
                      metadata_config:
                        indexed:
                          - 'genre'
                          - 'title'
                          - 'imdb_rating'
                      source_collection: 'movie-embeddings'
      responses:
        '201':
          description: The index has been successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexModel'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403PodQuotaExceeded'
        '404':
          $ref: '#/components/responses/404ServerlessSpecNotFound'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'

        '409':
          description: Index of given name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                index-name-already-exists:
                  summary: 'Index name needs to be unique.'
                  value:
                    status: 409
                    error:
                      code: 'ALREADY_EXISTS'
                      message: 'Resource already exists.'

        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    servers:
      - url: 'https://api.pinecone.io'
  '/indexes/{index_name}':
    get:
      operationId: describe_index
      summary: 'Describe an index'
      description: Get a description of an index.
      parameters:
        - name: index_name
          required: true
          in: path
          description: The name of the index to be described.
          example: 'test-index'
          schema:
            type: string
      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:
                    name: 'movie-recommendations'
                    dimension: 1536
                    metric: 'cosine'
                    host: 'movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io'
                    status:
                      ready: false
                      state: 'Initializing'
                    spec:
                      serverless:
                        cloud: 'aws'
                        region: 'us-east-1'
                movie-recommendations-pod:
                  summary: A pod-based index
                  value:
                    name: 'movie-recommendations'
                    dimension: 1536
                    metric: 'cosine'
                    host: 'movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io'
                    status:
                      ready: false
                      state: 'Initializing'
                    spec:
                      pod:
                        environment: 'us-east-1-aws'
                        replicas: 1
                        shards: 1
                        pod_type: 'p1.x1'
                        pods: 1
                        metadata_config:
                          indexed:
                            - 'genre'
                            - 'title'
                            - 'imdb_rating'
          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':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404IndexNotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    delete:
      operationId: delete_index
      summary: 'Delete an index'
      description: This operation deletes an existing index.
      parameters:
        - name: index_name
          required: true
          in: path
          schema:
            type: string
          example: 'test-index'
          description: The name of the index to delete.
      responses:
        '202':
          description: The request to delete the index has been accepted.
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404IndexNotFound'
        '412':
          $ref: '#/components/responses/412PendingCollection'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    patch:
      operationId: configure_index
      summary: 'Configure an index'
      description: >-
        This operation configures the pod size and number of replicas for a pod-based index.
        
        
        It is not possible to change the pod type of an index. However, you can create a collection from an index and then [create a new index with a different pod type](http://docs.pinecone.io/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection) from the collection.
      parameters:
        - name: index_name
          required: true
          in: path
          example: 'test-index'
          schema:
            type: string
          description: The name of the index to configure.
      requestBody:
        description: The desired pod size and replica configuration for the index.
        required: true
        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
      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':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403PodQuotaExceeded'
        '404':
          $ref: '#/components/responses/404IndexNotFound'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    servers:
      - url: 'https://api.pinecone.io'
  /collections:
    get:
      operationId: list_collections
      summary: 'List collections'
      description: >
        This operation returns a list of all collections in a project.
        

        Serverless indexes do not support collections.
      responses:
        '200':
          description: >-
            This operation returns a list of 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:
                      - name: 'small-collection'
                        size: 3126700
                        status: 'Ready'
                        dimension: 3
                        vector_count: 99
                        environment: us-east1-gcp
                      - name: 'small-collection-new'
                        size: 3126700
                        status: 'Initializing'
                        dimension: 3
                        vector_count: 99
                        environment: us-east1-gcp
                      - name: 'big-collection'
                        size: 160087040000000
                        status: 'Ready'
                        dimension: 1536
                        vector_count: 10000000
                        environment: us-east1-gcp
                no-collections:
                  summary: 'No collections created yet'
                  value:
                    collections: []
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    post:
      operationId: create_collection
      summary: 'Create a collection'
      description: >
        This operation creates a Pinecone collection.
        

        Serverless indexes do not support collections.
      requestBody:
        description: The desired configuration for the collection.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
            examples:
              creating-collection:
                summary: Creating a collection
                value:
                  name: 'example-collection'
                  source: 'example-source-index'
      responses:
        '201':
          description: The collection has been successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionModel'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403CollectionsQuotaExceeded'
        '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:
                    status: 409
                    error:
                      code: 'ALREADY_EXISTS'
                      message: 'Resource already exists.'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    servers:
      - url: 'https://api.pinecone.io'

  '/collections/{collection_name}':
    get:
      operationId: describe_collection
      summary: 'Describe a collection'
      description: >
        This operation gets a description of a collection.


        Serverless indexes do not support collections.
      parameters:
        - name: collection_name
          required: true
          in: path
          description: The name of the collection to be described.
          schema:
            type: string
          example: 'tiny-collection'
      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:
                    name: 'tiny-collection'
                    size: 3126700
                    status: 'Ready'
                    dimension: 3
                    vector_count: 99
                    environment: us-east1-gcp
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404CollectionNotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    delete:
      operationId: delete_collection
      summary: 'Delete a collection'
      description: >
        This operation deletes an existing collection.
        

        Serverless indexes do not support collections.
      parameters:
        - name: collection_name
          required: true
          in: path
          schema:
            type: string
          description: The name of the collection.
          example: 'test-collection'
      responses:
        '202':
          description: The collection has been successfully deleted.
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404CollectionNotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
      tags:
        - Manage Indexes
    servers:
      - url: 'https://api.pinecone.io'

components:
  schemas:
    # Data Models
    IndexModel:
      type: object
      description: >-
        The IndexModel describes the configuration and status of a
        Pinecone index.
      required:
        - name
        - dimension
        - metric
        - status
        - spec
        - host
      properties:
        name:
          $ref: '#/components/schemas/IndexName'
        dimension:
          $ref: '#/components/schemas/IndexDimension'
        metric:
          $ref: '#/components/schemas/IndexMetric'
        host:
          $ref: '#/components/schemas/IndexHost'
        spec:
          type: object
          properties:
            pod:
              $ref: '#/components/schemas/PodSpec'
            serverless:
              $ref: '#/components/schemas/ServerlessSpec'
          example:
            pod:
              environment: 'us-east-1-aws'
              replicas: 1
              shards: 1
              pod_type: 'p1.x1'
              pods: 1
              metadata_config:
                indexed:
                  - 'genre'
                  - 'title'
                  - 'imdb_rating'
        status:
          type: object
          required:
            - ready
            - state
          example:
            ready: true
            state: 'ScalingUpPodSize'
          properties:
            ready:
              type: boolean
            state:
              type: string
              enum:
                - Initializing
                - InitializationFailed
                - ScalingUp
                - ScalingDown
                - ScalingUpPodSize
                - ScalingDownPodSize
                - Terminating
                - Ready

    CollectionModel:
      type: object
      description: >-
        The CollectionModel describes the configuration and status of a
        Pinecone collection.
      required:
        - name
        - status
        - environment
      properties:
        name:
          type: string
          description: The name of the collection.
          example: example-collection
        size:
          type: integer
          description: The size of the collection in bytes.
          example: 10000000
          format: int64
        status:
          type: string
          description: The status of the collection.
          enum:
            - Initializing
            - Ready
            - Terminating
          example: Initializing
        dimension:
          type: integer
          description: The dimension of the vectors stored in each record held in the collection.
          example: 1536
          minimum: 1
          maximum: 2000
          format: int32
        vector_count:
          type: integer
          example: 120000
          format: int32
          description: The number of records stored in the collection.
        environment:
          type: string
          description: >-
            The environment where the collection is hosted.
          example: 'us-east1-gcp'

    # Properties of the IndexModel
    IndexMetric:
      type: string
      description: >-
        The distance metric to be used for similarity search. You can use
        'euclidean', 'cosine', or 'dotproduct'.
      enum:
        - cosine
        - euclidean
        - dotproduct
      default: cosine
    IndexName:
      type: string
      minLength: 1
      maxLength: 45
      description: >
        The name of the index. Resource name must be 1-45 characters long, start and end with an alphanumeric character,
        and consist only of lower case alphanumeric characters or '-'.
      example: example-index
    IndexDimension:
      type: integer
      description: The dimensions of the vectors to be inserted in the index.
      minimum: 1
      maximum: 20000
      example: 1536
      format: int32
    IndexHost:
      type: string
      description: >-
        The URL address where the index is hosted.
      example: 'semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io'

    # Properties of the spec object for pod-based indexes
    PodSpec:
      type: object
      description: Configuration needed to deploy a pod-based index.
      required:
        - environment
        - pods
        - replicas
        - shards
        - pod_type
      example:
        environment: 'us-east1-gcp'
        replicas: 1
        shards: 1
        pod_type: 'p1.x1'
        pods: 1
        metadata_config:
          indexed:
            - 'genre'
            - 'title'
            - 'imdb_rating'
        source_collection: 'movie-embeddings'
      properties:
        environment:
          type: string
          description: >-
            The environment where the index is hosted.
          example: 'us-east1-gcp'
        replicas:
          $ref: '#/components/schemas/PodSpecReplicas'
        shards:
          $ref: '#/components/schemas/PodSpecShards'
        pod_type:
          $ref: '#/components/schemas/PodSpecPodType'
        pods:
          type: integer
          description: >-
            The number of pods to be used in the index. This should be equal to
            `shards` x `replicas`.'
          default: 1
          example: 1
          minimum: 1
        metadata_config:
          type: object
          description: >-
            Configuration for the behavior of Pinecone's internal metadata index. By
            default, all metadata is indexed; when `metadata_config` is present,
            only specified metadata fields are indexed. These configurations are
            only valid for use with pod-based indexes.
          properties:
            indexed:
              type: array
              description: >-
                By default, all metadata is indexed; to change this behavior, use
                this property to specify an array of metadata fields that should be
                indexed.
              items:
                type: string
          example:
            indexed:
              - 'genre'
              - 'title'
              - 'imdb_rating'
        source_collection:
          type: string
          description: >-
            The name of the collection to be used as the source for the index.
          example: 'movie-embeddings'
    PodSpecPodType:
      type: string
      description: >-
        The type of pod to use. One of `s1`, `p1`, or `p2` appended with `.` and
        one of `x1`, `x2`, `x4`, or `x8`.
      default: p1.x1
    PodSpecReplicas:
      type: integer
      format: int32
      description: >-
        The number of replicas. Replicas duplicate your index. They provide
        higher availability and throughput. Replicas can be scaled up or down
        as your needs change.
      default: 1
      minimum: 1
    PodSpecShards:
      type: integer
      format: int32
      description: >-
        The number of shards. Shards split your data across multiple pods so you
        can fit more data into an index.
      default: 1
      minimum: 1

    # Properties of the spec object for serverless indexes
    ServerlessSpec:
      type: object
      required:
        - cloud
        - region
      description: Configuration needed to deploy a serverless index.
      properties:
        cloud:
          type: string
          enum:
            - gcp
            - aws
            - azure
          description: >-
            The public cloud where you would like your index hosted.
          example: aws
        region:
          type: string
          description: >-
            The region where you would like your index to be created. 
          example: us-east-1

    # Shape of error responses
    ErrorResponse:
      type: object
      description: The response shape used for all error responses.
      required:
        - status
        - error
      properties:
        status:
          type: integer
          description: The HTTP status code of the error.
          example: 500
        error:
          type: object
          description: Detailed information about the error that occurred.
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - OK
                - UNKNOWN
                - INVALID_ARGUMENT
                - DEADLINE_EXCEEDED
                - QUOTA_EXCEEDED
                - NOT_FOUND
                - ALREADY_EXISTS
                - PERMISSION_DENIED
                - UNAUTHENTICATED
                - RESOURCE_EXHAUSTED
                - FAILED_PRECONDITION
                - ABORTED
                - OUT_OF_RANGE
                - UNIMPLEMENTED
                - INTERNAL
                - UNAVAILABLE
                - DATA_LOSS
                - FORBIDDEN
            message:
              type: string
              example: Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen.
            details:
              description: >-
                Additional information about the error. This field is not
                guaranteed to be present.
              type: object
          example:
            code: 'INVALID_ARGUMENT'
            message: 'Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen.'
      example:
        status: 429
        error:
          code: 'QUOTA_EXCEEDED'
          message: 'The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota.'

    IndexList:
      type: object
      description: The list of indexes that exist in the project.
      properties:
        indexes:
          type: array
          items:
            $ref: '#/components/schemas/IndexModel'

    CollectionList:
      type: object
      description: The list of collections that exist in the project.
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/CollectionModel'

    # Request bodies
    CreateIndexRequest:
      type: object
      description: >-
        The configuration needed to create a Pinecone index.
      required:
        - name
        - dimension
        - spec
      properties:
        name:
          $ref: '#/components/schemas/IndexName'
        dimension:
          $ref: '#/components/schemas/IndexDimension'
        metric:
          $ref: '#/components/schemas/IndexMetric'
        spec:
          type: object
          description: >
            The spec object defines how the index should be deployed.


            For serverless indexes, you define only the [cloud and region](http://docs.pinecone.io/guides/index-data/indexing-overview#cloud-regions) where the index should be hosted. For pod-based indexes, you define the [environment](http://docs.pinecone.io/guides/indexes/pods/understanding-pod-based-indexes#pod-environments) where the index should be hosted, the [pod type and size](http://docs.pinecone.io/guides/indexes/pods/understanding-pod-based-indexes#pod-types) to use, and other index characteristics.
          additionalProperties: false
          properties:
            serverless:
              $ref: '#/components/schemas/ServerlessSpec'
            pod:
              type: object
              description: >-
                Configuration needed to deploy a pod-based index.
              required:
                - environment
                - pod_type
              properties:
                environment:
                  type: string
                  description: >-
                    The environment where the index is hosted.
                  example: 'us-east1-gcp'
                replicas:
                  $ref: '#/components/schemas/PodSpecReplicas'
                pod_type:
                  $ref: '#/components/schemas/PodSpecPodType'
                pods:
                  type: integer
                  description: >-
                    The number of pods to be used in the index. This should be equal to `shards` x `replicas`.
                  example: 1
                  minimum: 1
                shards:
                  $ref: '#/components/schemas/PodSpecShards'
                metadata_config:
                  type: object
                  description: >-
                    Configuration for the behavior of Pinecone's internal metadata index. By
                    default, all metadata is indexed; when `metadata_config` is present,
                    only specified metadata fields are indexed. These configurations are
                    only valid for use with pod-based indexes.
                  properties:
                    indexed:
                      type: array
                      description: >-
                        By default, all metadata is indexed; to change this behavior, use
                        this property to specify an array of metadata fields which should be
                        indexed.
                      items:
                        type: string
                  example:
                    indexed:
                      - 'genre'
                      - 'title'
                      - 'imdb_rating'
                source_collection:
                  type: string
                  description: >-
                    The name of the collection to be used as the source for the index.
                  example: 'movie-embeddings'
          oneOf:
            - required: [serverless]
            - required: [pod]
    CreateCollectionRequest:
      type: object
      description: >-
        The configuration needed to create a Pinecone collection.
      required:
        - name
        - source
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 45
          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 '-'.
        source:
          type: string
          description: The name of the index to be used as the source for the collection.
          example: example-source-index
    ConfigureIndexRequest:
      type: object
      description: >-
        Configuration used to scale an index.
      required: ['spec']
      properties:
        spec:
          type: object
          required: ['pod']
          properties:
            pod:
              type: object
              properties:
                replicas:
                  $ref: '#/components/schemas/PodSpecReplicas'
                pod_type:
                  $ref: '#/components/schemas/PodSpecPodType'

  responses:
    '400BadRequest':
      description: Bad request. The request body included invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            index-metric-validation-error:
              summary: 'Validation error on metric.'
              value:
                status: 400
                error:
                  code: 'INVALID_ARGUMENT'
                  message: 'Metric must be cosine, euclidean, or dotproduct.'
    '401Unauthorized':
      description: 'Unauthorized. Possible causes: Invalid API key.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: 'Unauthorized'
              value:
                status: 401
                error:
                  code: 'UNAUTHENTICATED'
                  message: 'Invalid API key.'
    '403CollectionsQuotaExceeded':
      description: "You've exceed your collections quota."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: 'Forbidden'
              value:
                status: 403
                error:
                  code: 'FORBIDDEN'
                  message: Collection exceeds quota. Maximum allowed on your account is 1. Currently have 1.
    '403PodQuotaExceeded':
      description: "You've exceed your pod quota."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: 'Forbidden'
              value:
                status: 403
                error:
                  code: 'FORBIDDEN'
                  message: Increase your quota or upgrade to create more indexes.
    '404ServerlessSpecNotFound':
      description: Unknown cloud or region when creating a serverless index.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            serverless-spec-cloud-not-found:
              summary: 'Cannot create serverless index with invalid spec.'
              value:
                status: 404
                error:
                  code: 'NOT_FOUND'
                  message: 'Resource cloud: aws region: us-west1 not found.'
    '404IndexNotFound':
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            index-not-found:
              summary: 'Index not found'
              value:
                status: 404
                error:
                  code: 'NOT_FOUND'
                  message: 'Index example-index not found.'
    '404CollectionNotFound':
      description: Collection not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            collection-not-found:
              summary: 'Collection not found.'
              value:
                status: 404
                error:
                  code: 'NOT_FOUND'
                  message: 'Collection example-collection not found.'
    '412PendingCollection':
      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:
                status: 412
                error:
                  code: 'FAILED_PRECONDITION'
                  message: >- 
                    Unable to delete an index. There are pending collections for this index: ['test-collection']
    '422UnprocessableEntity':
      description: >-
        Unprocessable entity. The request body could not be deserialized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing-field:
              summary: 'Unprocessable entity'
              value:
                status: 422
                error:
                  code: 'INVALID_ARGUMENT'
                  message: 'Failed to deserialize the JSON body into the target type: missing field `metric` at line 1 column 16'
    '500InternalServerError':
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              summary: 'Internal server error'
              value:
                status: 500
                error:
                  code: 'UNKNOWN'
                  message: 'Internal server error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Api-Key
      description: "An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/)."
      in: header

security:
  - ApiKeyAuth: []