Curation

Curation sets let you hand-tune results for specific queries: pin documents to fixed positions, hide documents, inject filters, override sorting, or replace the query entirely. Rules can match by query text, filter, tags, and time windows.

Create a Curation Set

PUT /curation_sets/promotions
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_API_KEY

{
  "items": [
    {
      "id": "featured-laptop",
      "rule": {"query": "laptop", "match": "exact"},
      "includes": [{"id": "prod-42", "position": 1}],
      "excludes": [{"id": "prod-13"}]
    }
  ]
}

Bind to a Collection

Collections reference curation sets in their schema - every search on the collection evaluates the bound sets:

{
  "name": "products",
  "curation_sets": ["promotions"],
  "fields": [ ... ]
}

Rules

A rule decides when an item applies:

Field	Description
`query` + `match`	Match the search's `q`: `exact` or `contains`. `"query": "*"` matches every query.
`filter_by`	Applies when the search's `filter_by` parameter equals this exactly
`tags`	Applies when the search passes a matching `curation_tags` parameter

Item Actions

Field	Description
`includes`	Pin documents to 1-based positions: `[{"id": "doc1", "position": 1}]`
`excludes`	Hide documents from the results entirely
`filter_by`	Extra filter AND-ed onto the search's filter
`sort_by`	Override the search's sort order
`replace_query`	Replace the query text before searching
`remove_matched_tokens`	Strip the rule's tokens from the query
`filter_curated_hits`	When `true`, pinned documents must also satisfy the search's `filter_by`
`stop_processing`	Stop evaluating further items after this one matches (default `true`)
`effective_from_ts` / `effective_to_ts`	Unix-timestamp window during which the item is active - schedule promotions ahead of time
`metadata`	Arbitrary JSON echoed in the search response when the item matches

Search Parameters

Parameter	Description
`curation_tags`	Comma-separated tags - only items whose rule tags match are evaluated
`enable_curations=false`	Skip curation evaluation for this query
`filter_curated_hits`	Per-query override of the item-level setting

Curation applies in both single search and multi-search. Pinned documents surface in grouped results at the pinned position.

API Reference

# Sets
GET    /curation_sets                    # list all sets
PUT    /curation_sets/{name}             # create or replace a set
GET    /curation_sets/{name}             # get a set
DELETE /curation_sets/{name}             # delete a set

# Items within a set
GET    /curation_sets/{name}/items       # list items
PUT    /curation_sets/{name}/items/{id}  # create or update an item
GET    /curation_sets/{name}/items/{id}  # get an item
DELETE /curation_sets/{name}/items/{id}  # delete an item