# POST   /v1/search

The unified search endpoint. The gateway routes the query to the best data sources based on intent, then fuses and re-ranks the results.

API key optional (anonymous traffic is rate-limited per IP and consumes the daily free quota)

#### Request parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| query | string | Yes | Search query |
| max_results | int | No | Number of results to return, e.g. 10. Defaults to 10. Range: 1–10 |
| tag | string | No | Sub-domain capability tag, a single value in the form {domain}.{sub_domain}, e.g. "code.doc" |
| zone | string | No | Region, one of cn or intl |
| language | string | No | Preferred language, e.g. zh-CN or en |
| params | object | No | Extended parameters passed through to AnyMix, e.g. {"ticker": "AAPL"} |
| format | string | No | Output format, one of json or markdown |

#### Request example

```bash
curl -X POST https://api.anysearch.com/v1/search \
  -H "Authorization: Bearer YOUR_ANYSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Go 1.26 release notes",
    "max_results": 10
  }'
```

#### Request example（parameter）

```bash
curl -X POST https://api.anysearch.com/v1/search \
  -H "Authorization: Bearer YOUR_ANYSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Go 1.26 release notes",
    "tag": "code.doc",
    "params": {"library": "golang"},
    "max_results": 10
}
```

#### Response Format

| FIELD | DESCRIPTION |
| --- | --- |
| code | Business result code. Success is 0. |
| message | Fixed to success for successful requests. |
| request_id | Server-generated UUID v4 request correlation ID. |
| data.results | Search result list. |
| data.results[].title | Result title. Always present, but may be an empty string when the source provides no title. |
| data.results[].url | Result URL. |
| data.results[].snippet | Short result summary. Omitted when unavailable. |
| data.results[].content | Cleaned result content. Omitted when unavailable. With format: "markdown", this field contains Markdown while the outer response remains JSON. |
| data.metadata.total_results | Total number of results returned for this response. |
| data.metadata.search_time_ms | Upstream search duration in milliseconds. |

#### Response Example

```json
{
  "code": 0,
  "message": "success",
  "request_id": "7d6f4e91-2a83-4c5b-9f10-6e8a3d27b541",
  "data": {
    "results": [{
      "title": "Go 1.26 Release Notes",
      "url": "https://go.dev/doc/go1.26",
      "snippet": "Introduction to the changes in Go 1.26.",
      "content": "Go 1.26 introduces changes to the language, toolchain, runtime, and libraries..."
    }],
    "metadata": {
      "total_results": 1,
      "search_time_ms": 312
    }
  }
}
```

#### Error Responses

Search and Extract use the same error envelope. The table lists only the HTTP status and its meaning; classify errors by HTTP status and retain the request ID.

| HTTP STATUS | DESCRIPTION |
| --- | --- |
| 400 | Invalid request body or fields, missing query, or an upstream client error. |
| 401 | Invalid Authorization header or API key. |
| 402 | Quota exhausted. Anonymous callers may receive generated credentials in message; see the shared 402 flow below. |
| 403 | Expired API key, disabled account, or forbidden access. |
| 415 | Content-Type is missing or is not application/json. |
| 429 | API-key, user, or anonymous-IP rate limit exceeded. |
| 502 | Search service unavailable or returned an invalid response. |

```json
{
  "code": -1,
  "message": "Query is required.",
  "request_id": "2e5a8c74-1d39-4f62-b087-9c6e3a51d428"
}
```

> Anonymous quota auto-registration (Search and Extract only): when an anonymous caller exceeds the daily free quota, the rejected request is not executed. If pre-registration has completed, the HTTP 402 response contains the generated credentials in its multi-line message. If registration is still running, retry after a short delay. After receiving all three credentials, save them securely and resubmit the original request with Authorization: Bearer <API_KEY>.

#### Anonymous quota 402 example

```json
{
  "code": -1,
  "message": "Your account and API key have been automatically generated. Use the API key below to continue.\nusername=<USERNAME>\npassword=<PASSWORD>\napi_key=<API_KEY>",
  "request_id": "5a3f8c27-1e64-4b90-a752-6d9e2f41c083"
}
```

This response may contain a password and API key. Treat the entire response as sensitive: do not write it to routine logs, analytics, traces, or support tickets. Credentials appear only when all three values are available.