---
updatedAt: 2026-04-28T09:31:16.000Z
agentTools:
  projectIndex: https://docs.makaira.io/llms.txt
---

# Create a new search query hook

Creates a new search query hook. Search query hooks allow an external webhook URL to intercept and modify search requests or results at different stages of the search pipeline.

Requires authentication.

## Request

**`POST /search-query-hook`**

### Headers

| Header          | Value              |
| --------------- | ------------------ |
| `Authorization` | `Bearer <token>`   |
| `Content-Type`  | `application/json` |

### Request Body

| Field      | Type    | Required | Description                                                                                                                                                               |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | string  | Yes      | When the hook is executed. One of: `pre-search` (before the search query is sent), `post-search` (after results are returned), `modify-result` (to transform the result). |
| `target`   | string  | Yes      | Where the hook applies. One of: `search`, `recommendation`.                                                                                                               |
| `url`      | string  | Yes      | The URL of the external webhook endpoint that will receive and process the hook request.                                                                                  |
| `priority` | integer | No       | Execution priority when multiple hooks of the same type are configured. Higher values execute first.                                                                      |

### Example Request

```json
{
  "type": "post-search",
  "target": "search",
  "url": "https://my-service.example.com/hooks/search",
  "priority": 10
}
```

## Response

Returns the created search query hook object.

### Example Response

```json
{
  "id": 3,
  "type": "post-search",
  "target": "search",
  "url": "https://my-service.example.com/hooks/search",
  "priority": 10
}
```

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Makaira API",
    "version": "1.0",
    "contact": {
      "name": "Makaira GmbH",
      "url": "https://www.makaira.io/",
      "email": "support@makaira.io"
    },
    "description": "API of the powerful Makaira Search/Recommendation and Marketing Suite"
  },
  "servers": [
    {
      "url": "https://{yourinstance}.makaira.io"
    }
  ],
  "paths": {
    "/search-query-hook": {
      "post": {
        "summary": "Create a new search query hook",
        "tags": [
          "Search Query Hook"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchQueryHook"
              },
              "examples": {
                "Pre-Search": {
                  "value": {
                    "priority": 1,
                    "type": "pre-search",
                    "target": "search",
                    "url": "https://webhook.test"
                  }
                },
                "Post-Search": {
                  "value": {
                    "priority": 1,
                    "type": "post-search",
                    "target": "search",
                    "url": "https://webhook.test"
                  }
                },
                "Modify recommendation result": {
                  "value": {
                    "priority": 1,
                    "type": "modify-result",
                    "target": "recommendation",
                    "url": "https://webhook.test"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Created"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/instance"
          }
        ],
        "operationId": "post_search-query-hook"
      }
    }
  },
  "components": {
    "schemas": {
      "SearchQueryHook": {
        "type": "object",
        "properties": {
          "priority": {
            "type": "integer",
            "description": "The priority of the hook, if we have multiple hooks of a same type, the one with higher priority will be executed first"
          },
          "type": {
            "type": "string",
            "description": "The type of the webhook, it will determine when the hook is executed",
            "enum": [
              "pre-search",
              "post-search",
              "modify-result"
            ]
          },
          "target": {
            "type": "string",
            "description": "The target of the webhook, it will determine where the hook is executed",
            "enum": [
              "search",
              "recommendation"
            ]
          },
          "url": {
            "type": "string",
            "description": "The url of the webhook, where the result of search/recommendation is modified"
          }
        }
      }
    },
    "parameters": {
      "instance": {
        "in": "header",
        "name": "X-Makaira-Instance",
        "required": true,
        "description": "Makaira Instance ID",
        "schema": {
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authentication by JSON Web Token\n"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```