diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7f402f1..6d30de7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,17 @@
 # Changelog
 
-## 1.8.0
+## 1.8.1
+
+### Added
+
+- **POST support on `/api/search`** — the search endpoint now accepts both GET and POST requests, enabling compatibility with clients that send search queries via POST
+- **Compatibility query parameters** on `/api/search`:
+  - `pageNumber` — alias for `page` (takes precedence when both are provided)
+  - `numResults` — requested result count hint (accepted and ignored; backend controls pagination)
+  - `format` — response format hint (e.g. `json`)
+  - `imageProxy` — client image-proxy preference flag (informational)
+  - `safesearch` — safe search level (`0` off, `1` moderate, `2` strict; accepted for compatibility)
+
 
 ### Added
 
diff --git a/FEATURES.md b/FEATURES.md
index bafe984..f3ae609 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -21,6 +21,8 @@
 ## REST API
 
 - Full REST API for search, autocomplete, and engine management
+- `/api/search` accepts both **GET and POST** requests with query string parameters
+- Compatibility parameters on `/api/search`: `pageNumber` (alias for `page`), `numResults`, `format`, `imageProxy`, `safesearch`
 - OpenAPI specification with interactive docs via [Swagger UI](https://swagger.io/tools/swagger-ui/) (`/docs`) and [Redoc](https://github.com/Redocly/redoc) (`/redoc`)
 
 ## Engine Management
@@ -80,6 +82,8 @@
 ## REST API
 
 - Full REST API for search, autocomplete, and engine management
+- `/api/search` accepts both **GET and POST** requests with query string parameters
+- Compatibility parameters on `/api/search`: `pageNumber` (alias for `page`), `numResults`, `format`, `imageProxy`, `safesearch`
 - Every result includes `result_id`, `rank`, `engine`, and `timestamp` for agent integration
 - `has_next` and `total_results` fields for cursor-aware pagination
 - Standardized error schema (`code`/`message`/`details`/`retry_hint`) on all error responses
diff --git a/README.md b/README.md
index 2b15a98..3640a28 100644
--- a/README.md
+++ b/README.md
@@ -78,15 +78,31 @@ The `/app/data` volume stores the SQLite database (engine settings, excluded dom
 
 ## API Endpoints
 
-| Method | Path                        | Description                 |
-| ------ | --------------------------- | --------------------------- |
-| GET    | `/api/search?q=&category=`  | Search web or images        |
-| GET    | `/api/autocomplete?q=`      | Autocomplete suggestions    |
-| GET    | `/api/engines`              | List all search engines     |
-| PUT    | `/api/engines/{name}`       | Enable/disable an engine    |
-| GET    | `/api/settings`             | Get app settings (cache TTL)|
-| PUT    | `/api/settings`             | Update settings             |
-| DELETE | `/api/cache`                | Flush search cache          |
+| Method     | Path                        | Description                 |
+| ---------- | --------------------------- | --------------------------- |
+| GET, POST  | `/api/search`               | Search web or images        |
+| GET        | `/api/autocomplete?q=`      | Autocomplete suggestions    |
+| GET        | `/api/engines`              | List all search engines     |
+| PUT        | `/api/engines/{name}`       | Enable/disable an engine    |
+| GET        | `/api/settings`             | Get app settings (cache TTL)|
+| PUT        | `/api/settings`             | Update settings             |
+| DELETE     | `/api/cache`                | Flush search cache          |
+
+### Search endpoint parameters
+
+| Parameter    | Default  | Description                                          |
+| ------------ | -------- | ---------------------------------------------------- |
+| `q`          | required | Search query string                                  |
+| `category`   | `web`    | `web` or `images`                                    |
+| `page`       | `1`      | Page number (1–50)                                   |
+| `pageNumber` | —        | Alias for `page` (takes precedence when provided)    |
+| `numResults` | —        | Requested result count hint (informational)          |
+| `format`     | —        | Response format hint (e.g. `json`)                   |
+| `imageProxy` | —        | Client image-proxy preference flag (informational)   |
+| `safesearch` | —        | Safe search level: `0` off, `1` moderate, `2` strict |
+| `engines`    | —        | Comma-separated engine names to restrict (e.g. `google,bing`) |
+| `image_size` | —        | `large`, `medium`, or `small` (images only)          |
+| `sort`       | `default`| `default`, `date_asc`, or `date_desc`                |
 
 ## Features
 
diff --git a/agents.md b/agents.md
index 994023c..b96ecb2 100644
--- a/agents.md
+++ b/agents.md
@@ -106,11 +106,27 @@ docker build -t hey-search . && docker run -p 8000:8000 hey-search
 
 ## API Endpoints
 
-| Method | Path                       | Description              |
-| ------ | -------------------------- | ------------------------ |
-| GET    | `/api/search`              | Metasearch (web/images)  |
-| GET    | `/api/autocomplete`        | Search suggestions       |
-| GET    | `/api/engines`             | List engines             |
-| PUT    | `/api/engines/{name}`      | Toggle engine on/off     |
-| GET    | `/docs`                    | Swagger UI               |
-| GET    | `/redoc`                   | Redoc API docs           |
+| Method    | Path                       | Description              |
+| --------- | -------------------------- | ------------------------ |
+| GET, POST | `/api/search`              | Metasearch (web/images)  |
+| GET       | `/api/autocomplete`        | Search suggestions       |
+| GET       | `/api/engines`             | List engines             |
+| PUT       | `/api/engines/{name}`      | Toggle engine on/off     |
+| GET       | `/docs`                    | Swagger UI               |
+| GET       | `/redoc`                   | Redoc API docs           |
+
+#### `/api/search` query parameters
+
+| Parameter    | Default  | Description                                                    |
+| ------------ | -------- | -------------------------------------------------------------- |
+| `q`          | required | Search query string                                            |
+| `category`   | `web`    | `web` or `images`                                             |
+| `page`       | `1`      | Page number (1–50)                                             |
+| `pageNumber` | —        | Alias for `page` (takes precedence when provided)              |
+| `numResults` | —        | Requested result count hint (informational)                    |
+| `format`     | —        | Response format hint (e.g. `json`)                             |
+| `imageProxy` | —        | Client image-proxy preference flag (informational)             |
+| `safesearch` | —        | Safe search level: `0` off, `1` moderate, `2` strict           |
+| `engines`    | —        | Comma-separated engine names (e.g. `google,bing`)              |
+| `image_size` | —        | `large`, `medium`, or `small` (images only)                    |
+| `sort`       | `default`| `default`, `date_asc`, or `date_desc`                          |