Docs 搜索 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 密钥进行速率限制。

在需要登录的站点上，使用同一密钥发出的 MCP、.md 和 llms.txt 请求共享单独的限制，即每分钟 120 次请求。它们不计入 Search API 的限制，Search 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 每次请求只按一种语言过滤结果。在请求体中传入 language，使用 BCP-47 代码（例如 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 界面中测试请求。

后续步骤