Create Interaction

POST

features

interactions

object

feature_id

string

interaction_type

enum<string>

search_request

object

queries

array

queries

Required

array

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.

Add Example Value

collections

array

filters

object

case_sensitive

boolean

AND

array

NOR

array

group_by

object

field

string

field

string

    Field to group by
    
    Note: We currently do not support ad-hoc grouping.
    This means the field must be indexed separately. 
    Please contact us to add additional fields for grouping.

Add Example Value

max_features

integer

sort

object

field

string

direction

enum<string>

sort

object

field

string

direction

enum<string>

select

array

reranking_options

object

weights

object

weights

object

    Weights to blend different ranking signals. Must sum to 1.0.
    - feedback: Weight for feedback-based score (positive, negative)
    - popularity: Weight for user interaction signals (clicks, views)

Add Example Value

enable_reranking

boolean

enable_reranking

boolean

    Enable interaction-based score adjustments.
    When enabled, historical interactions will influence ranking:
    - Positive feedback and clicks boost scores
    - Negative feedback reduces scores
    - View duration and skip signals are considered
    - Adjustments are weighted by recency

Add Example Value

session_id

string

return_url

boolean

position

integer

metadata

object

session_id

string

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.

Body

application/json

feature_id

string

required

ID of the item that was interacted with

interaction_type

enum<string>

required

Type of interaction or feedback

Available options:

view,

click,

positive_feedback,

negative_feedback

search_request

object | null

The search request that led to this interaction

search_request.queries

object[]

required

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.

search_request.queries.vector_index

enum<string>

required

Name of the vector index to search

Available options:

image,

multimodal,

text,

video,

keyword

search_request.queries.value

string

required

Query value - can be text, URL, or base64 encoded image

search_request.queries.type

enum<string>

required

Type of input (text, url, or base64)

Available options:

text,

url,

base64

search_request.queries.filters

object | null

Optional filters for the query, this is used for filtering individual vector indexes

search_request.queries.settings

object | null

Optional settings for this specific query

search_request.collections

string[]

required

List of Collection names to search within, required

search_request.filters

object | null

Used for filtering across all indexes

search_request.filters.case_sensitive

boolean | null

default: false

Whether to perform case-sensitive matching

search_request.filters.AND

object[] | null

Logical AND operation

search_request.filters.OR

object[] | null

Logical OR operation

search_request.filters.NOR

object[] | null

Logical NOR operation

search_request.group_by

object | null

Grouping options for search results

search_request.group_by.field

string | null

default: asset_id

    Field to group by
    
    Note: We currently do not support ad-hoc grouping.
    This means the field must be indexed separately. 
    Please contact us to add additional fields for grouping.

search_request.group_by.max_features

integer | null

default: 10

Maximum number of features to group

search_request.group_by.sort

object | null

Sort options for ordering the inside of the groups

search_request.sort

object | null

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

search_request.select

string[] | null

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

search_request.reranking_options

object | null

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

search_request.reranking_options.weights

object

    Weights to blend different ranking signals. Must sum to 1.0.
    - feedback: Weight for feedback-based score (positive, negative)
    - popularity: Weight for user interaction signals (clicks, views)

search_request.reranking_options.enable_reranking

boolean

default: false

    Enable interaction-based score adjustments.
    When enabled, historical interactions will influence ranking:
    - Positive feedback and clicks boost scores
    - Negative feedback reduces scores
    - View duration and skip signals are considered
    - Adjustments are weighted by recency

search_request.session_id

string | null

Identifier for tracking search session interactions

search_request.return_url

boolean | null

default: false

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

position

integer | null

Position in search results where interaction occurred

metadata

object | null

Additional context about the interaction

session_id

string | null

Search session identifier

Response

200 - application/json

feature_id

string

required

ID of the item that was interacted with

interaction_type

enum<string>

required

Type of interaction or feedback

Available options:

view,

click,

positive_feedback,

negative_feedback

interaction_id

string

required

Unique identifier for this interaction

search_request

object | null

The search request that led to this interaction

search_request.queries

object[]

required

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.

search_request.queries.vector_index

enum<string>

required

Name of the vector index to search

Available options:

image,

multimodal,

text,

video,

keyword

search_request.queries.value

string

required

Query value - can be text, URL, or base64 encoded image

search_request.queries.type

enum<string>

required

Type of input (text, url, or base64)

Available options:

text,

url,

base64

search_request.queries.filters

object | null

Optional filters for the query, this is used for filtering individual vector indexes

search_request.queries.settings

object | null

Optional settings for this specific query

search_request.collections

string[]

required

List of Collection names to search within, required

search_request.filters

object | null

Used for filtering across all indexes

search_request.filters.case_sensitive

boolean | null

default: false

Whether to perform case-sensitive matching

search_request.filters.AND

object[] | null

Logical AND operation

search_request.filters.OR

object[] | null

Logical OR operation

search_request.filters.NOR

object[] | null

Logical NOR operation

search_request.group_by

object | null

Grouping options for search results

search_request.group_by.field

string | null

default: asset_id

    Field to group by
    
    Note: We currently do not support ad-hoc grouping.
    This means the field must be indexed separately. 
    Please contact us to add additional fields for grouping.

search_request.group_by.max_features

integer | null

default: 10

Maximum number of features to group

search_request.group_by.sort

object | null

Sort options for ordering the inside of the groups

search_request.sort

object | null

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

search_request.select

string[] | null

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

search_request.reranking_options

object | null

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

search_request.reranking_options.weights

object

    Weights to blend different ranking signals. Must sum to 1.0.
    - feedback: Weight for feedback-based score (positive, negative)
    - popularity: Weight for user interaction signals (clicks, views)

search_request.reranking_options.enable_reranking

boolean

default: false

    Enable interaction-based score adjustments.
    When enabled, historical interactions will influence ranking:
    - Positive feedback and clicks boost scores
    - Negative feedback reduces scores
    - View duration and skip signals are considered
    - Adjustments are weighted by recency

search_request.session_id

string | null

Identifier for tracking search session interactions

search_request.return_url

boolean | null

default: false

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

position

integer | null

Position in search results where interaction occurred

metadata

object | null

Additional context about the interaction

session_id

string | null

Search session identifier

Was this page helpful?

List Interactions Get Interaction

Health

Ingest

Features

Collections

Namespaces

Search Interactions

Entities

Assets

Percolators

Organizations

Collections

Tasks

Feature Extractors

Create Interaction

Headers

Body

Response