> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://cloud.meilisearch.com), select the **Search rules** tab, and click **New rule**. The visual editor opens. For a walkthrough of the editor, see [Create your first rule](https://www.meilisearch.com/docs/capabilities/search_rules/create_your_first_rule.md).

### Choose when the rule applies

Choose the index, here `products`. In the **Your rule** panel, select **These words**, then type `coffee` in the search bar. The rule now applies to every search containing that word, in any order, so it also covers "coffee machine" or "best coffee grinder".

### Pin the documents

To pin a document near the top, drag its card onto the position you want. For a document further down the results, hover its card and click the pin icon, then click the pin again and enter its new position in **Move to position**.

Pin the espresso machine at position `1`, then the coffee mug at position `2`. Each pinned card shows a filled pin, and the **What changes** section of the panel lists your pins in order.

![Visual editor with the espresso machine and the coffee mug pinned at positions 1 and 2, and both pins listed in the "What changes" section](https://mintcdn.com/meilisearch-6b28dec2/mjti93v8MIChJpXx/assets/images/cloud-search-rules/pin-two-documents.png?fit=max\&auto=format\&n=mjti93v8MIChJpXx\&q=85\&s=1d63421c47b6ea399e69e9644a12d160)

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

### Save the rule

Click **Save rule**. In the **Review and save** dialog, name the rule, such as `coffee-top-picks`, then click **Save and activate**. 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

> [!WARNING]
>
> Turn on Search Rules before you call the `/dynamic-search-rules` routes, otherwise Meilisearch returns an error. See [Create your first rule](https://www.meilisearch.com/docs/capabilities/search_rules/create_your_first_rule.md#turn-on-search-rules-2).

```bash cURL theme={null}
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](https://www.meilisearch.com/docs/capabilities/search_rules/advanced/specific_behaviors.md).

Meilisearch answers with a summarized task containing a `taskUid`, because creating a rule is an [asynchronous operation](https://www.meilisearch.com/docs/capabilities/indexing/tasks_and_batches/async_operations.md):

```json theme={null}
{
  "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](https://www.meilisearch.com/docs/reference/api/tasks/get-task.md).

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

## Next steps

> [card] [Boost documents](https://www.meilisearch.com/docs/capabilities/search_rules/how_to/boost_documents.md)
>
> Rank a selection of documents higher during a campaign

> [card] [Hide documents](https://www.meilisearch.com/docs/capabilities/search_rules/how_to/hide_documents.md)
>
> Remove documents from the results without reindexing

> [card] [Specific behaviors](https://www.meilisearch.com/docs/capabilities/search_rules/advanced/specific_behaviors.md)
>
> See how pins interact with filters and with the other actions

> [card] [API reference](https://www.meilisearch.com/docs/reference/api/search-rules/create-or-update-a-search-rule.md)
>
> Endpoints, rule fields, and update behavior


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.