通用数据结构

本页说明跨资源复用的数据结构。各资源自己的对象结构在对应 API 子目录的“数据结构”页面中说明。

Metadata 对象

metadata 是调用方自定义的扁平字符串键值对象。

规则	说明
结构	JSON object，所有 value 都必须是 string
最大键数量	16
key 最大长度	64 个 Unicode 字符
value 最大长度	512 个 Unicode 字符
默认值	省略时为 `{}`

示例：

{
  "team": "docs",
  "project": "cloud-agents"
}

列表接口返回统一的游标分页信封。

字段	类型	说明
`data`	array	当前页的资源对象数组
`has_more`	boolean	是否还有更多数据
`first_id`	string \| null	当前页第一条记录的游标 ID；`data` 为空时为 `null`
`last_id`	string \| null	当前页最后一条记录的游标 ID；`data` 为空时为 `null`

错误响应使用以下结构：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'name' is required."
  }
}

字段	类型	说明
`type`	string	固定为 `"error"`
`error.type`	string	错误类别，如 `invalid_request_error`、`authentication_error`、`permission_error`、`not_found_error`、`conflict_error`、`api_error`
`error.message`	string	人类可读的错误信息

时间字段是 UTC 的 ISO 8601 / RFC 3339 字符串，例如 "2026-05-18T15:26:39.61669Z"。部分字段可以为 null，具体以各资源结构说明为准。

了解 Qoder Cloud Agents 的整体架构。