文档搜索 API

Docs Search API 通过语义搜索为你提供以编程方式访问文档内容的能力。一个端点（POST /_api/search）接收自然语言查询，并返回文档中最相关的段落，按相关性排序。

使用场景

快速开始

curl -X POST https://your-project.jamdesk.app/_api/search \
  -H "Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I set up a custom domain?", "limit": 5, "language": "en"}'

{
  "query": "How do I set up a custom domain?",
  "language": "en",
  "results": [
    {
      "title": "Custom Domains",
      "section": "Step 4: Deploy",
      "slug": "deploy/custom-domains",
      "content": "To add a custom domain, go to Project Settings and enter your domain. You'll need to add a CNAME record pointing to your Jamdesk subdomain.",
      "url": "https://your-project.jamdesk.app/deploy/custom-domains",
      "score": 0.94
    }
  ],
  "total": 1,
  "durationMs": 85
}

身份验证

所有请求都必须在 Authorization 标头中包含 Bearer 令牌。

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

生成 API 密钥

密钥管理

撤销密钥

要撤销密钥，请前往 Project Settings → API Keys，按名称找到该密钥，然后点击 Revoke。撤销的密钥会立即停止工作。生成新密钥以替换它。

速率限制

请求会按 API 密钥进行速率限制。

超过限制时，API 会返回 429 Too Many Requests，并在标头中返回 Retry-After: 60，在请求正文中返回 {"error": "Rate limit exceeded"}。

查询限制

每个请求都接受一个 limit 参数，用于控制返回的结果数量。最大值为 20，默认值为 5，最小值为 1。不支持分页；所有匹配结果都会在单个响应中返回。如果需要更多上下文，请尝试使用更具体的查询，而不是提高 limit。

没有匹配结果的查询会返回 HTTP 200，并带有空的结果数组：

{"query": "quantum entanglement", "results": [], "total": 0, "durationMs": 48}

按语言筛选

如果文档站点支持多种语言，API 会将每个请求的结果筛选为单一语言。在请求正文中使用 BCP-47 代码传递 language（例如 en、es、fr、pt-BR、zh-Hans）。

curl -X POST https://your-project.jamdesk.app/_api/search \
  -H "Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a" \
  -H "Content-Type: application/json" \
  -d '{"query": "¿Cómo configuro un dominio personalizado?", "language": "es"}'

错误处理

所有错误响应都包含机器可读的 error 字段，你可以在程序中据此进行分支处理。

CORS

所有端点都已启用 CORS。基于浏览器的客户端（单页应用、浏览器扩展、静态站点）无需后端代理即可直接调用 /_api/search。允许所有来源。

SDK

目前没有官方的编程语言 SDK。请通过 fetch、requests、curl 或任意 HTTP 客户端直接使用 REST API。下面的 Postman 集合提供了可直接派生的示例。

版本控制

API 当前版本为 v1.0.0。破坏性变更（字段重命名、移除端点、更改身份验证）将在 Jamdesk 博客中公布，并在移除前至少 90 天通过 X-Deprecation 响应标头发布弃用通知。

OpenAPI 规范

完整的 OpenAPI 3.1 规范以 YAML 格式提供。将其导入代码生成工具、API 客户端或契约测试流水线。

Postman 集合

我们发布了一个官方 Postman 工作区，其中包含完整的 OpenAPI 规范和可直接派生的集合，让你无需编写代码即可在 Postman UI 中测试请求。

后续步骤