searchpipe-tech Search API

openapi: 3.2.0
info:
  title: SearchPipe Search API
  version: 0.2.0
tags:
- name: Search
paths:
  /search:
    post:
      summary: Search
      description: '搜索 → 抓取 → 重排 → (可选摘要) → 输出审核 → 返回。


        依赖链：鉴权 → 输入审核 → 限流 → 扣费 → 搜索 → 输出审核/AI标识。

        admin/owner 豁免限流与扣费。搜索失败退款（幂等）。'
      operationId: search_search_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Search
  /v1/search:
    post:
      summary: Search
      description: '搜索 → 抓取 → 重排 → (可选摘要) → 输出审核 → 返回。


        依赖链：鉴权 → 输入审核 → 限流 → 扣费 → 搜索 → 输出审核/AI标识。

        admin/owner 豁免限流与扣费。搜索失败退款（幂等）。'
      operationId: search_v1_search_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Search
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SearchResponse:
      properties:
        query:
          type: string
          title: Query
        answer:
          anyOf:
          - type: string
          - type: 'null'
          title: Answer
          description: LLM-generated answer (optional)
        results:
          items:
            $ref: '#/components/schemas/SearchResult'
          type: array
          title: Results
        ai_generated:
          type: boolean
          title: Ai Generated
          description: Whether the response contains LLM-generated content
          default: false
        images:
          anyOf:
          - items:
              $ref: '#/components/schemas/ImageResult'
            type: array
          - type: 'null'
          title: Images
          description: Image results (present when the request set include_images=true)
        answer_audit:
          anyOf:
          - $ref: '#/components/schemas/AnswerAudit'
          - type: 'null'
          description: Per-statement audit of the AI answer (advanced depth only)
        output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Output
          description: Structured JSON object conforming to output_schema (output_type='structured' only; null when conversion failed)
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: Unique request identifier, also returned as the X-Request-Id response header
        response_time:
          anyOf:
          - type: number
          - type: 'null'
          title: Response Time
          description: Server processing time for this request, in seconds
        usage:
          anyOf:
          - $ref: '#/components/schemas/UsageInfo'
          - type: 'null'
          description: Billing and cache info for this request
        warnings:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Warnings
          description: 'Parameter-level issues: a requested feature did not take effect (safe to show the developer; do not feed to the model)'
        notices:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Notices
          description: How this response was produced (safe to show to the model)
      type: object
      required:
      - query
      - results
      title: SearchResponse
    StatementAudit:
      properties:
        text:
          type: string
          title: Text
          description: Answer statement (citation markers stripped)
        verdict:
          type: string
          title: Verdict
          description: supported/partial/unsupported/inconclusive (judged) or uncited (no [n] marker, not judged)
        confidence:
          type: number
          title: Confidence
          description: Judge confidence 0-1 (0 for uncited)
          default: 0.0
        citations:
          items:
            $ref: '#/components/schemas/StatementCitation'
          type: array
          title: Citations
      type: object
      required:
      - text
      - verdict
      title: StatementAudit
      description: 单条陈述的审计结果（E 方向 tier-2，四标签契约与 /verify 同名同义）。
    ImageResult:
      properties:
        url:
          type: string
          title: Url
          description: Image URL
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Short caption/context from the source page, when available
      type: object
      required:
      - url
      title: ImageResult
      description: 图片检索结果（P1 控制面 T1）：include_images=true 时随响应返回。
    UsageInfo:
      properties:
        credits_charged:
          type: number
          title: Credits Charged
          description: Credits billed for this request. Cache hits are charged; 0 when exempt or refunded.
          default: 0.0
        cached:
          type: boolean
          title: Cached
          description: True when the response was served from the result cache
          default: false
      type: object
      title: UsageInfo
      description: 本次请求的计费与缓存信息（P0 响应信封，history/20261020-api-v1-endpoints.md）。
    ResultEvidence:
      properties:
        quote:
          type: string
          title: Quote
          description: Verbatim supporting sentence from the page
        span_start:
          type: integer
          title: Span Start
          description: Quote start offset (into raw_content, or content when snippet-fallback)
        span_end:
          type: integer
          title: Span End
          description: Quote end offset (exclusive)
        source_tier:
          type: string
          title: Source Tier
          description: 'Source authority tier: official/press/academic/preprint/community/unknown'
          default: unknown
        fetch_status:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fetch Status
          description: HTTP status of the page fetch (None = not fetched/timeout)
        redirected:
          type: boolean
          title: Redirected
          description: Whether the fetch followed redirects
          default: false
        final_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Final Url
          description: Final URL after redirects
        fetched_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Fetched At
          description: Fetch completion time, ISO-8601 UTC
      type: object
      required:
      - quote
      - span_start
      - span_end
      title: ResultEvidence
      description: 'tier-1 证据级结果（E 方向 E-1）：每条 result 自带的逐字证据。


        quote/span 来自 locator.best_supporting_span（query 当 claim，对抓取正文

        确定性选句，span 为 raw_content 中的字符偏移）；抓取失败退回 content

        snippet 兜底（此时 span 相对 content 字段，0 起算）。纯本地计算，零出站。'
    SearchResult:
      properties:
        url:
          type: string
          title: Url
        title:
          type: string
          title: Title
        content:
          type: string
          title: Content
          description: Content snippet
          default: ''
        score:
          type: number
          title: Score
          description: 'Relevance score: 0-1 from the LLM reranker on basic/advanced; raw, unnormalized upstream engine score on fast depth (0 when the source provides none; not comparable across engines)'
          default: 0.0
        raw_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Raw Content
          description: Full page content (optional)
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Stable result identifier (first 16 hex chars of the SHA-256 of the URL)
        evidence:
          anyOf:
          - $ref: '#/components/schemas/ResultEvidence'
          - type: 'null'
          description: 'Verbatim evidence: supporting quote, span, source tier, fetch metadata'
        published_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Published Date
          description: Publish date when the source provides one (ISO 8601 string), else null
      type: object
      required:
      - url
      - title
      title: SearchResult
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    StatementCitation:
      properties:
        url:
          type: string
          title: Url
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        quote:
          anyOf:
          - type: string
          - type: 'null'
          title: Quote
          description: Supporting span quoted from the cited page (None = no page text)
        span_start:
          anyOf:
          - type: integer
          - type: 'null'
          title: Span Start
        span_end:
          anyOf:
          - type: integer
          - type: 'null'
          title: Span End
      type: object
      required:
      - url
      title: StatementCitation
      description: 陈述级引用：该陈述所引结果及其支撑 span（E 方向 tier-2）。
    AnswerAudit:
      properties:
        score:
          type: number
          title: Score
          description: Fraction of judged statements that are supported, 0-1
        uncited_count:
          type: integer
          title: Uncited Count
          description: Statements without any [n] citation marker
        statements:
          items:
            $ref: '#/components/schemas/StatementAudit'
          type: array
          title: Statements
        prompt_version:
          type: string
          title: Prompt Version
          description: Audit judge prompt version
      type: object
      required:
      - score
      - uncited_count
      - statements
      - prompt_version
      title: AnswerAudit
      description: 'tier-2 已审计答案：answer 逐陈述审计报告（E 方向 E-2，2026-10-15）。


        additive 契约：仅 search_depth="advanced" 且 include_answer=true 且

        answer_audit_enabled 开时产出。score = 系统判 supported 的陈述占比

        （分母=有引文被判定的陈述数；全部 uncited 时为 0.0）。'
    SearchRequest:
      properties:
        query:
          type: string
          maxLength: 2000
          title: Query
          description: The search query
        max_results:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Max Results
          description: Maximum number of results to return
          default: 5
        search_depth:
          type: string
          maxLength: 16
          title: Search Depth
          description: 'Search depth: basic (1 credit) / advanced (2 credits) / fast (0.5 credit; skips all LLM steps — retrieval + rule fusion + fetching only, results keep engine order with engine-provided relevance scores, no answer)'
          default: basic
        include_answer:
          type: boolean
          title: Include Answer
          description: Deprecated alias for output_type='answer'; kept for backward compatibility. Prefer output_type. Ignored when output_type is explicitly set.
          default: false
        include_raw_content:
          type: boolean
          title: Include Raw Content
          description: Whether to return full fetched page content
          default: false
        stream:
          type: boolean
          title: Stream
          description: Stream the response over Server-Sent Events (requires output_type='answer'/'structured' or include_answer=true).
          default: false
        include_domains:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 300
          - type: 'null'
          title: Include Domains
          description: Restrict results to these domains. 'example.com' matches the domain and any subdomain; '*.example.com' matches subdomains only; 'example.com/docs' also requires the URL path to start with /docs.
        exclude_domains:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 150
          - type: 'null'
          title: Exclude Domains
          description: Exclude results from these domains (same matching rules as include_domains; wins over include_domains).
        time_range:
          anyOf:
          - type: string
            enum:
            - day
            - week
            - month
            - year
          - type: 'null'
          title: Time Range
          description: Limit results to a recency window, passed to upstream engines where supported.
        start_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Start Date
          description: Only keep results published on/after this date (ISO 8601). Results without a known publish date are not filtered.
        end_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: End Date
          description: Only keep results published on/before this date (ISO 8601). Results without a known publish date are not filtered.
        topic:
          type: string
          enum:
          - general
          - news
          title: Topic
          description: 'Content topic: general (default) or news. topic=''news'' always adds a dedicated news channel to retrieval.'
          default: general
        country:
          anyOf:
          - type: string
            maxLength: 2
          - type: 'null'
          title: Country
          description: ISO 3166-1 alpha-2 region bias (e.g. 'US'); combined with language into the upstream market locale (language='en' + country='de' becomes 'en-DE').
        language:
          anyOf:
          - type: string
            maxLength: 5
          - type: 'null'
          title: Language
          description: Upstream market language, e.g. 'en' or 'zh-CN'; overrides automatic query-language detection.
        safe_search:
          type: integer
          maximum: 2.0
          minimum: 0.0
          title: Safe Search
          description: 'Safe-search level passed upstream: 0 off (default) / 1 moderate / 2 strict.'
          default: 0
        include_images:
          type: boolean
          title: Include Images
          description: Also run an image search and return an images array alongside results.
          default: false
        output_type:
          anyOf:
          - type: string
            enum:
            - search_results
            - answer
            - structured
          - type: 'null'
          title: Output Type
          description: 'Response shape: search_results (default) / answer (LLM answer with citations, same as include_answer=true) / structured (JSON object per output_schema).'
        output_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Output Schema
          description: Flat JSON Schema (object whose properties are string/number/integer/boolean; at most 20 properties, 4000 chars). Required when output_type='structured'.
        objective:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Objective
          description: Optional one-line search intent from the calling agent; used to improve reranking. Does not change what the answer covers.
      type: object
      required:
      - query
      title: SearchRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer