# Deepseek Web Search

> Common

Search the web by query and return a structured result list. `model` is fixed to `deepseek-tools-search` and is used only for routing
(stripped before forwarding); all other fields are forwarded to the upstream as-is.

`query` supports the following search operators. Multiple operators can be combined in one query; the syntax is passed to the search service as-is:

| Operator | Example | Description |
|---|---|---|
| `site:` | `DeepSeek site:github.com` | Restrict results to a site. For multiple sites, separate with spaces and join with `OR`, e.g. `DeepSeek site:github.com OR site:huggingface.co` |
| `-site:` | `DeepSeek -site:example.com` | Exclude a site; separate multiple sites with spaces |
| `-` | `DeepSeek -ads` | Exclude pages containing a keyword; separate multiple keywords with spaces |
| `-"..."` | `DeepSeek -"release notes"` | Exclude pages containing a phrase (may contain spaces); separate multiple phrases with spaces |
| `"..."` | `DeepSeek "exact phrase"` | Match an exact phrase; separate multiple phrases with spaces |
| `lang:` | `DeepSeek lang:zh,en` | Restrict results to languages, comma-separated |
| `after:` | `DeepSeek after:2025` or `DeepSeek after:2025-01-01` | Restrict to pages published after a date |
| `before:` | `DeepSeek before:2026` or `DeepSeek before:2026-06-01` | Restrict to pages published before a date |

## Endpoint

`POST https://api.modelverse.cn/v1/web_search`

## Request Body

## Responses

- **200** — 
- **default** — Error response (gateway-side validation/auth errors or upstream non-200, status code and body passed through as-is).
Upstream errors use the OpenAI-compatible format, and `param` is always `null`.

Common upstream errors:

| HTTP status | Description |
|---|---|
| 400 | Invalid request body, including malformed JSON or invalid field values (e.g. `count` outside 1–50, blank `query`) |
| 401 | Missing or invalid API key |
| 408 | Timed out reading the request body |
| 413 | Request body exceeds the size limit |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
| 504 | Downstream request timed out |

Retry after a delay on 408, 429 or 5xx. Do not retry other 4xx errors without changing the request.


## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "ModelVerse DeepSeek Web Search API",
    "version": "1.0.0",
    "description": "Self-contained OpenAPI 3.1 schema for the ModelVerse **DeepSeek Web Search** model, powered by DeepSeek's in-house search engine.\nUnified endpoint `POST /v1/web_search`; the `model` field in the body selects the provider\n(stripped before forwarding). All other fields are DeepSeek Search native parameters,\nforwarded and returned as-is without normalization. The response is non-streaming JSON.\nBilling: per request. A call counts as 1 only when it returns HTTP 200 with a non-empty `results`;\nfailed requests, searches with no results (empty `results`) and timeouts are not billed.\n`count` only controls the number of results and does not affect the per-request price.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "Web Search",
      "description": "DeepSeek web search."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/web_search": {
      "post": {
        "tags": [
          "Web Search"
        ],
        "operationId": "createDeepseekToolsSearch",
        "summary": "Deepseek Web Search",
        "description": "Search the web by query and return a structured result list. `model` is fixed to `deepseek-tools-search` and is used only for routing\n(stripped before forwarding); all other fields are forwarded to the upstream as-is.\n\n`query` supports the following search operators. Multiple operators can be combined in one query; the syntax is passed to the search service as-is:\n\n| Operator | Example | Description |\n|---|---|---|\n| `site:` | `DeepSeek site:github.com` | Restrict results to a site. For multiple sites, separate with spaces and join with `OR`, e.g. `DeepSeek site:github.com OR site:huggingface.co` |\n| `-site:` | `DeepSeek -site:example.com` | Exclude a site; separate multiple sites with spaces |\n| `-` | `DeepSeek -ads` | Exclude pages containing a keyword; separate multiple keywords with spaces |\n| `-\"...\"` | `DeepSeek -\"release notes\"` | Exclude pages containing a phrase (may contain spaces); separate multiple phrases with spaces |\n| `\"...\"` | `DeepSeek \"exact phrase\"` | Match an exact phrase; separate multiple phrases with spaces |\n| `lang:` | `DeepSeek lang:zh,en` | Restrict results to languages, comma-separated |\n| `after:` | `DeepSeek after:2025` or `DeepSeek after:2025-01-01` | Restrict to pages published after a date |\n| `before:` | `DeepSeek before:2026` or `DeepSeek before:2026-06-01` | Restrict to pages published before a date |\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeepseekSearchRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic search",
                  "value": {
                    "model": "deepseek-tools-search",
                    "query": "DeepSeek V4 model release",
                    "count": 5
                  }
                },
                "withContent": {
                  "summary": "Return page content with the original question",
                  "value": {
                    "model": "deepseek-tools-search",
                    "query": "Beijing weekend weather",
                    "ori_question": "Is this weekend good for an outing in Beijing?",
                    "count": 3,
                    "need_content": true
                  }
                },
                "syntax": {
                  "summary": "Combined search operators",
                  "value": {
                    "model": "deepseek-tools-search",
                    "query": "DeepSeek model site:github.com OR site:huggingface.co lang:en after:2025",
                    "count": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeepseekSearchResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful response",
                    "value": {
                      "results": [
                        {
                          "rerank_score": 2.4,
                          "title": "DeepSeek V4 model released",
                          "url": "https://example.com/deepseek-v4",
                          "snippet": "DeepSeek V4 is now available, with tool calling and long-context support.",
                          "summary": "DeepSeek has released the V4 model. The release adds improved tool calling and long-context support for agent workflows.",
                          "content": "",
                          "site_name": "Example News",
                          "site_icon": "https://example.com/favicon.ico",
                          "date": "2026-06-01T00:00:00+00:00",
                          "authority": 3
                        }
                      ]
                    }
                  },
                  "empty": {
                    "summary": "No match",
                    "value": {
                      "results": []
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response (gateway-side validation/auth errors or upstream non-200, status code and body passed through as-is).\nUpstream errors use the OpenAI-compatible format, and `param` is always `null`.\n\nCommon upstream errors:\n\n| HTTP status | Description |\n|---|---|\n| 400 | Invalid request body, including malformed JSON or invalid field values (e.g. `count` outside 1–50, blank `query`) |\n| 401 | Missing or invalid API key |\n| 408 | Timed out reading the request body |\n| 413 | Request body exceeds the size limit |\n| 429 | Rate limit exceeded |\n| 500 | Internal server error |\n| 504 | Downstream request timed out |\n\nRetry after a delay on 408, 429 or 5xx. Do not retry other 4xx errors without changing the request.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeepseekErrorResponse"
                },
                "examples": {
                  "invalidCount": {
                    "summary": "count out of range",
                    "value": {
                      "error": {
                        "message": "'count' must be between 1 and 50",
                        "type": "invalid_request_error",
                        "param": null,
                        "code": "invalid_request_error"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Platform-issued API key, passed via `Authorization: Bearer <API Key>`."
      }
    },
    "schemas": {
      "DeepseekSearchRequest": {
        "type": "object",
        "additionalProperties": true,
        "description": "Unknown fields in the request body are ignored by the upstream.",
        "required": [
          "model",
          "query"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "deepseek-tools-search",
            "description": "Routing identifier, fixed to `deepseek-tools-search`; stripped before forwarding."
          },
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Search query, 1–128 Unicode characters, not all whitespace. Supports operators such as `site:`, `-site:` and quotes."
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10,
            "description": "Number of results, 1–50. Defaults to 10."
          },
          "ori_question": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "description": "The user's original question that triggered the search, 1–128 characters. Helps the engine understand search intent; `null` is treated as not provided."
          },
          "localization": {
            "type": "string",
            "default": "",
            "description": "IP address used to prioritize localized results. Defaults to an empty string. Forwarded as-is; the gateway does not fill in the client's real IP."
          },
          "need_content": {
            "type": "boolean",
            "default": false,
            "description": "Whether to return page content in `content`. Defaults to `false`; when `false`, `content` is always an empty string."
          }
        }
      },
      "DeepseekSearchResponse": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "description": "Search results; an empty array when nothing matches.",
            "items": {
              "$ref": "#/components/schemas/DeepseekSearchResult"
            }
          }
        }
      },
      "DeepseekSearchResult": {
        "type": "object",
        "required": [
          "rerank_score",
          "title",
          "url",
          "snippet",
          "summary",
          "content",
          "site_name",
          "site_icon",
          "date",
          "authority"
        ],
        "properties": {
          "rerank_score": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 3,
            "description": "Ranking score from 0 to 3, combining relevance, authority and freshness. A score of 1.5 or higher indicates a high-quality result."
          },
          "title": {
            "type": "string",
            "description": "Result title."
          },
          "url": {
            "type": "string",
            "description": "Result URL."
          },
          "snippet": {
            "type": "string",
            "description": "Short query-relevant summary, typically 100–200 characters, suited for UI display."
          },
          "summary": {
            "type": "string",
            "description": "Long query-relevant summary, typically 600–800 characters, suited for model consumption."
          },
          "content": {
            "type": "string",
            "description": "Page content. Empty string when `need_content` is `false` or content is unavailable."
          },
          "site_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Site name; `null` when unavailable."
          },
          "site_icon": {
            "type": [
              "string",
              "null"
            ],
            "description": "Site icon URL; `null` when unavailable."
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Publish time in UTC RFC 3339 format; `null` when unknown.",
            "examples": [
              "2026-06-01T00:00:00+00:00"
            ]
          },
          "authority": {
            "type": "integer",
            "minimum": -1,
            "maximum": 4,
            "description": "Page authority from 0 to 4 (`-1` means unknown); 3 or higher indicates a highly authoritative result."
          }
        }
      },
      "DeepseekErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/DeepseekError"
          }
        }
      },
      "DeepseekError": {
        "type": "object",
        "required": [
          "message",
          "type",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always `null` in upstream errors."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code.",
            "examples": [
              "invalid_request_error"
            ]
          }
        }
      }
    }
  }
}
```