---
title: "Natural Search"
method: POST
path: "/api/v1/search"
tags: ["检索"]
---

# Natural Search

`POST /api/v1/search`

## Request

- Base URL: `https://api.hipowork.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.hipowork.com/api/v1/search`
- Auth: OAuth 2 (password, token URL `/api/v1/auth/oauth/token`)

自然语言检索：通过本地关键词解析查询，再做结构化检索（不调用 LLM）。

Agent 场景建议直接使用 /search/structured 或 /agent/match-candidates。

## Request body

- SearchRequest
  - `query` string, required
  - `max_results` integer
  - `min_match_score` number, nullable

## Response `200`

Successful Response

- SearchResponse
  - `query_id` string, required
  - `query_summary` string, required
  - `total_hard_filtered` integer, required
  - `results` CandidateSearchResult[], required
    - `rank` integer, required
    - `final_score` number, required
    - `score_breakdown` object, nullable
    - `match_reasons` string[], nullable
    - `candidate` object, nullable
  - `ai_summary` string, nullable
  - `degraded` boolean, nullable
  - `degraded_reason` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/hipowork/apis/hipo-work-ai-recruitment-platform.md) · [All operations](https://skmtc.dev/hipowork/apis/hipo-work-ai-recruitment-platform/llms.txt) · [OpenAPI document](https://skmtc.dev/hipowork/apis/hipo-work-ai-recruitment-platform/revisions/de21a6c57062?raw)