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

# Structured Search

`POST /api/v1/search/structured`

## 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/structured`
- Auth: OAuth 2 (password, token URL `/api/v1/auth/oauth/token`)

结构化检索：required条件做硬性SQL过滤，preferred条件做语义匹配

## Request body

- StructuredSearchRequest
  - `required` RequiredRule[], nullable
    - `field` string, required
    - `operator` string, required
    - `value` unknown, required
    - `label` string, nullable
  - `preferred` PreferredConditions
    - `semantic_query` string, nullable
    - `skills` PreferredSkill[], nullable
      - `name` string, required
      - `min_level` integer, nullable
      - `min_years` number, nullable
      - `weight` number
      - `label` string, nullable
    - `keywords` PreferredKeyword[], nullable
      - `text` string, required
      - `weight` number
      - `label` string, nullable
    - `industry_extensions` object, nullable
  - `max_results` integer
  - `scoring_required` RequiredRule[], nullable
    - `field` string, required
    - `operator` string, required
    - `value` unknown, required
    - `label` string, 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)