根据锚点获取对话
基于 prevId、nextId 或 initialId 游标锚点按时间正序加载会话消息记录,自动补齐对话轮次边界并返回前后翻页游标。
端点概览
- HTTP 方法:
POST - 请求路径:
/api/core/chat/record/getRecords_v2 - 所属模块:对话 / 对话管理
- 鉴权方式:
Authorization: Bearer <apiKey>—支持 应用 API Key(无需appId)与 个人密钥(需传appId);另支持authProxy团队成员代理与outLinkAuthData外链分享(详见 API 入门:完成首次请求) - 在线调试:在云服务 Scalar 调试台打开(自部署实例请将域名替换为
<instance>/apidoc/systemopenapi#tag/%E5%AF%B9%E8%AF%9D%E7%AE%A1%E7%90%86/POST/core/chat/record/getRecords_v2)
接口说明与注意事项
默认读取最新消息,按时间正序返回。prevId、nextId、initialId 三选一,也可均不传;角色由方向确定,prevId 定位 Human,nextId 和 initialId 定位 AI。将 prevCursor/nextCursor 直接传入 prevId/nextId;无对应方向的下一页时为 null。为补齐轮次边界,返回条数可能略超 pageSize。支持多种鉴权模式。
请求参数
Request Body 请求体(application/json)
各分支公共字段
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
chatId | string | 否 | - | 会话 ID。最大长度:1024 |
loadCustomFeedbacks | boolean | 否 | - | 是否加载自定义反馈 |
type | string (enum) | 否 | - | 获取类型,影响数据过滤规则。可选值:normal , outLink , home |
includeDeleted | boolean | 否 | - | 是否包含已删除的记录 |
互斥参数分支(anyOf 选填其一)
- 应用会话
通过 appId 定位会话。接口同时支持 API Key 和登录态时,Authorization 优先于 token/Cookie。
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
appId | string | 是 | - | 应用 ID,使用接口允许的请求头凭证鉴权。正则:^[0-9a-fA-F]{24}$ |
sourceType | string (enum) | 否 | - | appId 对应的会话资源类型。缺省为 App 会话;辅助生成会话传对应 sourceType。可选值:app , chatAgentHelper , workflowBuilder |
默认身份: 不传 customUid 和 authProxy,沿用凭证对应的团队成员身份。适用于直接以当前鉴权成员调用应用。
自定义使用者: 通过 customUid 对接自己平台的使用者,不改变鉴权成员及权限。发起对话时作为使用者和工作流 userId;管理对话时按该值限制使用者范围。
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
customUid | string | 是 | - | 仅普通应用的 API Key 调用支持。精确匹配对话的外部使用者 ID(outLinkUid),不匹配 tmbId;省略时保留原访问范围,传入时限制读取、修改及删除。最长 1024 字符,不接受空字符串或 null,不改变鉴权成员。最小长度:1;最大长度:1024 |
代理团队成员: 通过 authProxy 代表同团队成员执行,解析出有效 tmbId 后按该成员权限校验。仅开启代理权限的个人密钥可用,与 customUid 互斥。
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
authProxy | object | 是 | - | API Key 代理调用身份。仅开启 authProxy 的个人密钥可用;按团队成员 ID 或用户名指定,二者同时传入时优先使用 tmbId,解析时过滤 username;tmbId 无效时不回退到用户名 |
authProxy.tmbId | string | 是 | - | 分支:按团队成员 ID。API Key 代理调用的团队成员 ID,优先于 username。正则:^[0-9a-fA-F]{24}$ |
authProxy.username | string | 是 | - | 分支:按用户名。API Key 代理调用的团队成员用户名。最小长度:1;最大长度:128 |
- Skill 调试会话
通过 skillId 定位调试会话,优先于 appId 并忽略其 sourceType,使用接口允许的请求头凭证鉴权。
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
skillId | string | 是 | - | Skill Edit 调试 ID,使用接口允许的请求头凭证鉴权。正则:^[0-9a-fA-F]{24}$ |
- 外链会话
通过 outLinkAuthData 解析真实应用,优先于 skillId 和 appId 并忽略其 sourceType。外链身份优先于请求头身份;token/Cookie 可以同时传入,受保护外链仍会校验登录态。外链校验失败时不会回退到普通资源鉴权。
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
outLinkAuthData | object | 是 | - | 外链鉴权数据,包含 shareId/outLinkUid。优先于 skillId 和 appId,忽略低优先级字段;允许同时携带 token/Cookie,受保护外链仍需校验登录态。 |
outLinkAuthData.shareId | string | 是 | - | 分享链接 ID。最小长度:1 |
outLinkAuthData.outLinkUid | string | 是 | - | 外链用户 ID。最小长度:1 |
- 应用 API Key(无需 appId)
Authorization 使用绑定应用的 APP API Key 时无需传 appId 或 sourceType,服务端从 Key 绑定取得应用,sourceType 固定为 app。个人密钥和登录态不能使用此省略方式;显式传入 appId 时仍以 Key 绑定为准。
默认身份: 不传 customUid 和 authProxy,沿用凭证对应的团队成员身份。适用于直接以当前鉴权成员调用应用。
自定义使用者: 通过 customUid 对接自己平台的使用者,不改变鉴权成员及权限。发起对话时作为使用者和工作流 userId;管理对话时按该值限制使用者范围。
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
customUid | string | 是 | - | 仅普通应用的 API Key 调用支持。精确匹配对话的外部使用者 ID(outLinkUid),不匹配 tmbId;省略时保留原访问范围,传入时限制读取、修改及删除。最长 1024 字符,不接受空字符串或 null,不改变鉴权成员。最小长度:1;最大长度:1024 |
各分支公共字段
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
anchor | object | array | string | number | boolean | null | 否 | - | 当前锚点(如 chunkIndex) |
互斥参数分支(anyOf 选填其一)
- 向前翻页
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
prevId | string | 是 | - | 向前翻页的游标 ID |
pageSize | integer | 否 | 20 | 互斥参数组:分页参数。每页参考消息条数,默认 20,最多 500;为补齐轮次边界,实际返回条数可能略超。最大值:500 |
- 向后翻页
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
nextId | string | 是 | - | 向后翻页的游标 ID |
pageSize | integer | 否 | 20 | 互斥参数组:分页参数。每页参考消息条数,默认 20,最多 500;为补齐轮次边界,实际返回条数可能略超。最大值:500 |
- 定位记录
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
initialId | string | 是 | - | 初始定位数据 ID |
pageSize | integer | 否 | 20 | 互斥参数组:分页参数。每页参考消息条数,默认 20,最多 500;为补齐轮次边界,实际返回条数可能略超。最大值:500 |
- 默认页
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
pageSize | integer | 否 | 20 | 互斥参数组:分页参数。每页参考消息条数,默认 20,最多 500;为补齐轮次边界,实际返回条数可能略超。最大值:500 |
请求示例
调用前请将 YOUR_API_KEY 与示例 ID 替换为真实值;私有化部署实例请将基础域名替换为 <instance>/api。
cURL 请求示例
curl --fail-with-body -X POST "https://cloud.fastgpt.cn/api/core/chat/record/getRecords_v2" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data-raw '{
"appId": "68ad85a7463006c963799a05",
"prevId": "68ad85a7463006c963799a04"
}'最小合法 JSON 请求体示例
{
"appId": "68ad85a7463006c963799a05",
"prevId": "68ad85a7463006c963799a04"
}响应结构与示例
除兼容 OpenAI 协议的对话补全或二进制下载接口外,成功响应统一包裹在 { "code": 200, "statusText": "", "message": "", "data": ... } 标准结构中;下方 200 字段表对应 data 载荷结构(若契约未声明具体载荷结构,请以上方状态描述及实际响应为准)。
HTTP 200
成功返回对话
Content-Type : application/json
| 字段 | 类型 | 必填 | 默认值 | 约束与说明 |
|---|---|---|---|---|
hasMorePrev | boolean | 是 | - | 是否还有更多前置数据 |
hasMoreNext | boolean | 是 | - | 是否还有更多后置数据 |
list | object[] | 是 | - | 聊天记录列表,业务标识使用 dataId |
total | integer | 是 | - | 最小值:-9007199254740991;最大值:9007199254740991 |
prevCursor | string | null | 是 | - | 向前翻页的 dataId,直接传入 prevId,服务端以 Human 定位轮次起点;无前页或当前列表为空时为 null |
nextCursor | string | null | 是 | - | 向后翻页的 dataId,直接传入 nextId,服务端以 AI 定位轮次终点;无后页或当前列表为空时为 null |
多态字段明细:list
- 变体 1 (
obj="Human"):obj,value,hideInUI,useAgentSandbox,totalQuoteList,toolCiteLinks,errorText,llmModuleAccount - 变体 2 (
obj="System"):obj,value,useAgentSandbox,totalQuoteList,toolCiteLinks,errorText,llmModuleAccount,historyPreviewLength - 变体 3 (
obj="AI"):obj,value,memories,userGoodFeedback,userBadFeedback,customFeedbacks,adminFeedback,isFeedbackRead
文件更新时间