> ## 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.
# Getting started with search rules
> Enable search rules, create your first rule, and verify how pinned results appear in search.
This guide walks you through enabling the experimental flag, creating your first rule, and checking how it affects search results. You can do this from the Meilisearch Cloud dashboard or directly against the API.
## Set up from the Meilisearch Cloud dashboard
Open your project in the [Meilisearch Cloud dashboard](https://cloud.meilisearch.com) and select the **Search rules** tab.
### Activate the feature
Search rules are an add-on. On the Search rules tab, click **Enable Search Rules** to turn on the `dynamicSearchRules` experimental flag for the project.
### Create your first rule
Once the feature is active, the Search rules tab shows a short explainer and a **New rule** button. Click it to start building a rule.
### Fill in the rule's general information
Give the rule a **Rule ID** (used as the `uid`), an optional **Description**, and a **Priority** if several rules might match the same query. Keep the **Active** toggle on to apply the rule at search time.
### Add conditions
In the **Conditions** block, click **Add condition** to open the condition dialog. Pick a type (**Query contains**, **Query is empty**, or **Time window**) and fill in the value. Every condition you add is combined with `AND`, so the rule fires only when all conditions are true at the same time.
### Pin documents to fixed positions
In the **Actions** block, click **Add pin**. Choose the source **Index**, pick the **Document** to promote, and set its target **Position** in the result list. Repeat for each document you want to pin. When the rule is ready, click **Create rule**.
### Review and manage your rules
Back on the Search rules tab, every rule you have created is listed with its conditions, actions, priority, and active state. Use the row toggle to pause a rule without deleting it, or the icons on the right to edit or remove it.
## Set up from the API
Prefer the API? The same flow maps directly to the `/dynamic-search-rules` routes.
### Enable the experimental flag
Send a `PATCH /experimental-features` to turn on the feature:
```json theme={null}
{
"dynamicSearchRules": true
}
```
While the flag is disabled, the `/dynamic-search-rules` routes reject requests and saved rules do not apply at search time.
### Create a rule
Create a rule with `PATCH /dynamic-search-rules/invoice-help`:
```json theme={null}
{
"description": "Promote billing help for invoice searches",
"active": true,
"conditions": [
{ "scope": "query", "contains": "invoice" }
],
"actions": [
{
"selector": { "indexUid": "support", "id": "billing-workspace-overview" },
"action": { "type": "pin", "position": 0 }
}
]
}
```
This rule pins the document `billing-workspace-overview` in the `support` index to the first position whenever a query contains the substring `invoice`.
The route behaves as an upsert:
* It returns `201 Created` when the rule does not exist yet
* It returns `200 OK` when you update an existing rule
### Check the stored rule
Retrieve the rule you just created with `GET /dynamic-search-rules/invoice-help`. The response should include the `uid`, conditions, and actions you sent:
```json theme={null}
{
"uid": "invoice-help",
"description": "Promote billing help for invoice searches",
"active": true,
"conditions": [
{ "scope": "query", "contains": "invoice" }
],
"actions": [
{
"selector": { "indexUid": "support", "id": "billing-workspace-overview" },
"action": { "type": "pin", "position": 0 }
}
]
}
```
### Run a matching search
Send a normal search request to the index, for example `POST /indexes/support/search`:
```json theme={null}
{
"q": "invoice settings"
}
```
If `billing-workspace-overview` exists in the `support` index and survives the current filters, Meilisearch inserts it at position `0`. The rest of the response is the normal organic result set, with duplicates removed.
Search rules do not replace organic results. Meilisearch still computes them, then inserts the pinned documents on top.
## Next steps
Promote a landing page or help article for a query
Learn how search rules interact with ranking and filters
Review endpoints and request fields
Learn more about experimental feature management