> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 约定与规范

> 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  | 下一页游标；**省略或为空**表示无更多数据 |

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

## 错误响应

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

```json theme={null}
{
  "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` | 服务端错误           |

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

## 认证

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

```http theme={null}
Authorization: Bearer <api_key>
```

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

## 组织级基础路径

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

`/v1/organizations/{organization_id}`

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