约定与规范

Teams OpenAPI：接入点、命名、时间、分页、错误与认证约定。

本节为所有 Teams OpenAPI 的通用约定。各接口的特殊规则以对应章节为准。

​

服务接入点

生产环境 Base URL：

https://api.qoder.com

完整请求地址示例：

https://api.qoder.com/v1/organizations/{organization_id}/members

​

字段命名

JSON 请求与响应字段统一使用 lowerCamelCase（小驼峰），例如：

organizationId、repositoryUrl、createdAt、maxResults、nextToken

​

时间格式

时间戳采用 ISO 8601（RFC 3339），示例：

2025-01-01T00:00:00Z

部分接口同时支持 Unix 毫秒时间戳，以该接口参数说明为准。

​

分页（游标）

列表类接口通常使用 游标分页，通过查询参数控制：

​

请求查询参数

参数	类型	必填	默认值	说明
maxResults	integer	否	20	每页最大条数，上限 100
nextToken	string	否	—	上一页响应中的下一页游标；首屏不传

用量类接口使用 nextToken 进行游标分页，接口另有说明时除外。

​

响应字段

字段	类型	说明
maxResults	integer	本页请求的每页条数
nextToken	string	下一页游标；省略或为空表示无更多数据

列表响应不保证返回总条数（totalCount）；需翻页直至游标为空。

​

错误响应

错误时 HTTP 状态码为非 2xx，响应体为 JSON，不包含名为 status 的顶层字段。结构如下：

{
  "requestId": "req_abc123",
  "code": "NotFound",
  "message": "resource not found",
  "details": ["the requested resource does not exist"]
}

​

错误体字段

字段	类型	必填	说明
requestId	string	是	请求追踪 ID，排错时请提供给支持方
code	string	是	稳定错误码，供程序分支处理
message	string	是	人类可读说明
details	array	否	附加信息；无内容时可省略

​

常见 HTTP 与 code 对照

HTTP 状态码	code（示例）	说明
400	BadRequest	参数不合法
401	Unauthorized	未携带或 API Key 无效
403	Forbidden	无权访问该组织或资源
404	NotFound	资源不存在
409	AlreadyExists	资源冲突
500	InternalError	服务端错误

部分错误经网关或服务层转换后，HTTP 状态码与 code 的组合以实际响应为准；请勿仅依赖状态码做唯一判断。

​

认证

所有请求须在 HTTP 头中携带：

Authorization: Bearer <api_key>

将 <api_key> 替换为控制台创建的密钥。勿将真实 Key 写入客户端可公开反编译的包或公共仓库。

​

组织级基础路径

多数接口在以下路径下扩展：

/v1/organizations/{organization_id}

其中 organization_id 为路径参数，表示目标组织。具体子路径见 成员、用量、AI 代码指标 各篇。