Sciverse API 文档v0.1
POSThttps://api.sciverse.space/agentic-search

智能搜索接口。输入自然语言问题，返回来自学术文献和可信网页的相关文本片段，并附带相关性分数。支持全文检索、向量语义搜索及两者融合。

鉴权
Bearer Token

需要 Bearer Token

必填
query

搜索关键词或自然语言问题，最长 4096 个字符。这是唯一必填项。

概述

适用场景： 当你想对学术问题进行智能检索时，发送一条自然语言查询，接口将在后台完成查询改写、多路召回和融合排序，直接返回最相关的文本片段。
标准模式stream: false

一次性返回全部结果的 JSON 对象，适合大多数场景。

流式模式stream: true

通过 SSE 协议逐步推送结果，适合实时展示进度。

身份验证

所有请求需在 HTTP Header 中携带 Bearer Token。Token 可在 API 令牌页 创建。

http
Authorization: Bearer YOUR_API_TOKEN

请求参数

请求体为 JSON 格式，Content-Type 须设置为 application/json。

参数类型必填说明
query
string必填搜索关键词或自然语言问题，最长 4096 个字符。这是唯一必填项。
source_types
array | null
默认: null
可选按来源类型过滤，不填则搜索全部来源。
webpdf
filters
object | null
默认: null
可选额外过滤条件，当前版本保留字段，传 null 即可。
request_id
string | null
默认: null
可选自定义请求追踪 ID，方便日志关联；不填时系统自动生成。

响应结构

成功时返回 HTTP 200，响应体包含 hits（搜索结果数组）、timings（各阶段耗时）和 debug（调试信息，生产环境为 null）。

hits[*] — 单条结果字段
参数类型说明
chunk_id
string文本块的唯一 ID。
doc_id
string所属文档 ID；非必返字段。
title
string文档或网页标题。
abstract
string该文本块的摘要内容。
chunk
string文本块正文。ES 召回或混合路径下常为索引中的 content；纯向量召回且未写入 ES 时可能为空。
score
number相关性分数，越高越相关。
source_type
string来源类型。
pdf_page
integer | null命中内容所在 PDF 页码（仅 PDF 来源）。
offset
integer命中文本在原文中的起始字节偏移。
page_no
integer命中文本所在页码或分片页序号。

错误码

/agentic-search 的错误响应可能有两种格式：鉴权和连接类错误为扁平结构；请求处理类错误通常为嵌套结构。错误信息字段为 code / error.code 和 message / error.message 字段。

状态码含义处理建议
400请求参数错误请求体格式或参数不符合要求，请检查 query、top_k 等字段。
401鉴权失败Bearer Token 缺失、无效，或 Token 所属用户不可用。
405方法不允许接口仅支持 POST 请求。
500请求处理失败服务处理请求时出错，请稍后重试；如持续出现，请联系支持并提供 request_id。
502服务连接失败服务暂时无法建立必要连接，请稍后重试；如持续出现，请联系支持。
503服务暂不可用服务暂时不可用，请稍后重试。