release: 0.54.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.53.0"
+  ".": "0.54.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 56
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/mixedbread/mixedbread-a5ced984ffa6baffe454ae18348039c0c7e0ac2c1a3b59875e8b3352d4af2ac5.yml
+configured_endpoints: 57
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/mixedbread/mixedbread-3e37dbb8d316c2b8143c1c2c56b07722f3a30e4e7a58edecf9f4a99abb1f6370.yml
 openapi_spec_hash: c22196b7ee066ff04308ca2debc619ff
-config_hash: ea30439e415ad92fd65dd21586143acc
+config_hash: bb119b05c8fe0fb669267c4dfbab34e6

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.54.0 (2026-05-21)
+
+Full Changelog: [v0.53.0...v0.54.0](https://github.com/mixedbread-ai/mixedbread-python/compare/v0.53.0...v0.54.0)
+
+### Features
+
+* **api:** add list_chunks ([33eefb1](https://github.com/mixedbread-ai/mixedbread-python/commit/33eefb1c49fc766d9bd423fbc20f226d30a1a22e))
+
 ## 0.53.0 (2026-05-21)
 
 Full Changelog: [v0.52.0...v0.53.0](https://github.com/mixedbread-ai/mixedbread-python/compare/v0.52.0...v0.53.0)

api.md

@@ -55,6 +55,7 @@ from mixedbread.types import (
     VideoURL,
     StoreDeleteResponse,
     StoreGrepResponse,
+    StoreListChunksResponse,
     StoreMetadataFacetsResponse,
     StoreQuestionAnsweringResponse,
     StoreSearchResponse,
@@ -69,6 +70,7 @@ Methods:
 - <code title="get /v1/stores">client.stores.<a href="./src/mixedbread/resources/stores/stores.py">list</a>(\*\*<a href="src/mixedbread/types/store_list_params.py">params</a>) -> <a href="./src/mixedbread/types/store.py">SyncCursor[Store]</a></code>
 - <code title="delete /v1/stores/{store_identifier}">client.stores.<a href="./src/mixedbread/resources/stores/stores.py">delete</a>(store_identifier) -> <a href="./src/mixedbread/types/store_delete_response.py">StoreDeleteResponse</a></code>
 - <code title="post /v1/stores/grep">client.stores.<a href="./src/mixedbread/resources/stores/stores.py">grep</a>(\*\*<a href="src/mixedbread/types/store_grep_params.py">params</a>) -> <a href="./src/mixedbread/types/store_grep_response.py">StoreGrepResponse</a></code>
+- <code title="post /v1/stores/list-chunks">client.stores.<a href="./src/mixedbread/resources/stores/stores.py">list_chunks</a>(\*\*<a href="src/mixedbread/types/store_list_chunks_params.py">params</a>) -> <a href="./src/mixedbread/types/store_list_chunks_response.py">StoreListChunksResponse</a></code>
 - <code title="post /v1/stores/metadata-facets">client.stores.<a href="./src/mixedbread/resources/stores/stores.py">metadata_facets</a>(\*\*<a href="src/mixedbread/types/store_metadata_facets_params.py">params</a>) -> <a href="./src/mixedbread/types/store_metadata_facets_response.py">StoreMetadataFacetsResponse</a></code>
 - <code title="post /v1/stores/question-answering">client.stores.<a href="./src/mixedbread/resources/stores/stores.py">question_answering</a>(\*\*<a href="src/mixedbread/types/store_question_answering_params.py">params</a>) -> <a href="./src/mixedbread/types/store_question_answering_response.py">StoreQuestionAnsweringResponse</a></code>
 - <code title="post /v1/stores/search">client.stores.<a href="./src/mixedbread/resources/stores/stores.py">search</a>(\*\*<a href="src/mixedbread/types/store_search_params.py">params</a>) -> <a href="./src/mixedbread/types/store_search_response.py">StoreSearchResponse</a></code>

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mixedbread"
-version = "0.53.0"
+version = "0.54.0"
 description = "The official Python library for the Mixedbread API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/mixedbread/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "mixedbread"
-__version__ = "0.53.0"  # x-release-please-version
+__version__ = "0.54.0"  # x-release-please-version

src/mixedbread/resources/stores/stores.py

@@ -21,6 +21,7 @@
     store_create_params,
     store_search_params,
     store_update_params,
+    store_list_chunks_params,
     store_metadata_facets_params,
     store_question_answering_params,
 )
@@ -42,6 +43,7 @@
 from ...types.store_grep_response import StoreGrepResponse
 from ...types.store_delete_response import StoreDeleteResponse
 from ...types.store_search_response import StoreSearchResponse
+from ...types.store_list_chunks_response import StoreListChunksResponse
 from ...types.store_metadata_facets_response import StoreMetadataFacetsResponse
 from ...types.store_chunk_search_options_param import StoreChunkSearchOptionsParam
 from ...types.store_question_answering_response import StoreQuestionAnsweringResponse
@@ -449,6 +451,88 @@ def grep(
             cast_to=StoreGrepResponse,
         )
 
+    def list_chunks(
+        self,
+        *,
+        store_identifiers: SequenceNotStr[str],
+        top_k: int | Omit = omit,
+        filters: Optional[store_list_chunks_params.Filters] | Omit = omit,
+        file_ids: Union[Iterable[object], SequenceNotStr[str], None] | Omit = omit,
+        sort_by: Union[str, Iterable[object], None] | Omit = omit,
+        search_options: StoreChunkSearchOptionsParam | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> StoreListChunksResponse:
+        """
+        List store chunks purely by metadata filters — no embeddings, no semantic
+        similarity, no reranking.
+
+        Unlike `/stores/search`, this endpoint does not require a query and never runs a
+        vector lookup. It returns chunks whose file and chunk metadata satisfy
+        `filters`, optionally ordered by a numeric metadata field via `sort_by`. Useful
+        for ranked retrieval over numeric attributes (e.g. price, BPM) and for
+        reproducing the agentic `filter_chunks` tool externally.
+
+        list-chunks targets a single store and does not support pagination; raise
+        `top_k` to retrieve more chunks.
+
+        Args: filter_params: Filter configuration including: - store_identifiers: the
+        single store to filter against - filters: optional metadata filter conditions -
+        file_ids: optional list of file IDs to filter chunks by - sort_by: optional
+        metadata field path, or `(field, ascending)` tuple, for numeric ordering -
+        top_k: number of chunks to return
+
+        Returns: StoreListChunksResponse containing the list of matching chunks.
+
+        Raises: HTTPException (400): If filter parameters are invalid or multiple stores
+        are passed HTTPException (404): If the store is not found
+
+        Args:
+          store_identifiers: IDs or names of stores
+
+          top_k: Number of results to return
+
+          filters: Optional filter conditions
+
+          file_ids: Optional list of file IDs to filter chunks by (inclusion filter)
+
+          sort_by: Optional sort applied to the returned chunks. Pass a metadata field path or a
+              tuple of (field path, ascending). Unprefixed dot paths target file metadata;
+              generated_metadata.\\** targets chunk metadata.
+
+          search_options: Search configuration options
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/v1/stores/list-chunks",
+            body=maybe_transform(
+                {
+                    "store_identifiers": store_identifiers,
+                    "top_k": top_k,
+                    "filters": filters,
+                    "file_ids": file_ids,
+                    "sort_by": sort_by,
+                    "search_options": search_options,
+                },
+                store_list_chunks_params.StoreListChunksParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=StoreListChunksResponse,
+        )
+
     def metadata_facets(
         self,
         *,
@@ -1077,6 +1161,88 @@ async def grep(
             cast_to=StoreGrepResponse,
         )
 
+    async def list_chunks(
+        self,
+        *,
+        store_identifiers: SequenceNotStr[str],
+        top_k: int | Omit = omit,
+        filters: Optional[store_list_chunks_params.Filters] | Omit = omit,
+        file_ids: Union[Iterable[object], SequenceNotStr[str], None] | Omit = omit,
+        sort_by: Union[str, Iterable[object], None] | Omit = omit,
+        search_options: StoreChunkSearchOptionsParam | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> StoreListChunksResponse:
+        """
+        List store chunks purely by metadata filters — no embeddings, no semantic
+        similarity, no reranking.
+
+        Unlike `/stores/search`, this endpoint does not require a query and never runs a
+        vector lookup. It returns chunks whose file and chunk metadata satisfy
+        `filters`, optionally ordered by a numeric metadata field via `sort_by`. Useful
+        for ranked retrieval over numeric attributes (e.g. price, BPM) and for
+        reproducing the agentic `filter_chunks` tool externally.
+
+        list-chunks targets a single store and does not support pagination; raise
+        `top_k` to retrieve more chunks.
+
+        Args: filter_params: Filter configuration including: - store_identifiers: the
+        single store to filter against - filters: optional metadata filter conditions -
+        file_ids: optional list of file IDs to filter chunks by - sort_by: optional
+        metadata field path, or `(field, ascending)` tuple, for numeric ordering -
+        top_k: number of chunks to return
+
+        Returns: StoreListChunksResponse containing the list of matching chunks.
+
+        Raises: HTTPException (400): If filter parameters are invalid or multiple stores
+        are passed HTTPException (404): If the store is not found
+
+        Args:
+          store_identifiers: IDs or names of stores
+
+          top_k: Number of results to return
+
+          filters: Optional filter conditions
+
+          file_ids: Optional list of file IDs to filter chunks by (inclusion filter)
+
+          sort_by: Optional sort applied to the returned chunks. Pass a metadata field path or a
+              tuple of (field path, ascending). Unprefixed dot paths target file metadata;
+              generated_metadata.\\** targets chunk metadata.
+
+          search_options: Search configuration options
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/v1/stores/list-chunks",
+            body=await async_maybe_transform(
+                {
+                    "store_identifiers": store_identifiers,
+                    "top_k": top_k,
+                    "filters": filters,
+                    "file_ids": file_ids,
+                    "sort_by": sort_by,
+                    "search_options": search_options,
+                },
+                store_list_chunks_params.StoreListChunksParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=StoreListChunksResponse,
+        )
+
     async def metadata_facets(
         self,
         *,
@@ -1327,6 +1493,9 @@ def __init__(self, stores: StoresResource) -> None:
         self.grep = to_raw_response_wrapper(
             stores.grep,
         )
+        self.list_chunks = to_raw_response_wrapper(
+            stores.list_chunks,
+        )
         self.metadata_facets = to_raw_response_wrapper(
             stores.metadata_facets,
         )
@@ -1364,6 +1533,9 @@ def __init__(self, stores: AsyncStoresResource) -> None:
         self.grep = async_to_raw_response_wrapper(
             stores.grep,
         )
+        self.list_chunks = async_to_raw_response_wrapper(
+            stores.list_chunks,
+        )
         self.metadata_facets = async_to_raw_response_wrapper(
             stores.metadata_facets,
         )
@@ -1401,6 +1573,9 @@ def __init__(self, stores: StoresResource) -> None:
         self.grep = to_streamed_response_wrapper(
             stores.grep,
         )
+        self.list_chunks = to_streamed_response_wrapper(
+            stores.list_chunks,
+        )
         self.metadata_facets = to_streamed_response_wrapper(
             stores.metadata_facets,
         )
@@ -1438,6 +1613,9 @@ def __init__(self, stores: AsyncStoresResource) -> None:
         self.grep = async_to_streamed_response_wrapper(
             stores.grep,
         )
+        self.list_chunks = async_to_streamed_response_wrapper(
+            stores.list_chunks,
+        )
         self.metadata_facets = async_to_streamed_response_wrapper(
             stores.metadata_facets,
         )

src/mixedbread/types/__init__.py

@@ -51,11 +51,13 @@
 from .linear_data_source_param import LinearDataSourceParam as LinearDataSourceParam
 from .multi_encoding_embedding import MultiEncodingEmbedding as MultiEncodingEmbedding
 from .notion_data_source_param import NotionDataSourceParam as NotionDataSourceParam
+from .store_list_chunks_params import StoreListChunksParams as StoreListChunksParams
 from .data_source_create_params import DataSourceCreateParams as DataSourceCreateParams
 from .data_source_oauth2_params import DataSourceOauth2Params as DataSourceOauth2Params
 from .data_source_update_params import DataSourceUpdateParams as DataSourceUpdateParams
 from .embedding_create_response import EmbeddingCreateResponse as EmbeddingCreateResponse
 from .data_source_api_key_params import DataSourceAPIKeyParams as DataSourceAPIKeyParams
+from .store_list_chunks_response import StoreListChunksResponse as StoreListChunksResponse
 from .agentic_search_config_param import AgenticSearchConfigParam as AgenticSearchConfigParam
 from .data_source_delete_response import DataSourceDeleteResponse as DataSourceDeleteResponse
 from .pdf_chunk_generated_metadata import PdfChunkGeneratedMetadata as PdfChunkGeneratedMetadata

src/mixedbread/types/store_list_chunks_params.py

@@ -0,0 +1,93 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Union, Iterable, Optional
+from typing_extensions import Required, TypeAlias, TypedDict
+
+from .._types import SequenceNotStr
+from .store_chunk_search_options_param import StoreChunkSearchOptionsParam
+from .shared_params.search_filter_condition import SearchFilterCondition
+
+__all__ = [
+    "StoreListChunksParams",
+    "Filters",
+    "FiltersSearchFilterInput",
+    "FiltersSearchFilterInputAll",
+    "FiltersSearchFilterInputAny",
+    "FiltersSearchFilterInputNone",
+    "FiltersUnionMember2",
+    "FiltersUnionMember2SearchFilterInput",
+    "FiltersUnionMember2SearchFilterInputAll",
+    "FiltersUnionMember2SearchFilterInputAny",
+    "FiltersUnionMember2SearchFilterInputNone",
+]
+
+
+class StoreListChunksParams(TypedDict, total=False):
+    store_identifiers: Required[SequenceNotStr[str]]
+    """IDs or names of stores"""
+
+    top_k: int
+    """Number of results to return"""
+
+    filters: Optional[Filters]
+    """Optional filter conditions"""
+
+    file_ids: Union[Iterable[object], SequenceNotStr[str], None]
+    """Optional list of file IDs to filter chunks by (inclusion filter)"""
+
+    sort_by: Union[str, Iterable[object], None]
+    """Optional sort applied to the returned chunks.
+
+    Pass a metadata field path or a tuple of (field path, ascending). Unprefixed dot
+    paths target file metadata; generated_metadata.\\** targets chunk metadata.
+    """
+
+    search_options: StoreChunkSearchOptionsParam
+    """Search configuration options"""
+
+
+FiltersSearchFilterInputAll: TypeAlias = Union[SearchFilterCondition, object]
+
+FiltersSearchFilterInputAny: TypeAlias = Union[SearchFilterCondition, object]
+
+FiltersSearchFilterInputNone: TypeAlias = Union[SearchFilterCondition, object]
+
+
+class FiltersSearchFilterInput(TypedDict, total=False):
+    """Represents a filter with AND, OR, and NOT conditions."""
+
+    all: Optional[Iterable[FiltersSearchFilterInputAll]]
+    """List of conditions or filters to be ANDed together"""
+
+    any: Optional[Iterable[FiltersSearchFilterInputAny]]
+    """List of conditions or filters to be ORed together"""
+
+    none: Optional[Iterable[FiltersSearchFilterInputNone]]
+    """List of conditions or filters to be NOTed"""
+
+
+FiltersUnionMember2SearchFilterInputAll: TypeAlias = Union[SearchFilterCondition, object]
+
+FiltersUnionMember2SearchFilterInputAny: TypeAlias = Union[SearchFilterCondition, object]
+
+FiltersUnionMember2SearchFilterInputNone: TypeAlias = Union[SearchFilterCondition, object]
+
+
+class FiltersUnionMember2SearchFilterInput(TypedDict, total=False):
+    """Represents a filter with AND, OR, and NOT conditions."""
+
+    all: Optional[Iterable[FiltersUnionMember2SearchFilterInputAll]]
+    """List of conditions or filters to be ANDed together"""
+
+    any: Optional[Iterable[FiltersUnionMember2SearchFilterInputAny]]
+    """List of conditions or filters to be ORed together"""
+
+    none: Optional[Iterable[FiltersUnionMember2SearchFilterInputNone]]
+    """List of conditions or filters to be NOTed"""
+
+
+FiltersUnionMember2: TypeAlias = Union[FiltersUnionMember2SearchFilterInput, SearchFilterCondition]
+
+Filters: TypeAlias = Union[FiltersSearchFilterInput, SearchFilterCondition, Iterable[FiltersUnionMember2]]