@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Pinecone Control Plane API
@base https://api.pinecone.io
@version 2026-04
@auth ApiKey Api-Key in header
@common_fields {X-Pinecone-Api-Version: str=2026-04}
@endpoints 18
@toc indexes(8), collections(4), backups(4), restore-jobs(2)

@group indexes
@endpoint GET /indexes
@returns(200) {indexes: [map]}
@errors {401, 500}

@endpoint POST /indexes
@required {name: str, spec: map}
@optional {dimension: int(int32), metric: str, deletion_protection: str=disabled, tags: map, vector_type: str=dense}
@returns(201) {name: str, dimension: int(int32), metric: str, host: str, private_host: str, deletion_protection: str, tags: map, embed: map{model: str, metric: str, dimension: int(int32), vector_type: str, field_map: map, read_parameters: map, write_parameters: map}, spec: map, status: map{ready: bool, state: str}, vector_type: str}
@errors {400, 401, 402, 403, 404, 422, 409, 500}

@endpoint GET /indexes/{index_name}
@required {index_name: str}
@returns(200) {name: str, dimension: int(int32), metric: str, host: str, private_host: str, deletion_protection: str, tags: map, embed: map{model: str, metric: str, dimension: int(int32), vector_type: str, field_map: map, read_parameters: map, write_parameters: map}, spec: map, status: map{ready: bool, state: str}, vector_type: str}
@errors {401, 404, 500}

@endpoint DELETE /indexes/{index_name}
@required {index_name: str}
@returns(202)
@errors {401, 403, 404, 412, 500}

@endpoint PATCH /indexes/{index_name}
@required {index_name: str}
@optional {spec: any, deletion_protection: str=disabled, tags: map, embed: map{model: str, field_map: map, read_parameters: map, write_parameters: map}}
@returns(202) {name: str, dimension: int(int32), metric: str, host: str, private_host: str, deletion_protection: str, tags: map, embed: map{model: str, metric: str, dimension: int(int32), vector_type: str, field_map: map, read_parameters: map, write_parameters: map}, spec: map, status: map{ready: bool, state: str}, vector_type: str}
@errors {400, 401, 402, 403, 404, 422, 500}

@endpoint GET /indexes/{index_name}/backups
@required {index_name: str}
@optional {limit: int=10, paginationToken: str}
@returns(200) {data: [map], pagination: map{next: str}}
@errors {401, 404, 500}

@endpoint POST /indexes/{index_name}/backups
@required {index_name: str}
@optional {name: str, description: str}
@returns(201) {backup_id: str, source_index_name: str, source_index_id: str, name: str, description: str, status: str, cloud: str, region: str, dimension: int(int32), metric: str, schema: map{fields: map}, record_count: int, namespace_count: int, size_bytes: int, tags: map, created_at: str}
@errors {400, 401, 402, 403, 422, 500}

@endgroup

@group collections
@endpoint GET /collections
@returns(200) {collections: [map]}
@errors {401, 500}

@endpoint POST /collections
@required {name: str, source: str}
@returns(201) {name: str, size: int(int64), status: str, dimension: int(int32), vector_count: int(int32), environment: str}
@errors {400, 401, 402, 403, 409, 422, 500}

@endgroup

@group indexes
@endpoint POST /indexes/create-for-model
@required {name: str, cloud: str, region: str, embed: map{model!: str, metric: str, field_map!: map, dimension: int, read_parameters: map, write_parameters: map}}
@optional {deletion_protection: str=disabled, tags: map, schema: map{fields!: map}, read_capacity: any}
@returns(201) {name: str, dimension: int(int32), metric: str, host: str, private_host: str, deletion_protection: str, tags: map, embed: map{model: str, metric: str, dimension: int(int32), vector_type: str, field_map: map, read_parameters: map, write_parameters: map}, spec: map, status: map{ready: bool, state: str}, vector_type: str}
@errors {400, 401, 404, 409, 422, 500}

@endgroup

@group backups
@endpoint GET /backups
@optional {limit: int=10, paginationToken: str}
@returns(200) {data: [map], pagination: map{next: str}}
@errors {401, 500}

@endpoint GET /backups/{backup_id}
@required {backup_id: str}
@returns(200) {backup_id: str, source_index_name: str, source_index_id: str, name: str, description: str, status: str, cloud: str, region: str, dimension: int(int32), metric: str, schema: map{fields: map}, record_count: int, namespace_count: int, size_bytes: int, tags: map, created_at: str}
@errors {401, 404, 500}

@endpoint DELETE /backups/{backup_id}
@required {backup_id: str}
@returns(202)
@errors {401, 404, 412, 500}

@endpoint POST /backups/{backup_id}/create-index
@required {backup_id: str, name: str}
@optional {tags: map, deletion_protection: str=disabled}
@returns(202) {restore_job_id: str, index_id: str}
@errors {400, 401, 402, 403, 404, 409, 422, 500}

@endgroup

@group restore-jobs
@endpoint GET /restore-jobs
@optional {limit: int=10, paginationToken: str}
@returns(200) {data: [map], pagination: map{next: str}}
@errors {401, 500}

@endpoint GET /restore-jobs/{job_id}
@required {job_id: str}
@returns(200) {restore_job_id: str, backup_id: str, target_index_name: str, target_index_id: str, status: str, created_at: str(date-time), completed_at: str(date-time), percent_complete: num(float)}
@errors {401, 404, 500}

@endgroup

@group collections
@endpoint GET /collections/{collection_name}
@required {collection_name: str}
@returns(200) {name: str, size: int(int64), status: str, dimension: int(int32), vector_count: int(int32), environment: str}
@errors {401, 404, 500}

@endpoint DELETE /collections/{collection_name}
@required {collection_name: str}
@returns(202)
@errors {401, 404, 500}

@endgroup

@end