分页与排序

所有列表端点支持统一的分页和排序参数。

查询参数

参数	类型	默认值	范围	说明
offset	int	0	>= 0	跳过前 N 条记录
limit	int	50	1 ~ 100	返回数量上限
desc	bool	true	—	是否降序排列
order	string	created_at	created_at | updated_at	排序字段

示例

GET /api/v1/conversations?offset=0&limit=20&desc=true&order=updated_at

返回最近更新的 20 条对话。

GET /api/v1/files?offset=40&limit=20&desc=false&order=created_at

返回最早创建的文件（第 41-60 条）。

响应格式

列表端点直接返回数组：

[
  { "id": "...", "created_at": "..." },
  { "id": "...", "created_at": "..." }
]

部分端点返回包装对象（含总数）：

{
  "items": [...],
  "count": 156
}

边界行为

场景	行为
offset 超过总数	返回空数组 []
limit 超过 100	返回 422 验证错误
limit 为 0 或负数	返回 422 验证错误
order 为无效值	返回 422 验证错误

时间范围过滤

部分端点额外支持时间范围过滤：

参数	格式	说明
created_after_datetime	ISO 8601	创建时间晚于
created_before_datetime	ISO 8601	创建时间早于
updated_after_datetime	ISO 8601	更新时间晚于
updated_before_datetime	ISO 8601	更新时间早于

时间过滤与分页/排序组合使用：

GET /api/v1/transaction-logs?created_after_datetime=2026-03-01T00:00:00Z&limit=50