POST
/
v1
/
features
/
search
curl --request POST \
  --url https://api.mixpeek.com/v1/features/search \
  --header 'Content-Type: application/json' \
  --data '{
  "queries": [
    {
      "embedding_model": "image",
      "settings": {
        "limit": 50,
        "min_score": 0.7
      },
      "type": "url",
      "value": "https://example.com/dog.jpg"
    },
    {
      "embedding_model": "text",
      "type": "text",
      "value": "This is a text query"
    }
  ],
  "collections": [
    "collection1",
    "collection2"
  ],
  "filters": {
    "case_sensitive": true,
    "AND": [
      {
        "key": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "key": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "key": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "key": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOR": [
      {
        "key": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "key": "location",
        "operator": "eq",
        "value": "remote"
      }
    ]
  },
  "group_by": {
    "field": "asset_id",
    "max_features": 10,
    "sort": {
      "direction": "desc",
      "field": "metadata.field_name"
    }
  },
  "sort": {
    "direction": "desc",
    "field": "score"
  },
  "select": [
    "title",
    "content",
    "metadata.author",
    "metadata.publication_date"
  ],
  "reranking_options": {
    "weights": {
      "feedback": 0.7,
      "popularity": 0.3
    },
    "enable_reranking": true
  },
  "session_id": "sess_abc123",
  "return_url": true
}'
{}

Headers

​
Authorization
string | null

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings. Example: 'Bearer sk_1234567890abcdef'

​
X-Namespace
string | null

Optional namespace for data isolation. This can be a namespace name or namespace ID. Example: 'netflix_prod' or 'ns_1234567890'. To create a namespace, use the /namespaces endpoint.

Query Parameters

​
offset_position
integer | null

The position to start returning results from. Used for pagination. Does not work with group_by

​
page_size
integer
default:
10

Number of results to return per page.

Required range: 1 <= x <= 100

Body

application/json
​
collections
string[]
required

List of Collection names to search within, required

​
queries
object[] | null

List of search queries to perform.

    Behavior:
    - Single query: Results are returned directly from that query
    - Multiple queries: Results are combined using Reciprocal Rank Fusion (RRF)
    
    RRF combines results from multiple queries by:
    1. Taking each item's rank position in each result list
    2. Re-ranking all items by their combined RRF scores
    
    When merging lists from different sources, 
    RRF considers all items that appear in any of the input lists, 
    not just items that appear in all lists.
    
    This helps surface items that rank well across multiple queries while
    reducing the impact of outlier high rankings in single queries.
    
    NOTE: If query array is empty, it will return all features.
​
filters
object | null

Used for filtering across all indexes

​
group_by
object | null

Grouping options for search results

​
sort
object | null

List of fields to sort by, with direction (asc or desc). Supports dot notation for nested fields.

​
select
string[] | null

List of fields to return in results, supports dot notation. If None, all fields are returned.

​
reranking_options
object | null

Options for ranking the search results, including weights and feedback application

​
session_id
string | null

Identifier for tracking search session interactions

​
return_url
boolean | null
default:
false

Return the presigned URL for the asset and preview asset, this will introduce additional latency

Response

200
application/json
Successful Response

The response is of type object.

Was this page helpful?

Suggest editsRaise issue
HealthcheckGet Feature