@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Pinecone Data Plane API
@base https://{index_host}
@version 2026-04
@auth ApiKey Api-Key in header
@common_fields {X-Pinecone-Api-Version: str=2026-04}
@endpoints 18
@toc bulk(4), describe_index_stats(1), query(1), vectors(6), namespaces(4), records(2)

@group bulk
@endpoint GET /bulk/imports
@optional {limit: int(int32)=100, paginationToken: str}
@returns(200) {data: [map], pagination: map{next: str}}
@errors {400, 4XX, 5XX}

@endpoint POST /bulk/imports
@required {uri: str}
@optional {integrationId: str, errorMode: map{onError: str}}
@returns(200) {id: str}
@errors {400, 4XX, 5XX}

@endpoint GET /bulk/imports/{id}
@required {id: str}
@returns(200) {id: str, uri: str, status: str, createdAt: str(date-time), finishedAt: str(date-time), percentComplete: num(float), recordsImported: int(int64), error: str}
@errors {400, 4XX, 5XX}

@endpoint DELETE /bulk/imports/{id}
@required {id: str}
@returns(200)
@errors {400, 4XX, 5XX}

@endgroup

@group describe_index_stats
@endpoint POST /describe_index_stats
@optional {filter: map}
@returns(200) {namespaces: map, dimension: int(int64), indexFullness: num(float), totalVectorCount: int(int64), metric: str, vectorType: str, memory_fullness: num(float), storage_fullness: num(float)}
@errors {400, 4XX, 5XX}

@endgroup

@group query
@endpoint POST /query
@required {topK: int(int64)}
@optional {namespace: str, filter: map, includeValues: bool=False, includeMetadata: bool=False, queries: [map{values!: [num(float)], sparseValues: map{indices!: [int(int64)], values!: [num(float)]}, topK: int(int64), namespace: str, filter: map}], vector: [num(float)], sparseVector: map{indices!: [int(int64)], values!: [num(float)]}, id: str, scanFactor: num(float), maxCandidates: int(int64)}
@returns(200) {results: [map], matches: [map], namespace: str, usage: map{readUnits: int(int64)}}
@errors {400, 4XX, 5XX}

@endgroup

@group vectors
@endpoint POST /vectors/delete
@optional {ids: [str], deleteAll: bool=False, namespace: str, filter: map}
@returns(200)
@errors {400, 4XX, 5XX}

@endpoint GET /vectors/fetch
@required {ids: [str]}
@optional {namespace: str}
@returns(200) {vectors: map, namespace: str, usage: map{readUnits: int(int64)}}
@errors {400, 4XX, 5XX}

@endpoint POST /vectors/fetch_by_metadata
@optional {namespace: str, filter: map, limit: int(int64)=100, paginationToken: str}
@returns(200) {vectors: map, namespace: str, usage: map{readUnits: int(int64)}, pagination: map{next: str}}
@errors {400, 4XX, 5XX}

@endpoint GET /vectors/list
@optional {prefix: str, limit: int(int64)=100, paginationToken: str, namespace: str}
@returns(200) {vectors: [map], pagination: map{next: str}, namespace: str, usage: map{readUnits: int(int64)}}
@errors {400, 4XX, 5XX}

@endpoint POST /vectors/update
@optional {id: str, values: [num(float)], sparseValues: map{indices!: [int(int64)], values!: [num(float)]}, setMetadata: map, namespace: str, filter: map, dryRun: bool=False}
@returns(200) {matchedRecords: int(int32)}
@errors {400, 4XX, 5XX}

@endpoint POST /vectors/upsert
@required {vectors: [map{id!: str, values: [num(float)], sparseValues: map{indices!: [int(int64)], values!: [num(float)]}, metadata: map}]}
@optional {namespace: str}
@returns(200) {upsertedCount: int(int64)}
@errors {400, 4XX, 5XX}

@endgroup

@group namespaces
@endpoint GET /namespaces
@optional {limit: int(int32), paginationToken: str, prefix: str}
@returns(200) {namespaces: [map], pagination: map{next: str}, total_count: int(int32)}
@errors {4XX, 5XX}

@endpoint POST /namespaces
@required {name: str}
@optional {schema: map{fields!: map}}
@returns(200) {name: str, record_count: int(int64), schema: map{fields: map}, indexed_fields: map{fields: [str]}}
@errors {400, 409, 4XX, 5XX}

@endpoint GET /namespaces/{namespace}
@required {namespace: str}
@returns(200) {name: str, record_count: int(int64), schema: map{fields: map}, indexed_fields: map{fields: [str]}}
@errors {400, 4XX, 5XX}

@endpoint DELETE /namespaces/{namespace}
@required {namespace: str}
@returns(200)
@errors {400, 4XX, 5XX}

@endgroup

@group records
@endpoint POST /records/namespaces/{namespace}/upsert
@required {namespace: str}
@returns(201)
@errors {400, 4XX, 5XX}

@endpoint POST /records/namespaces/{namespace}/search
@required {namespace: str, query: map{top_k!: int(int32), filter: map, inputs: map, vector: map{values: [num(float)], sparse_values: [num(float)], sparse_indices: [int(int32)]}, id: str, match_terms: map{strategy: str, terms: [str]}}}
@optional {fields: [str], rerank: map{model!: str, rank_fields!: [str], top_n: int(int32), parameters: map, query: str}}
@returns(200) {result: map{hits: [map]}, usage: map{read_units: int(int32), embed_total_tokens: int(int32), rerank_units: int(int32)}}
@errors {400, 4XX, 5XX}

@endgroup

@end