帮助中心

管理项目的帮助中心文章及其分类。需要项目已开启帮助中心 — 关闭时，下面所有端点都返回 404。

文章正文是 Markdown，不是 HTML。门户通过一个从不执行原始 HTML 的查看器渲染它们，因此您提交的任何 HTML 都会以纯文本形式呈现给读者。

GET/v1/articles

Parameter	Type	Description
`status`	`string`	按状态筛选：draft、published 或 archived。
`category_id`	`string`	仅此分类下的文章。
`limit`	`integer`	每页条数。默认 25，最大 100。
`offset`	`integer`	跳过的条数。默认 0。

GET/v1/articles/search

Parameter	Type	Description
`q`required	`string`	搜索词。支持引号短语、OR 和 - 排除。
`limit`	`integer`	结果条数。默认 25，最大 100。

GET/v1/articles/:id

POST/v1/articles

Parameter	Type	Description
`title`required	`string`	最多 200 个字符。
`body`	`string`	Markdown。最多 50,000 个字符。
`excerpt`	`string`	一行摘要，最多 300 个字符。省略时从正文生成。
`slug`	`string`	URL 片段，最多 80 个字符。省略时从标题生成。
`category_id`	`string`	归入的分类。

PATCH/v1/articles/:id

Parameter	Type	Description
`title`	`string`	新标题。
`body`	`string`	新的 Markdown 正文。
`excerpt`	`string`	新摘要；null 清空。
`slug`	`string`	新的 URL 片段。
`category_id`	`string`	新分类；null 表示不分类。
`status`	`string`	draft、published 或 archived。

DELETE/v1/articles/:id

文章始终以草稿创建 — 发布是单独的 PATCH，因此不会有内容意外出现在门户上。创建文章需要付费计划的写入权限，这里其他所有修改类方法同样如此。

列出文章


curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "如何重置密码？",
      "slug": "how-do-i-reset-my-password",
      "body": "打开 **设置**，然后选择 *重置密码*。",
      "excerpt": "打开设置，然后选择重置密码。",
      "status": "published",
      "category_id": "3c2b...",
      "published_at": "2026-07-01T09:12:00Z",
      "helpful_count": 12,
      "not_helpful_count": 1,
      "created_at": "2026-06-28T14:03:00Z",
      "updated_at": "2026-07-01T09:12:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_more": false }
}

不加筛选时也会返回草稿和已归档的文章，按最近编辑排序。需要客户实际能看到的内容时，请传 status=published。

搜索文章


curl "https://api.supdesk.app/v1/articles/search?q=重置密码&limit=5" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "如何重置密码？",
      "slug": "how-do-i-reset-my-password",
      "category_slug": "getting-started",
      "category_name": "入门",
      "snippet": "打开设置，然后选择重置密码。",
      "rank": 0.6079
    }
  ]
}

仅针对已发布文章的全文搜索，按相关度排序，并附带命中位置附近的纯文本片段。标题的权重高于摘要，摘要高于正文。空查询或无法解析的查询返回空列表，而不是错误。

获取单篇文章


curl "https://api.supdesk.app/v1/articles/8f7a..." \
  -H "Authorization: Bearer sd_live_..."

返回与列表中形状相同的单篇文章；若该 id 在您的项目中不存在，则返回 404。

创建文章


curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "如何重置密码？",
    "body": "打开 **设置**，然后选择 *重置密码*。",
    "category_id": "3c2b..."
  }'


{
  "data": {
    "id": "8f7a...",
    "title": "如何重置密码？",
    "slug": "how-do-i-reset-my-password",
    "body": "打开 **设置**，然后选择 *重置密码*。",
    "excerpt": "打开设置，然后选择重置密码。",
    "status": "draft",
    "category_id": "3c2b...",
    "published_at": null,
    "helpful_count": 0,
    "not_helpful_count": 0,
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:12:00Z"
  }
}

返回 201。省略 slug 时会从标题生成，若地址已被占用则加上 -2、-3… 后缀。省略 excerpt 时会从正文生成。

您的计划限制了项目可保留的文章数量 — 免费版 5 篇、专业版 50 篇、团队版无限。超出后返回 limit_reached（429）。已归档的文章不计入，所以归档一篇就能腾出一个名额。

更新文章


curl -X PATCH https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

只有您提交的字段会被写入，因此 PATCH 绝不会清空您未发送的内容。把 status 设为 published 会在首次发布时记录 published_at 并在之后保留 — 修正错别字不会让旧文章看起来像新的。设为 archived 则在不删除的前提下下线文章。

取消归档会重新检查计划额度，因此也可能返回 limit_reached。

删除文章


curl -X DELETE https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..."

永久删除文章及其读者反馈，返回 204。若想保留文章只是下线，请把状态设为 archived。

分类

GET/v1/article-categories

Parameter	Type	Description
`limit`	`integer`	每页条数。默认 25，最大 100。
`offset`	`integer`	跳过的条数。默认 0。

GET/v1/article-categories/:id

POST/v1/article-categories

Parameter	Type	Description
`name`required	`string`	最多 80 个字符。
`description`	`string`	显示在门户上，最多 300 个字符。
`sort_order`	`integer`	显示位置。默认 0。

PATCH/v1/article-categories/:id

Parameter	Type	Description
`name`	`string`	新名称。
`description`	`string`	新描述；null 清空。
`sort_order`	`integer`	新的显示位置。

DELETE/v1/article-categories/:id


curl -X POST https://api.supdesk.app/v1/article-categories \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "入门", "sort_order": 1 }'


{
  "data": {
    "id": "3c2b...",
    "name": "入门",
    "slug": "getting-started",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

分类先按 sort_order 排列，再按名称排列。短链接从名称生成，方式与文章短链接从标题生成相同。

删除分类返回 204，并不会删除其中的文章 — 它们只是变为不分类，仍可通过搜索和帮助中心首页找到。

错误

除标准错误码之外：

错误码	状态	触发条件
`not_found`	404	id 不存在 — 或该项目已关闭帮助中心。
`forbidden`	403	在没有 API 写入权限的计划上执行写操作。
`limit_reached`	429	计划的文章额度已用尽。