Pin several documents for a query

Control the first positions of your results by combining several pin actions in one rule.

When customers search for “coffee”, you know what they should see first: the espresso machine you promote this month, then the mug that goes with it. One pin controls one position, so a rule with several pin actions builds the top of your results in the order you choose. Organic results fill everything below.

Set up from the Meilisearch Cloud dashboard

Open your project in the Meilisearch Cloud dashboard, select the Search rules tab, and click New rule. Give the rule an ID, such as coffee-top-picks, and a description.

Pin the first document

In the Actions block, click Add action, select Pin a document, then click Next. Choose the Index, then search the Document by its ID or its content. Set its Position, which starts at 1 for the first result, and click Add action.

Pin the next ones

Repeat the same steps for every document you want to place, here the coffee mug at position 2. The Actions block numbers your pins and shows which document each one promotes.

Pins do not have to follow each other. Pinning at positions 1 and 5 leaves organic results in between.

Choose when the rule applies

In the Conditions block, set Query to Contains all words, then enter coffee. The rule now applies to every search containing that word, in any order, so it also covers “coffee machine” or “best coffee grinder”.

Click Create rule. Meilisearch indexes the rule, which can take a few seconds to a few minutes. Once it is live, a search containing “coffee” starts with your two picks, in the order you chose.

Set up on a self-hosted instance

Search rules must be turned on before you call the /dynamic-search-rules routes, otherwise Meilisearch returns an error. See Create your first rule.

cURL

curl \
  -X PATCH 'MEILISEARCH_URL/dynamic-search-rules/coffee-top-picks' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "Show our two coffee picks first for coffee searches",
    "active": true,
    "conditions": {
      "query": {
        "words": "coffee"
      }
    },
    "actions": {
      "pin": [
        {
          "indexUid": "products",
          "id": "5",
          "position": 0
        },
        {
          "indexUid": "products",
          "id": "3",
          "position": 1
        }
      ]
    }
  }'

• Each entry in pin places one document at one position. The order of the entries does not matter, the position values do.
• Positions count from 0 in the API, so 0 is the first result. The dashboard displays the same slot as position 1.
• If the current search filters exclude a pinned document, Meilisearch drops that pin and an organic result takes the slot. The other pins stay where you put them. See specific behaviors.

Meilisearch answers with a summarized task containing a taskUid, because creating a rule is an asynchronous operation:

{
  "taskUid": 46,
  "indexUid": ".meili_dsr",
  "status": "enqueued",
  "type": "dsrUpdate",
  "enqueuedAt": "2026-05-28T09:12:41.157267963Z"
}

The rule applies to searches once this task reaches the succeeded status. To follow its progress, pass the taskUid to the task API.

From then on, every search containing “coffee” starts with your two picks, in the order you chose, and the organic results follow.

Next steps

Boost documents

Rank a selection of documents higher during a campaign

Hide documents

Remove documents from the results without reindexing

Specific behaviors

See how pins interact with filters and with the other actions

API reference

Endpoints, rule fields, and update behavior