@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Pinecone API
@base https://controller.us-east1-gcp.pinecone.io
@version 20230406.1
@auth ApiKey Api-Key in header
@endpoints 15
@toc collections(4), databases(5), describe_index_stats(1), query(1), vectors(4)

@group collections
@endpoint GET /collections
@desc List collections
@returns(200) This operation returns a list of all the collections in your current project.

@endpoint POST /collections
@desc Create collection
@required {name: str(CollectionName) # The unique name of a collection., source: str(IndexName) # The unique name of an index.}
@returns(201) The collection has been successfully created.
@errors {400: Quota exceeded, or invalid parameters., 409: A collection with the name provided already exists., 500: Internal error. Can be caused by invalid parameters.}

@endpoint GET /collections/{collectionName}
@desc Describe collection
@returns(200) {name: str(CollectionName), size: int(int64), status: str(CollectionState)} # This operation returns a list of all the collections in your current project.
@errors {404: Collection not found., 500: Internal error. Can be caused by invalid parameters.}

@endpoint DELETE /collections/{collectionName}
@desc Delete Collection
@returns(202) The collection has been successfully deleted.
@errors {404: Collection not found., 500: Internal error. Can be caused by invalid parameters.}

@endgroup

@group databases
@endpoint GET /databases
@desc List indexes
@returns(200) This operation returns a list of all the indexes that you have previously created, and which are associated with the given API key

@endpoint POST /databases
@desc Create index
@required {name: str(IndexName) # The unique name of an index., dimension: int(int32) # The number of dimensions in the vector representation}
@optional {metric: str(euclidean/cosine/dotproduct) # The vector similarity metric of the index, pods: int(int32)=1 # The number of pods for the index to use,including replicas., replicas: int(int32)=1 # The number of replicas. Replicas duplicate your index. They provide higher availability and throughput., pod_type: str(s1.x1/s1.x2/s1.x4/s1.x8/p1.x1/p1.x2/p1.x4/p1.x8/p2.x1/p2.x2/p2.x4/p2.x8) # The pod type, metadata_config: map{indexed: [str]} # 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., source_collection: str(CollectionName) # The unique name of a collection.}
@returns(201) The collection has been successfully created.
@errors {400: Quota exceeded, or invalid parameters., 409: Index of given name already exists., 500: Internal error. Can be caused by invalid parameters.}

@endpoint GET /databases/{indexName}
@desc Describe index
@returns(200) {database: map{name: str(IndexName), metric: str, dimension: int(int32), replicas: int(int32), shards: int(int32), pods: int(int32), pod_type: str}, status: map{host: str(Hostname), port: int(int32), state: str(IndexState), ready: bool}} # This operation returns a list of all the collections in your current project.
@errors {404: Index not found., 500: Internal error. Can be caused by invalid parameters.}

@endpoint DELETE /databases/{indexName}
@desc Delete Index
@returns(202) The index has been successfully deleted.
@errors {404: Index not found., 500: Internal error. Can be caused by invalid parameters.}

@endpoint PATCH /databases/{indexName}
@desc Configure index
@optional {replicas: int(int32)=1 # The desired number of replicas for the index., pod_type: str(s1.x1/s1.x2/s1.x4/s1.x8/p1.x1/p1.x2/p1.x4/p1.x8/p2.x1/p2.x2/p2.x4/p2.x8) # The pod type}
@returns(201) The index has been successfully updated.
@errors {400: Quota exceeded, or invalid parameters., 404: Index not found., 500: Internal error. Can be caused by invalid parameters.}

@endgroup

@group describe_index_stats
@endpoint POST /describe_index_stats
@desc Describe Index Stats
@optional {filter: map # If this parameter is present, the operation only affects vectors that satisfy the filter. See https://www.pinecone.io/docs/metadata-filtering/.}
@returns(200) {namespaces: map, dimension: int(int32), indexFullness: num(float), totalVectorCount: int(int64)} # A successful response

@endgroup

@group query
@endpoint POST /query
@desc Query
@required {topK: int(int64)=100 # The number of results to return for each query.}
@optional {namespace: str(NamespaceName) # An index namespace name, filter: map # If this parameter is present, the operation only affects vectors that satisfy the filter. See https://www.pinecone.io/docs/metadata-filtering/., includeValues: bool=false, includeMetadata: bool=false, vector: [num(float)] # Vector dense data. This should be the same length as the dimension of the index being queried., sparseVector: map{indices!: [int(int64)], values!: [num(float)]} # Vector sparse data. Represented as a list of indices and a list of corresponded values, which must be the same length., id: str(VectorId) # The unique ID of a vector}
@returns(200) {matches: [map], namespace: str(NamespaceName)} # A successful response

@endgroup

@group vectors
@endpoint POST /vectors/delete
@desc Delete
@optional {ids: [str(VectorId)], deleteAll: bool=false, namespace: str(NamespaceName) # An index namespace name, filter: map # If this parameter is present, the operation only affects vectors that satisfy the filter. See https://www.pinecone.io/docs/metadata-filtering/.}
@returns(200) A successful response

@endpoint POST /vectors/fetch
@desc Fetch
@required {ids: [str(VectorId)]}
@optional {namespace: str(NamespaceName) # An index namespace name}
@returns(200) {vectors: map, namespace: str(NamespaceName)} # A successful response

@endpoint POST /vectors/update
@desc Fetch
@required {id: str(VectorId) # The vector's unique ID}
@optional {values: [num(float)] # Vector dense data. This should be the same length as the dimension of the index being queried., sparseValues: map{indices!: [int(int64)], values!: [num(float)]} # Vector sparse data. Represented as a list of indices and a list of corresponded values, which must be the same length., setMetadata: map, namespace: str(NamespaceName) # An index namespace name}
@returns(200) A successful response

@endpoint POST /vectors/upsert
@desc Upsert
@required {vectors: [map{id: str(VectorId), values: [num(float)], sparseValues: map, metadata: map}]}
@optional {namespace: str(NamespaceName) # An index namespace name}
@returns(200) {upsertedCount: int(int64)} # A successful response

@endgroup

@end