跳转到主要内容
POST
查询会话列表

限制说明

使用说明

  • 分页使用 p/limit(默认 20,最大 100)。调用者置顶且符合过滤条件的会话会额外插在第 1 页最前面(不占 limit),不会出现在后续页,也不计入 total。
  • scope=all 返回调用者创建的会话,以及绑定到调用者所在团队的会话。团队以实际成员关系为准,对所有角色一致;账户所有者和管理员在此看不到其他团队的会话。
  • team_ids、person_ids、entry_kinds 只会收窄可见范围。无痕会话永不列出;子智能体会话仅在 include_subagent_sessions=true 时返回。
  • creator_name、has_unread、pinned_at 按调用者计算。current_turn_* 字段与 context_window 恒为 0,且不返回 state、bound_environment、context_resolved、automation、has_open_tasks;如需这些字段请使用 POST /safari/session/get。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json

查询智能体会话列表的过滤条件。all 表示调用者自己的个人会话和可访问团队的团队会话;账户管理员不可见他人的个人会话。

app_name
enum<string>
必填

要查询其会话的智能体应用。可选值:

可用选项:
ask-ai,
support,
support-website,
support-flashcat,
ai-sre,
template-assistant,
query-assistant,
swe
p
integer
默认值:1

页码,从 1 开始。

必填范围: x >= 1
limit
integer
默认值:20

每页数量,1–100。

必填范围: 1 <= x <= 100
orderby
enum<string>

排序字段:created_at 按创建时间,updated_at 按最近更新时间;省略时默认 updated_at。

可用选项:
created_at,
updated_at
asc
boolean

为 true 时升序,false 时降序。仅在与 orderby 同时提供时生效;省略 orderby 时始终按 updated_at 降序。

include_subagent_sessions
boolean

为 true 时同时列出子智能体派发产生的子会话。默认 false(只返回顶层会话)。

keyword
string

只返回 session_name 包含该文本的会话;首尾空格会被忽略。

Maximum string length: 64
scope
enum<string>

可见范围:

  • all(默认):调用者创建的会话,加上绑定到调用者所在团队的会话
  • personal:调用者自己创建且未绑定团队(team_id = 0)的会话
  • team:绑定到调用者所在团队的会话;调用者不属于任何团队时为空
可用选项:
all,
personal,
team
team_ids
integer<int64>[]

可选的团队过滤;与 scope 取交集,且不会扩大访问范围。

person_ids
integer<int64>[]

按会话发起人过滤:只返回由这些成员发起的会话(person_id 命中其一即保留)。与 scope、team_ids 取交集,因此不会让调用方看到本来无权限的会话。

entry_kinds
enum<string>[]

仅返回由这些入口创建的会话:web(控制台)、im(IM 机器人或 IM 端 H5)、api(公开 API)、automation(自动化规则)。为空则返回所有入口。

可用选项:
web,
im,
api,
automation
status
enum<string>

归档过滤:

  • active(默认):未归档的会话
  • archived:仅已归档的会话
  • all:两者都返回
可用选项:
active,
archived,
all

响应

成功

所有 Flashduty 公开 API 共用的标准响应结构。成功时 data 为接口专属载荷且不含 error;失败时 error 存在而 data 缺失。request_id 始终存在,并会同步写入 Flashcat-Request-Id 响应头。

request_id
string
必填

本次请求的唯一 ID,与 Flashcat-Request-Id 响应头一致。反馈问题时请携带该 ID。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

error
object

响应结构中的错误 payload,仅在非 2xx 响应时出现。

data
object

一页智能体会话。