跳到主要内容
Sursa Developers

快速入门

本指南带您在五分钟内从零完成一个可用的集成：创建 API 密钥并检查它，向知识库添加文档，找到这个文档，并就它提出问题。每一步都是一个 HTTP 请求。在任意示例中选择一次语言，页面上的所有示例都会随之切换。

带语言切换的示例使用本门户的 API 专用地址：在 Sursa 云中是 https://api.sursa.com，在您自己的部署中是部署的 API 专用地址。示例中出现 https://api.example.com 时，请换成您的 API 专用地址。如果不确定自己使用的是哪个地址，请参见 API 专用地址与环境。

1. 创建 API 密钥

组织管理员在 Sursa 的 Administration → API keys（管理 → API 密钥）中创建密钥。给密钥起一个能说明用途的名称（例如“CRM sync”），选择角色；如果想进一步缩小范围，再选择权限范围。密钥能做具有该角色的用户能做的事，且不超出其权限范围。完成本指南，editor 角色就足够了。

密钥只显示一次。请把它保存在系统的密钥存储中，并通过环境变量传给代码：

export SURSA_API_KEY="kb_…"

每个请求都在 Authorization 头中以 Bearer 令牌的形式传入密钥。API 密钥与权限范围介绍了角色、权限范围、过期和轮换。

2. 设置客户端

不需要任何库：API 就是普通的 HTTPS 和 JSON。本指南的示例在每种语言中使用一个小的辅助函数。复制您所用语言的版本；后续指南也使用同一个辅助函数。官方客户端库列在 SDK 下。

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. 检查密钥

GET /v1/me 描述调用方：组织、密钥、密钥的角色和权限范围，以及适用的速率限制。任何有效的密钥都可以调用它，因此它是每个集成最适合发出的第一个请求。

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

返回 401 且错误码为 auth.not_authenticated，表示没有密钥、密钥已撤销或输错；错误码 api_keys.expired 表示密钥已过期。

4. 找到合集

卡片存放在合集中。GET /v1/collections 列出密钥能看到的合集：

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

记下要使用的合集的 id 和 name。下面的示例使用名为 support 的合集 3。

5. 添加文档

PUT /v1/cards-by-external-id/{external_id} 以您自己的 ID 创建卡片；卡片已存在时则替换它。同一个请求执行两次也是安全的：第二次内容没有变化，返回 skipped，原因为 unchanged。请把记录在您系统中的 ID 用作 external_id。

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

卡片可以被搜索到时，请求才会返回：新卡片返回 201 和 "status": "ready"，被替换的卡片返回 200。HTML 和纯文本的用法相同，分别使用 "content_type": "html" 或 "text"。文件（PDF、Word、Excel 等）以 multipart/form-data 形式通过同一个接口上传；文件、文件夹、元数据和大批量文档的导入参见导入文档。

POST /v1/search 查找与查询匹配的卡片摘录，最匹配的排在前面：

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection 接受合集的名称。不传时，搜索范围是名为 default 的合集。

7. 提问

POST /v1/ask 用自然语言回答问题，并返回回答的来源。助手查找相关知识，并且只根据密钥有权读取的卡片作答。

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

没有找到相关内容时，响应仍然是 200，带有 "empty": "no_hits"，answer 中有简短说明。这种情况下向用户显示什么，由您的代码决定。

后续步骤