cursor-api/README.md

# cursor-api

## 说明

* 当前版本已稳定，若发现响应出现缺字漏字，与本程序无关。
* 若发现首字慢，与本程序无关。
* 若发现响应出现乱码，也与本程序无关。
* 属于官方的问题，请不要像作者反馈。
* 本程序拥有堪比客户端原本的速度，甚至可能更快。
* 本程序的性能是非常厉害的。
* 根据本项目开源协议，Fork的项目不能以作者的名义进行任何形式的宣传、推广或声明。
* 更新的时间跨度达5月有余了，求赞助，项目不收费，不定制。
* 推荐自部署，[官方网站](https://cc.wisdgod.com) 仅用于作者测试，不保证稳定性。

## 获取key

1. 访问 [www.cursor.com](https://www.cursor.com) 并完成注册登录
2. 在浏览器中打开开发者工具（F12）
3. 在 Application-Cookies 中查找名为 `WorkosCursorSessionToken` 的条目，并复制其第三个字段。请注意，%3A%3A 是 :: 的 URL 编码形式，cookie 的值使用冒号 (:) 进行分隔。

## 配置说明

### 环境变量

* `PORT`: 服务器端口号（默认：3000）
* `AUTH_TOKEN`: 认证令牌（必须，用于API认证）
* `ROUTE_PREFIX`: 路由前缀（可选）

更多请查看 `/env-example`

### Token文件格式（已弃用）

`.tokens` 文件：每行为token和checksum的对应关系：

```
# 这里的#表示这行在下次读取要删除
token1,checksum1
token2,checksum2
```

该文件可以被自动管理，但用户仅可在确认自己拥有修改能力时修改，一般仅有以下情况需要手动修改：

* 需要删除某个 token
* 需要使用已有 checksum 来对应某一个 token

### 模型列表

写死了，后续也不会会支持自定义模型列表，因为本身就支持动态更新，详见[更新模型列表说明](#更新模型列表说明)

```
claude-4-sonnet
claude-4-sonnet-thinking
claude-4-opus-thinking
claude-4-opus
default
claude-3.5-sonnet
o3
gemini-2.5-pro-preview-05-06
gemini-2.5-flash-preview-04-17
gpt-4.1
claude-3.7-sonnet
claude-3.7-sonnet-thinking
cursor-small
claude-3.5-haiku
gemini-2.5-pro-exp-03-25
gpt-4o
o4-mini
deepseek-r1
deepseek-v3.1
grok-3-beta
grok-3-mini
```

支持图像(default始终支持)：
```
claude-4-sonnet
claude-4-sonnet-thinking
claude-4-opus-thinking
claude-4-opus
claude-3.5-sonnet
o3
gemini-2.5-pro-preview-05-06
gemini-2.5-flash-preview-04-17
gpt-4.1
claude-3.7-sonnet
claude-3.7-sonnet-thinking
claude-3.5-haiku
gemini-2.5-pro-exp-03-25
gpt-4o
o4-mini
```

支持思考：
```
claude-4-sonnet-thinking
claude-4-opus-thinking
o3
gemini-2.5-pro-preview-05-06
gemini-2.5-flash-preview-04-17
claude-3.7-sonnet-thinking
gemini-2.5-pro-exp-03-25
o4-mini
deepseek-r1
```

支持Max与非Max：
```
claude-4-sonnet
claude-4-sonnet-thinking
claude-3.5-sonnet
gemini-2.5-pro-preview-05-06
gpt-4.1
claude-3.7-sonnet
claude-3.7-sonnet-thinking
gemini-2.5-pro-exp-03-25
o4-mini
grok-3-beta
```

Max Only：
```
claude-4-opus-thinking
claude-4-opus
o3
```

非Max Only：
```
default
gemini-2.5-flash-preview-04-17
cursor-small
claude-3.5-haiku
gpt-4o
deepseek-r1
deepseek-v3.1
grok-3-mini
```

## 接口说明

### 基础对话

* 接口地址: `/v1/chat/completions`
* 请求方法: POST
* 认证方式: Bearer Token
  1. 使用环境变量 `AUTH_TOKEN` 进行认证
  2. ~~使用 `.token` 文件中的令牌列表进行轮询认证~~ 在v0.1.3的rc版本更新中移除`.token`文件
  3. ~~自v0.1.3-rc.3起支持直接使用 token,checksum 进行认证，但未提供配置关闭~~ v0.3.0起不再支持
  4. 使用 `/build-key` 构建的动态密钥认证
  5. 使用 `/config` 设置的共享Token进行认证 (关联：环境变量`SHARED_TOKEN`)
  6. 日志中的缓存 token key 的两种表示方式认证 (`/build-key` 同时也会给出这两种格式作为动态密钥的别名，该数字key本质为一个192位的整数)

#### 请求格式

```json
{
  "model": string,
  "messages": [
    {
      "role": "system" | "user" | "assistant", // 也可以是 "developer" | "human" | "ai"
      "content": string | [
        {
          "type": "text" | "image_url",
          "text": string,
          "image_url": {
            "url": string
          }
        }
      ]
    }
  ],
  "stream": boolean,
  "stream_options": {
    "include_usage": boolean
  }
}
```

#### 响应格式

如果 `stream` 为 `false`:

```json
{
  "id": string,
  "object": "chat.completion",
  "created": number,
  "model": string,
  "choices": [
    {
      "index": number,
      "message": {
        "role": "assistant",
        "content": string
      },
      "finish_reason": "stop" | "length"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

如果 `stream` 为 `true`:

```
data: {"id":string,"object":"chat.completion.chunk","created":number,"model":string,"choices":[{"index":number,"delta":{"role":"assistant","content":string},"finish_reason":null}]}

data: {"id":string,"object":"chat.completion.chunk","created":number,"model":string,"choices":[{"index":number,"delta":{"content":string},"finish_reason":null}]}

data: {"id":string,"object":"chat.completion.chunk","created":number,"model":string,"choices":[{"index":number,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

### 获取模型列表

* 接口地址: `/v1/models`
* 请求方法: GET
* 认证方式: Bearer Token

#### 查询参数

可选的 JSON 请求体用于作为请求模型列表的参数：

```json
{
  "is_nightly": boolean,                    // 是否包含 nightly 版本模型，默认 false
  "include_long_context_models": boolean,   // 是否包含长上下文模型，默认 false  
  "exclude_max_named_models": boolean,      // 是否排除 max 命名的模型，默认 false
  "additional_model_names": [string]        // 额外包含的模型名称列表，默认空数组
}
```

**注意**: 认证可选，查询参数可选且认证时生效，未提供时使用默认值。

#### 响应格式

```json
{
  "object": "list",
  "data": [
    {
      "id": string,
      "display_name": string,
      "created": number,
      "created_at": string,
      "object": "model",
      "type": "model", 
      "owned_by": string,
      "supports_thinking": boolean,
      "supports_images": boolean,
      "supports_max_mode": boolean,
      "supports_non_max_mode": boolean
    }
  ]
}
```

#### 更新模型列表说明

每次携带Token时都会拉取最新的模型列表，与上次更新需距离至少30分钟。`additional_model_names` 可以用添加额外模型。

### Token管理接口

#### 简易Token信息管理页面

* 接口地址: `/tokens`
* 请求方法: GET
* 响应格式: HTML页面
* 功能: 调用下面的各种相关API的示例页面

#### 获取Token信息

* 接口地址: `/tokens/get`
* 请求方法: POST
* 认证方式: Bearer Token
* 响应格式:

```json
{
  "status": "success",
  "tokens": [
    [
      number,
      string,
      {
        "bundle": {
          "primary_token": string,
          "secondary_token": string, // 可选
          "checksum": {
            "first": string,
            "second": string,
          },
          "client_key": string, // 可选，非空时显示
          "config_version": string, // 可选
          "session_id": string, // 可选
          "proxy": string, // 可选
          "timezone": string, // 可选
          "gcpp_host": object, // 可选
          "user": { // 可选
            "email": string,
            "name": string,
            "updated_at": string,
            "picture": string, // 可选
            "is_on_new_pricing": boolean
          }
        },
        "status": "enabled" | "disabled",
        "stripe": { // 可选
          "membership_type": "free" | "free_trial" | "pro" | "pro_plus" | "ultra" | "enterprise",
          "payment_id": string, // 可选
          "days_remaining_on_trial": number,
          "subscription_status": "trialing" | "active" | "incomplete" | "incomplete_expired" | "past_due" | "canceled" | "unpaid" | "paused", // 可选
          "verified_student": boolean, // 可选
          "is_on_student_plan": boolean // 可选
        }
      }
    ]
  ],
  "tokens_count": number
}
```

#### 设置Token信息

* 接口地址: `/tokens/set`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
[
  [
    string,
    {
      "bundle": {
        "primary_token": string,
        "secondary_token": string, // 可选
        "checksum": {
          "first": string,
          "second": string,
        },
        "client_key": string, // 可选
        "config_version": string, // 可选
        "session_id": string, // 可选
        "proxy": string, // 可选
        "timezone": string, // 可选
        "gcpp_host": object, // 可选
        "user": { // 可选
          "email": string,
          "name": string,
          "updated_at": string,
          "picture": string, // 可选
          "is_on_new_pricing": boolean
        }
      },
      "status": "enabled" | "disabled",
      "stripe": { // 可选
        "membership_type": "free" | "free_trial" | "pro" | "pro_plus" | "ultra" | "enterprise",
        "payment_id": string, // 可选
        "days_remaining_on_trial": number,
        "subscription_status": "trialing" | "active" | "incomplete" | "incomplete_expired" | "past_due" | "canceled" | "unpaid" | "paused", // 可选
        "verified_student": boolean // 可选
      }
    }
  ]
]
```

* 响应格式:

```json
{
  "status": "success",
  "tokens_count": number,
  "message": "Token files have been updated and reloaded"
}
```

#### 添加Token

* 接口地址: `/tokens/add`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "tokens": [
    {
      "alias": string, // 可选，无则自动生成
      "token": string,
      "checksum": string, // 可选，无则自动生成
      "client_key": string, // 可选，无则自动生成
      "session_id": string, // 可选
      "config_version": string, // 可选
      "proxy": string, // 可选
      "timezone": string, // 可选
      "gcpp_host": string // 可选
    }
  ],
  "status": "enabled" | "disabled"
}
```

* 响应格式:

```json
{
  "status": "success",
  "tokens_count": number,
  "message": string  // "New tokens have been added and reloaded" 或 "No new tokens were added"
}
```

#### 删除Token

* 接口地址: `/tokens/del`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "aliases": [string], // 要删除的token列表
  "include_failed_tokens": boolean // 默认为false
}
```

* 响应格式:

```json
{
  "status": "success",
  "failed_tokens": [string] // 可选，根据include_failed_tokens返回，表示未找到的token列表
}
```

* expectation说明:
  - simple: 只返回基本状态
  - updated_tokens: 返回更新后的token列表
  - failed_tokens: 返回未找到的token列表
  - detailed: 返回完整信息（包括updated_tokens和failed_tokens）

#### 设置Tokens标签（已弃用）

* 接口地址: `/tokens/tags/set`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "tokens": [string],
  "tags": {
    string: null | string // 键可以为 timezone: 时区标识符 或 proxy: 代理名称
  }
}
```

* 响应格式:

```json
{
  "status": "success",
  "message": string  // "标签更新成功"
}
```

#### 更新令牌Profile

* 接口地址: `/tokens/profile/update`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
[
  string // aliases
]
```

* 响应格式:

```json
{
  "status": "success",
  "message": "已更新{}个令牌配置, {}个令牌更新失败"
}
```

#### 更新令牌CV

* 接口地址: `/tokens/config-version/update`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
[
  string // aliases
]
```

* 响应格式:

```json
{
  "status": "success",
  "message": "已更新{}个令牌配置版本, {}个令牌更新失败"
}
```

#### 刷新令牌

* 接口地址: `/tokens/refresh`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
[
  string // aliases
]
```

* 响应格式:

```json
{
  "status": "success",
  "message": "已刷新{}个令牌, {}个令牌刷新失败"
}
```

#### 设置令牌状态

* 接口地址: `/tokens/status/set`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "aliases": [string],
  "status": "enabled" | "disabled"
}
```

* 响应格式:

```json
{
  "status": "success",
  "message": "已设置{}个令牌状态, {}个令牌设置失败"
}
```

#### 设置令牌别名

* 接口地址: `/tokens/alias/set`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "{old_alias}": "{new_alias}"
}
```

* 响应格式:

```json
{
  "status": "success",
  "message": "已设置{}个令牌别名, {}个令牌设置失败"
}
```

#### 设置Tokens代理

* 接口地址: `/tokens/proxy/set`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "aliases": [string],
  "proxy": string  // 可选，代理地址，null表示清除代理
}
```

* 响应格式:

```json
{
  "status": "success",
  "message": "已设置{}个令牌代理, {}个令牌设置失败"
}
```

#### 设置Tokens时区

* 接口地址: `/tokens/timezone/set`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "aliases": [string],
  "timezone": string  // 可选，时区标识符（如"Asia/Shanghai"），null表示清除时区
}
```

* 响应格式:

```json
{
  "status": "success",
  "message": "已设置{}个令牌时区, {}个令牌设置失败"
}
```

#### 构建API Key

* 接口地址: `/build-key`
* 请求方法: POST
* 认证方式: Bearer Token (当SHARE_AUTH_TOKEN启用时需要)
* 请求格式:

```json
{
  "token": string,               // 格式: JWT
  "checksum": {
    "first": string,             // 格式: 长度为64的Hex编码字符串
    "second": string,            // 格式: 长度为64的Hex编码字符串
  },
  "client_key": string,          // 格式: 长度为64的Hex编码字符串
  "config_version": string,      // 格式: UUID
  "session_id": string,          // 格式: UUID
  "secret": string,              // 可选，没什么用
  "proxy_name": string,          // 可选，指定代理
  "timezone": string,            // 可选，指定时区
  "gcpp_host": string,           // 可选，代码补全区域
  "disable_vision": boolean,       // 可选，禁用图片处理能力
  "enable_slow_pool": boolean,     // 可选，启用慢速池
  "include_web_references": boolean,
  "usage_check_models": {          // 可选，使用量检查模型配置
    "type": "default" | "disabled" | "all" | "custom",
    "model_ids": string  // 当type为custom时生效，以逗号分隔的模型ID列表
  }
}
```

* 响应格式:

```json
{
  "keys": [string]    // 成功时返回生成的key
}
```

或出错时:

```json
{
  "error": string  // 错误信息
}
```

说明：

1. 此接口用于生成携带动态配置的API Key，是对直接传token与checksum模式的升级版本，在0.3起，直接传token与checksum的方式已经不再适用

2. 生成的key格式为: `sk-{encoded_config}`，其中sk-为默认前缀(可配置)

3. usage_check_models配置说明:
   - default: 使用默认模型列表(同下 `usage_check_models` 字段的默认值)
   - disabled: 禁用使用量检查
   - all: 检查所有可用模型
   - custom: 使用自定义模型列表(需在model_ids中指定)

4. 在当前版本，keys数组长度总为3，后2个基于缓存，仅第1个使用过才行：
   1. 完整key，旧版本也存在
   2. 数字key的base64编码版本
   3. 数字key的明文版本

5. 数字key是一个128位无符号整数与一个64位无符号整数组成的，比通常使用的uuid更难破解。

#### 获取Config Version

* 接口地址: `/config-version`
* 请求方法: POST
* 认证方式: Bearer Token (当SHARE_AUTH_TOKEN启用时需要)
* 请求格式:

```json
{
  "token": string,               // 格式: JWT
  "checksum": {
    "first": string,             // 格式: 长度为64的Hex编码字符串
    "second": string,            // 格式: 长度为64的Hex编码字符串
  },
  "client_key": string,          // 格式: 长度为64的Hex编码字符串
  "session_id": string,          // 格式: UUID
  "proxy_name": string,          // 可选，指定代理
  "timezone": string,            // 可选，指定时区
  "gcpp_host": string            // 可选，代码补全区域
}
```

* 响应格式:

```json
{
  "config_version": string    // 成功时返回生成的UUID
}
```

或出错时:

```json
{
  "error": string  // 错误信息
}
```

### 代理管理接口

#### 简易代理信息管理页面

* 接口地址: `/proxies`
* 请求方法: GET
* 响应格式: HTML页面
* 功能: 调用下面的各种相关API的示例页面

#### 获取代理配置信息

* 接口地址: `/proxies/get`
* 请求方法: POST
* 响应格式:

```json
{
  "status": "success",
  "proxies": {
    "proxies": {
      "proxy_name": "non" | "sys" | "http://proxy-url",
    },
    "general": string // 当前使用的通用代理名称
  },
  "proxies_count": number,
  "general_proxy": string,
  "message": string // 可选
}
```

#### 设置代理配置

* 接口地址: `/proxies/set`
* 请求方法: POST
* 请求格式:

```json
{
  "proxies": {
    "{proxy_name}": "non" | "sys" | "http://proxy-url"
  },
  "general": string  // 要设置的通用代理名称
}
```

* 响应格式:

```json
{
  "status": "success",
  "proxies_count": number,
  "message": "代理配置已更新"
}
```

#### 添加代理

* 接口地址: `/proxies/add`
* 请求方法: POST
* 请求格式:

```json
{
  "proxies": {
    "{proxy_name}": "non" | "sys" | "http://proxy-url"
  }
}
```

* 响应格式:

```json
{
  "status": "success",
  "proxies_count": number,
  "message": string  // "已添加 X 个新代理" 或 "没有添加新代理"
}
```

#### 删除代理

* 接口地址: `/proxies/del`
* 请求方法: POST
* 请求格式:

```json
{
  "names": [string],  // 要删除的代理名称列表
  "expectation": "simple" | "updated_proxies" | "failed_names" | "detailed"  // 默认为simple
}
```

* 响应格式:

```json
{
  "status": "success",
  "updated_proxies": {  // 可选，根据expectation返回
    "proxies": {
      "proxy_name": "non" | "sys" | "http://proxy-url"
    },
    "general": string
  },
  "failed_names": [string]  // 可选，根据expectation返回，表示未找到的代理名称列表
}
```

#### 设置通用代理

* 接口地址: `/proxies/set-general`
* 请求方法: POST
* 请求格式:

```json
{
  "name": string  // 要设置为通用代理的代理名称
}
```

* 响应格式:

```json
{
  "status": "success",
  "message": "通用代理已设置"
}
```

#### 代理类型说明

* `non`: 表示不使用代理
* `sys`: 表示使用系统代理
* 其他: 表示具体的代理URL地址（如 `http://proxy-url`）

#### 注意事项

1. 代理名称必须是唯一的，添加重复名称的代理会被忽略
2. 设置通用代理时，指定的代理名称必须存在于当前的代理配置中
3. 删除代理时的 expectation 参数说明：
   - simple: 只返回基本状态
   - updated_proxies: 返回更新后的代理配置
   - failed_names: 返回未找到的代理名称列表
   - detailed: 返回完整信息（包括updated_proxies和failed_names）

### 错误格式

所有接口在发生错误时会返回统一的错误格式：

```json
{
  "status": "error",
  "code": number,   // 可选
  "error": string,  // 可选，错误详细信息
  "message": string // 错误提示信息
}
```

### 配置管理接口

#### 配置页面

* 接口地址: `/config`
* 请求方法: GET
* 响应格式: HTML页面
* 功能: 提供配置管理界面,可以修改页面内容和系统配置

#### 更新配置

* 接口地址: `/config`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "action": "get" | "update" | "reset",
  "path": string,
  "content": {
    "type": "default" | "not_found" | "redirect" | "plain_text" | "html" | "css" | "js",
    "value": string  // type=redirect时为URL, type=plain_text/html/css/js时为对应内容
  },
  "vision_ability": "none" | "base64" | "all", // "disabled" | "base64-only" | "base64-http"
  "enable_slow_pool": boolean,
  "enable_long_context": boolean,
  "usage_check_models": {
    "type": "none" | "default" | "all" | "list",
    "content": string
  },
  "enable_dynamic_key": boolean,
  "share_token": string,
  "calibrate_token": string,
  "include_web_references": boolean
}
```

* 响应格式:

```json
{
  "status": "success",
  "message": string,
  "data": {
    "content": {
      "type": "default" | "not_found" | "redirect" | "plain_text" | "html" | "css" | "js",
      "value": string
    },
    "vision_ability": "none" | "base64" | "all",
    "enable_slow_pool": boolean,
    "enable_long_context": boolean,
    "usage_check_models": {
      "type": "none" | "default" | "all" | "list",
      "content": string
    },
    "enable_dynamic_key": boolean,
    "share_token": string,
    "calibrate_token": string,
    "include_web_references": boolean
  }
}
```

注意：`usage_check_models` 字段的默认值为非"cursor-small"、"deepseek-v3.1"、"grok-3-mini"的所有模型。

这些模型将默认进行使用量检查。您可以通过配置接口修改此设置。

### 日志管理接口

#### 获取日志接口

* 接口地址: `/logs`
* 请求方法: GET
* 响应格式: 根据配置返回不同的内容类型(默认、文本或HTML)

#### 获取日志数据

* 接口地址: `/logs/get`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
{
  "query": {
    // 分页与排序控制
    "limit": number,             // 可选，返回记录数量限制
    "offset": number,            // 可选，起始位置偏移量
    "reverse": boolean,          // 可选，反向排序，默认false（从旧到新），true时从新到旧

    // 时间范围过滤
    "from_date": string,         // 可选，开始日期时间，RFC3339格式
    "to_date": string,           // 可选，结束日期时间，RFC3339格式

    // 用户标识过滤
    "user_id": string,           // 可选，按用户ID精确匹配
    "email": string,             // 可选，按用户邮箱过滤（支持部分匹配）
    "membership_type": string,   // 可选，按会员类型过滤 ("free"/"free_trial"/"pro"/"enterprise")

    // 核心业务过滤
    "status": string,            // 可选，按状态过滤 ("pending"/"success"/"failure")
    "model": string,             // 可选，按模型名称过滤（支持部分匹配）
    "include_models": [string],  // 可选，包含特定模型
    "exclude_models": [string],  // 可选，排除特定模型

    // 请求特征过滤
    "stream": boolean,           // 可选，是否为流式请求
    "has_chain": boolean,        // 可选，是否包含对话链
    "has_usage": boolean,        // 可选，是否有usage信息

    // 错误相关过滤
    "has_error": boolean,        // 可选，是否包含错误
    "error": string,             // 可选，按错误过滤（支持部分匹配）

    // 性能指标过滤
    "min_total_time": number,    // 可选，最小总耗时（秒）
    "max_total_time": number,    // 可选，最大总耗时（秒）
    "min_tokens": number,        // 可选，最小token数（input + output）
    "max_tokens": number         // 可选，最大token数
  }
}
```

* 响应格式:

```json
{
  "total": number,
  "logs": [
    {
      "id": number,
      "timestamp": string,
      "model": string,
      "token_info": {
        "key": string,
        "stripe": { // 可选
          "membership_type": "free" | "free_trial" | "pro" | "pro_plus" | "ultra" | "enterprise",
          "payment_id": string, // 可选
          "days_remaining_on_trial": number,
          "subscription_status": "trialing" | "active" | "incomplete" | "incomplete_expired" | "past_due" | "canceled" | "unpaid" | "paused", // 可选
          "verified_student": boolean // 可选
        }
      },
      "chain": {
        "prompt": [ // array or string
          {
            "role": string,
            "content": string
          }
        ],
        "delays": [
          string,
          [
            number, // chars count
            number // time
          ]
        ],
        "usage": { // optional
          "input": number,
          "output": number,
        }
      },
      "timing": {
        "total": number
      },
      "stream": boolean,
      "status": string,
      "error": string
    }
  ],
  "timestamp": string,
  "status": "success"
}
```

* 说明：
  - 所有查询参数都是可选的
  - 管理员可以查看所有日志，普通用户只能查看与其token相关的日志
  - 如果提供了无效的状态或会员类型，将返回空结果
  - 日期时间格式需遵循 RFC3339 标准，如："2024-03-20T15:30:00+08:00"
  - 邮箱和模型名称支持部分匹配

#### 获取日志令牌

* 接口地址: `/logs/tokens/get`
* 请求方法: POST
* 认证方式: Bearer Token
* 请求格式:

```json
[
  string
]
```

* 响应格式:

```json
{
  "status": "success",
  "tokens": {
    "{key}": {
      "primary_token": string,
      "secondary_token": string, // 可选
      "checksum": {
        "first": string,
        "second": string,
      },
      "client_key": string, // 可选，非空时显示
      "config_version": string, // 可选
      "session_id": string, // 可选
      "proxy": string, // 可选
      "timezone": string, // 可选
      "gcpp_host": object, // 可选
      "user": { // 可选
        "email": string,
        "name": string,
        "updated_at": string,
        "picture": string, // 可选
        "is_on_new_pricing": boolean
      }
    }
  },
  "total": number,
  "timestamp": string
}
```

### 静态资源接口

#### 获取共享样式

* 接口地址: `/static/shared-styles.css`
* 请求方法: GET
* 响应格式: CSS文件
* 功能: 获取共享样式表

#### 获取共享脚本

* 接口地址: `/static/shared.js`
* 请求方法: GET
* 响应格式: JavaScript文件
* 功能: 获取共享JavaScript代码

#### 获取其他资源

* 接口地址: `/static/{path}`
* 请求方法: GET
* 请求参数:
  - `path`: 静态文件的相对路径

* 响应格式:
  - **成功响应 (200 OK)**:
    - Headers:
      - `Content-Type`: 根据文件扩展名自动设置（见下方MIME类型映射表）
      - `Content-Length`: 文件大小
    - Body: 文件的二进制内容

  - **文件不存在或大小超过4GiB (404 Not Found)**:
    - Headers:
      - `Content-Type`: `text/plain; charset=utf-8`
    - Body: 错误信息

* 支持的MIME类型映射:
  - 文本类型: html, htm, txt, css, js, mjs, csv, xml, md, markdown
  - 图像类型: jpg, jpeg, png, gif, webp, svg, bmp, ico, tiff, tif, avif
  - 音频类型: mp3, mp4a, wav, ogg, oga, weba, aac, flac, m4a
  - 视频类型: mp4, mpeg, mpg, webm, ogv, avi, mov, qt, flv
  - 文档类型: pdf, doc, docx, xls, xlsx, ppt, pptx
  - 压缩文件: zip, rar, 7z, gz, gzip, tar
  - 字体类型: ttf, otf, woff, woff2
  - 其他类型: 默认为 `application/octet-stream`

* 功能: 获取从环境变量DATA_DIR指定的目录下的子目录static下的文件。

#### 环境变量示例

* 接口地址: `/env-example`
* 请求方法: GET
* 响应格式: 文本文件
* 功能: 获取环境变量配置示例

### 健康检查接口

* **接口地址**: `/health` 或 `/`(重定向)
* **请求方法**: GET
* **认证方式**: 无需
* **响应格式**: 根据配置返回不同的内容类型(默认JSON、文本或HTML)

#### 响应结构

```json
{
  "status": "success",
  "service": {
    "name": "cursor-api",
    "version": "1.0.0",
    "is_debug": false,
    "build": {
      "version": 1,
      "timestamp": "2024-01-15T10:30:00Z",
      "is_debug": false,
      "is_prerelease": false
    }
  },
  "runtime": {
    "started_at": "2024-01-15T10:00:00+08:00",
    "uptime_seconds": 1800,
    "requests": {
      "total": 1250,
      "active": 3,
      "errors": 12
    }
  },
  "system": {
    "memory": {
      "used_bytes": 134217728,
      "used_percentage": 12.5,
      "available_bytes": 1073741824
    },
    "cpu": {
      "usage_percentage": 15.2,
      "load_average": [0.8, 1.2, 1.5]
    }
  },
  "capabilities": {
    "models": ["gpt-4", "claude-3"],
    "endpoints": ["/chat", "/completions", "/embeddings"],
    "features": ["streaming", "function_calling", "vision"]
  }
}
```

#### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | string | 服务状态: "success", "warning", "error" |
| `service.name` | string | 服务名称 |
| `service.version` | string | 服务版本 |
| `service.is_debug` | boolean | 是否为调试模式 |
| `service.build.version` | number | 构建版本号(仅preview功能启用时) |
| `service.build.timestamp` | string | 构建时间戳 |
| `service.build.is_prerelease` | boolean | 是否为预发布版本 |
| `runtime.started_at` | string | 服务启动时间 |
| `runtime.uptime_seconds` | number | 运行时长(秒) |
| `runtime.requests.total` | number | 总请求数 |
| `runtime.requests.active` | number | 当前活跃请求数 |
| `runtime.requests.errors` | number | 错误请求数 |
| `system.memory.used_bytes` | number | 已使用内存(字节) |
| `system.memory.used_percentage` | number | 内存使用率(%) |
| `system.memory.available_bytes` | number | 可用内存(字节,可选) |
| `system.cpu.usage_percentage` | number | CPU使用率(%) |
| `system.cpu.load_average` | array | 系统负载[1分钟,5分钟,15分钟] |
| `capabilities.models` | array | 支持的模型列表 |
| `capabilities.endpoints` | array | 可用的API端点 |
| `capabilities.features` | array | 支持的功能特性 |

### 其他接口

#### 随机生成一个uuid

* 接口地址: `/gen-uuid`
* 请求方法: GET
* 响应格式:

```plaintext
string
```

#### 随机生成一个hash

* 接口地址: `/gen-hash`
* 请求方法: GET
* 响应格式:

```plaintext
string
```

#### 随机生成一个checksum

* 接口地址: `/gen-checksum`
* 请求方法: GET
* 响应格式:

```plaintext
string
```

#### 随机生成一个token（已弃用）

* 接口地址: `/gen-token`
* 请求方法: GET
* 响应格式:

```plaintext
string
```

#### 获取当前的timestampheader

* 接口地址: `/get-timestamp-header`
* 请求方法: GET
* 响应格式:

```plaintext
string
```

#### 获取用户信息（已弃用）

* 接口地址: `/userinfo`
* 请求方法: POST
* 认证方式: 请求体中包含token
* 请求格式:

```json
{
  "token": string
}
```

* 响应格式:

```json
{
  "usage": {
    "premium": {
      "num_requests": number,
      "total_requests": number,
      "num_tokens": number,
      "max_requests": number,
      "max_tokens": number
    },
    "standard": {
      "num_requests": number,
      "total_requests": number,
      "num_tokens": number,
      "max_requests": number,
      "max_tokens": number
    },
    "start_of_month": string
  },
  "user": {
    "email": string,
    "name": string,
    "id": string,
    "updated_at": string
  },
  "stripe": {
    "membership_type": "free" | "free_trial" | "pro" | "enterprise",
    "payment_id": string,
    "days_remaining_on_trial": number
  }
}
```

如果发生错误，响应格式为:

```json
{
  "error": string
}
```

#### 获取更新令牌（已弃用）

* 接口地址: `/token-upgrade`
* 请求方法: POST
* 认证方式: 请求体中包含token
* 请求格式:

```json
{
  "token": string
}
```

* 响应格式:

```json
{
  "status": "success" | "failure" | "error",
  "message": string,
  "result": string // optional
}
```

#### 基础校准（已弃用）

* 接口地址: `/basic-calibration`
* 请求方法: POST
* 认证方式: 请求体中包含token
* 请求格式:

```json
{
  "token": string
}
```

* 响应格式:

```json
{
  "status": "success" | "error",
  "message": string,
  "user_id": string,
  "create_at": string
}
```

注意: `user_id` 和 `create_at` 字段在校验失败时可能不存在。

## Copilot++ 接口文档

1. 相关接口都需要 `x-client-key`, 格式请见 `/gen-hash`（32字节）。
2. Cookie `FilesyncCookie` 是16字节，工作区不变即不变。
3. 关于形如 `AWSALBAPP-0` 的 Cookie 具有7天有效期，可能变化，详情请查阅 Amazon 相关文档。
4. `FilesyncCookie` 和 `AWSALBAPP` 总是被 `/file/upload` 或 `/file/sync`。
5. 以下所有接口都使用 POST 方法，且都需要认证。

### 获取代码补全服务的配置信息

* 接口地址: `/cpp/config`

#### 请求格式

```json
{
  "is_nightly": boolean,  // 可选，是否使用nightly版本
  "model": string,        // 模型名称
  "supports_cpt": boolean // 可选，是否支持CPT
}
```

### 响应格式

```json
{
  "above_radius": number,                                        // 可选，上方扫描半径
  "below_radius": number,                                        // 可选，下方扫描半径
  "merge_behavior": {                                            // 可选，合并行为
    "type": string,
    "limit": number,                                             // 可选，限制
    "radius": number                                             // 可选，半径
  },
  "is_on": boolean,                                              // 可选，是否开启
  "is_ghost_text": boolean,                                      // 可选，是否使用幽灵文本
  "should_let_user_enable_cpp_even_if_not_pro": boolean,         // 可选，非专业用户是否可以启用
  "heuristics": [                                                // 启用的启发式规则列表
    "lots_of_added_text",
    "duplicating_line_after_suggestion",
    "duplicating_multiple_lines_after_suggestion",
    "reverting_user_change",
    "output_extends_beyond_range_and_is_repeated",
    "suggesting_recently_rejected_edit"
  ],
  "exclude_recently_viewed_files_patterns": [string],            // 最近查看文件排除模式
  "enable_rvf_tracking": boolean,                                // 是否启用RVF跟踪
  "global_debounce_duration_millis": number,                     // 全局去抖动时间(毫秒)
  "client_debounce_duration_millis": number,                     // 客户端去抖动时间(毫秒)
  "cpp_url": string,                                             // CPP服务URL
  "use_whitespace_diff_history": boolean,                        // 是否使用空白差异历史
  "import_prediction_config": {                                  // 导入预测配置
    "is_disabled_by_backend": boolean,                           // 是否被后端禁用
    "should_turn_on_automatically": boolean,                     // 是否自动开启
    "python_enabled": boolean                                    // Python是否启用
  },
  "enable_filesync_debounce_skipping": boolean,                  // 是否启用文件同步去抖动跳过
  "check_filesync_hash_percent": number,                         // 文件同步哈希检查百分比
  "geo_cpp_backend_url": string,                                 // 地理位置CPP后端URL
  "recently_rejected_edit_thresholds": {                         // 可选，最近拒绝编辑阈值
    "hard_reject_threshold": number,                             // 硬拒绝阈值
    "soft_reject_threshold": number                              // 软拒绝阈值
  },
  "is_fused_cursor_prediction_model": boolean,                   // 是否使用融合光标预测模型
  "include_unchanged_lines": boolean,                            // 是否包含未更改行
  "should_fetch_rvf_text": boolean,                              // 是否获取RVF文本
  "max_number_of_cleared_suggestions_since_last_accept": number, // 可选，上次接受后清除建议的最大数量
  "suggestion_hint_config": {                                    // 可选，建议提示配置
    "important_lsp_extensions": [string],                        // 重要的LSP扩展
    "enabled_for_path_extensions": [string]                      // 启用的路径扩展
  }
}
```

### 获取可用的代码补全模型列表

* 接口地址: `/cpp/models`

#### 请求格式

无

### 响应格式

```json
{
  "models": [string],     // 可用模型列表
  "default_model": string // 可选，默认模型
}
```

### 上传文件

* 接口地址: `/file/upload`

#### 请求格式

```json
{
  "uuid": string,                    // 文件标识符
  "relative_workspace_path": string, // 文件相对于工作区的路径
  "contents": string,                // 文件内容
  "model_version": number,           // 模型版本
  "sha256_hash": string              // 可选，文件的SHA256哈希值
}
```

### 响应格式

```json
{
  "error": string // 错误类型：unspecified, non_existant, hash_mismatch
}
```

### 同步文件变更

* 接口地址: `/file/sync`

#### 请求格式

```json
{
  "uuid": string,                                // 文件标识符
  "relative_workspace_path": string,             // 文件相对于工作区的路径
  "model_version": number,                       // 模型版本
  "filesync_updates": [                          // 文件同步更新数组
    {
      "model_version": number,                   // 模型版本
      "relative_workspace_path": string,         // 文件相对于工作区的路径
      "updates": [                               // 单个更新请求数组
        {
          "start_position": number,              // 更新开始位置
          "end_position": number,                // 更新结束位置
          "change_length": number,               // 变更长度
          "replaced_string": string,             // 替换的字符串
          "range": {                             // 简单范围
            "start_line_number": number,         // 开始行号
            "start_column": number,              // 开始列
            "end_line_number_inclusive": number, // 结束行号（包含）
            "end_column": number                 // 结束列
          }
        }
      ],
      "expected_file_length": number             // 预期文件长度
    }
  ],
  "sha256_hash": string                          // 文件的SHA256哈希值
}
```

### 响应格式

```json
{
  "error": string // 错误类型：unspecified, non_existant, hash_mismatch
}
```

### 流式代码补全

* 接口地址: `/cpp/stream`

#### 请求格式

```json
{
  "current_file": {                                               // 当前文件信息
    "relative_workspace_path": string,                            // 文件相对于工作区的路径
    "contents": string,                                           // 文件内容
    "rely_on_filesync": boolean,                                  // 是否依赖文件同步
    "sha256_hash": string,                                        // 可选，SHA256哈希值
    "top_chunks": [                                               // 顶级代码块
      {
        "content": string,                                        // 内容
        "range": {                                                // 最简单范围
          "start_line": number,                                   // 开始行
          "end_line_inclusive": number                            // 结束行（包含）
        },
        "score": number,                                          // 分数
        "relative_path": string                                   // 相对路径
      }
    ],
    "contents_start_at_line": number,                             // 内容开始行
    "cursor_position": {                                          // 光标位置
      "line": number,                                             // 行号
      "column": number                                            // 列号
    },
    "dataframes": [                                               // 数据框信息
      {
        "name": string,                                           // 名称
        "shape": string,                                          // 形状
        "data_dimensionality": number,                            // 数据维度
        "columns": [                                              // 列
          {
            "key": string,                                        // 键
            "type": string                                        // 类型
          }
        ],
        "row_count": number,                                      // 行数
        "index_column": string                                    // 索引列
      }
    ],
    "total_number_of_lines": number,                              // 总行数
    "language_id": string,                                        // 语言ID
    "selection": {                                                // 选择范围
      "start_position": {                                         // 开始位置
        "line": number,                                           // 行号
        "column": number                                          // 列号
      },
      "end_position": {                                           // 结束位置
        "line": number,                                           // 行号
        "column": number                                          // 列号
      }
    },
    "alternative_version_id": number,                             // 可选，替代版本ID
    "diagnostics": [                                              // 诊断信息
      {
        "message": string,                                        // 消息
        "range": {                                                // 范围
          "start_position": {                                     // 开始位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          },
          "end_position": {                                       // 结束位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          }
        },
        "severity": "error" | "warning" | "information" | "hint", // 严重程度
        "related_information": [                                  // 相关信息
          {
            "message": string,                                    // 消息
            "range": {                                            // 范围
              "start_position": {                                 // 开始位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              },
              "end_position": {                                   // 结束位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              }
            }
          }
        ]
      }
    ],
    "file_version": number,                                       // 可选，文件版本
    "cell_start_lines": [number],                                 // 单元格开始行
    "workspace_root_path": string                                 // 工作区根路径
  },
  "diff_history": [string],                                       // 差异历史
  "model_name": string,                                           // 可选，模型名称
  "linter_errors": {                                              // 可选，Linter错误
    "relative_workspace_path": string,                            // 文件相对于工作区的路径
    "errors": [                                                   // 错误数组
      {
        "message": string,                                        // 错误消息
        "range": {                                                // 范围
          "start_position": {                                     // 开始位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          },
          "end_position": {                                       // 结束位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          }
        },
        "source": string,                                         // 可选，来源
        "related_information": [                                  // 相关信息数组
          {
            "message": string,                                    // 相关信息消息
            "range": {                                            // 相关信息范围
              "start_position": {                                 // 开始位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              },
              "end_position": {                                   // 结束位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              }
            }
          }
        ],
        "severity": "error" | "warning" | "information" | "hint"  // 可选，严重程度
      }
    ],
    "file_contents": string                                       // 文件内容
  },
  "context_items": [                                              // 上下文项
    {
      "contents": string,                                         // 内容
      "symbol": string,                                           // 可选，符号
      "relative_workspace_path": string,                          // 相对工作区路径
      "score": number                                             // 分数
    }
  ],
  "diff_history_keys": [string],                                  // 差异历史键
  "give_debug_output": boolean,                                   // 可选，提供调试输出
  "file_diff_histories": [                                        // 文件差异历史
    {
      "file_name": string,                                        // 文件名
      "diff_history": [string],                                   // 差异历史
      "diff_history_timestamps": [number]                         // 差异历史时间戳
    }
  ],
  "merged_diff_histories": [                                      // 合并差异历史
    {
      "file_name": string,                                        // 文件名
      "diff_history": [string],                                   // 差异历史
      "diff_history_timestamps": [number]                         // 差异历史时间戳
    }
  ],
  "block_diff_patches": [                                         // 块差异补丁
    {
      "start_model_window": {                                     // 开始模型窗口
        "lines": [string],                                        // 行
        "start_line_number": number,                              // 开始行号
        "end_line_number": number                                 // 结束行号
      },
      "changes": [                                                // 变更
        {
          "text": string,                                         // 文本
          "range": {                                              // 范围
            "start_line_number": number,                          // 开始行号
            "start_column": number,                               // 开始列
            "end_line_number": number,                            // 结束行号
            "end_column": number                                  // 结束列
          }
        }
      ],
      "relative_path": string,                                    // 相对路径
      "model_uuid": string,                                       // 模型UUID
      "start_from_change_index": number                           // 开始变更索引
    }
  ],
  "is_nightly": boolean,                                          // 可选，是否为nightly版本
  "is_debug": boolean,                                            // 可选，是否为调试模式
  "immediately_ack": boolean,                                     // 可选，立即确认
  "enable_more_context": boolean,                                 // 可选，启用更多上下文
  "parameter_hints": [                                            // 参数提示
    {
      "label": string,                                            // 标签
      "documentation": string                                     // 可选，文档
    }
  ],
  "lsp_contexts": [                                               // LSP上下文
    {
      "uri": string,                                              // URI
      "symbol_name": string,                                      // 符号名称
      "positions": [                                              // 位置
        {
          "line": number,                                         // 行
          "character": number                                     // 字符
        }
      ],
      "context_items": [                                          // 上下文项
        {
          "uri": string,                                          // 可选，URI
          "type": string,                                         // 类型
          "content": string,                                      // 内容
          "range": {                                              // 可选，范围
            "start_line": number,                                 // 开始行
            "start_character": number,                            // 开始字符
            "end_line": number,                                   // 结束行
            "end_character": number                               // 结束字符
          }
        }
      ],
      "score": number                                             // 分数
    }
  ],
  "cpp_intent_info": {                                            // 可选，代码补全意图信息
    "source": string                                              // 来源
  },
  "workspace_id": string,                                         // 可选，工作区ID
  "additional_files": [                                           // 附加文件
    {
      "relative_workspace_path": string,                          // 相对工作区路径
      "is_open": boolean,                                         // 是否打开
      "visible_range_content": [string],                          // 可见范围内容
      "last_viewed_at": number,                                   // 可选，最后查看时间
      "start_line_number_one_indexed": [number],                  // 从1开始索引的起始行号
      "visible_ranges": [                                         // 可见范围
        {
          "start_line_number": number,                            // 开始行号
          "end_line_number_inclusive": number                     // 结束行号（包含）
        }
      ]
    }
  ],
  "control_token": "quiet" | "loud" | "op",                       // 可选，控制标记
  "client_time": number,                                          // 可选，客户端时间
  "filesync_updates": [                                           // 文件同步更新
    {
      "model_version": number,                                    // 模型版本
      "relative_workspace_path": string,                          // 相对工作区路径
      "updates": [                                                // 更新数组
        {
          "start_position": number,                               // 开始位置（字符偏移量）
          "end_position": number,                                 // 结束位置（字符偏移量）
          "change_length": number,                                // 变更长度
          "replaced_string": string,                              // 替换的字符串
          "range": {                                              // 范围
            "start_line_number": number,                          // 开始行号
            "start_column": number,                               // 开始列
            "end_line_number_inclusive": number,                  // 结束行号（包含）
            "end_column": number                                  // 结束列
          }
        }
      ],
      "expected_file_length": number                              // 预期文件长度
    }
  ],
  "time_since_request_start": number,                             // 请求开始后的时间
  "time_at_request_send": number,                                 // 请求发送时的时间
  "client_timezone_offset": number,                               // 可选，客户端时区偏移
  "lsp_suggested_items": {                                        // 可选，LSP建议项
    "suggestions": [                                              // 建议
      {
        "label": string                                           // 标签
      }
    ]
  },
  "supports_cpt": boolean                                         // 可选，是否支持CPT
}
```

### 响应格式 (SSE流格式)

事件类型及对应数据格式：

1. **model_info**
```json
{
  "type": "model_info",
  "is_fused_cursor_prediction_model": boolean,
  "is_multidiff_model": boolean
}
```

2. **range_replace**
```json
{
  "type": "range_replace",
  "start_line_number": number,
  "end_line_number_inclusive": number,
  "text": string
}
```

3. **cursor_prediction**
```json
{
  "type": "cursor_prediction",
  "relative_path": string,
  "line_number_one_indexed": number,
  "expected_content": string,
  "should_retrigger_cpp": boolean
}
```

4. **text**
```json
{
  "type": "text",
  "text": string
}
```

5. **done_edit**
```json
{
  "type": "done_edit"
}
```

6. **done_stream**
```json
{
  "type": "done_stream"
}
```

7. **debug**
```json
{
  "type": "debug",
  "model_input": string,
  "model_output": string,
  "total_time": string,   // 可选
  "stream_time": string,
  "ttft_time": string,
  "server_timing": string // 可选
}
```

8. **error**
```json
{
  "type": "error",
  "message": string
}
```

9. **stream_end**
```json
{
  "type": "stream_end"
}
```

#### 来源可选值

- line_change
- typing
- option_hold
- linter_errors
- parameter_hints
- cursor_prediction
- manual_trigger
- editor_change
- lsp_suggestions

## 鸣谢

感谢以下项目和贡献者:

- [cursor-api](https://github.com/wisdgod/cursor-api) - 本项目本身
- [zhx47/cursor-api](https://github.com/zhx47/cursor-api) - 提供了本项目起步阶段的主要参考
- [luolazyandlazy/cursorToApi](https://github.com/luolazyandlazy/cursorToApi)