Skip to main content

Command Palette

Search for a command to run...

API

Admin API

Admin API 允许你以编程方式访问团队数据，包括成员信息、用量指标、支出明细、团队目录组、模型访问和 Grok Bot。

  • Admin API 使用 Basic Authentication，并将你的 API 密钥作为用户名。
  • 有关创建 API 密钥、认证方式、速率限制和最佳实践的详细信息，请参阅 API 概览。

如需执行跨团队的组织级操作，请参阅 组织 和 组织 API。

端点

获取团队成员

GET/teams/members

获取所有团队成员及其详细信息。

响应字段

teamMembers array

团队成员对象数组，每个对象包含：
  • id string - 团队成员的编码用户 ID (例如 user_PDSPmvukpYgZEDXsoNirw3CFhy)。OpenTelemetry 导出中的可选资源属性 cursor.user.account_id 也携带相同的值。
  • email string - 团队成员的电子邮件地址
  • name string - 团队成员的显示名称
  • role string - 在团队中的角色 (例如 member、owner)
  • isRemoved boolean - 该成员是否已从团队中移除
curl -X GET https://api.cursor.com/teams/members \  -u YOUR_API_KEY:

响应：

{  "teamMembers": [    {      "id": "user_PDSPmvukpYgZEDXsoNirw3CFhy",      "name": "Alex",      "email": "[email protected]",      "role": "member",      "isRemoved": false    },    {      "id": "user_kljUvI0ASZORvSEXf9hV0ydcso",      "name": "Sam",      "email": "[email protected]",      "role": "owner",      "isRemoved": false    }  ]}

获取审计日志

GET/teams/audit-logs

通过筛选获取团队的审计日志事件，用于跟踪团队活动、安全事件和配置变更。每个团队每分钟最多 20 次请求。详见速率限制和最佳实践。

参数

startTime string | number

开始时间 (默认为 7 天前) 。参见 日期格式

endTime string | number

结束时间 (默认是当前时间) 。参见 日期格式

eventTypes string

要筛选的事件类型，以逗号分隔。可能的取值： login, logout, add_user, remove_user, update_user_role, team_settings, mcp_server_config, team_api_key, user_api_key, privacy_mode, user_spend_limit, team_rule, team_repo, team_hook, team_command, create_directory_group, delete_directory_group, update_directory_group, update_directory_group_permissions, add_user_to_directory_group, remove_user_from_directory_group, bugbot_installation, bugbot_installation_settings, bugbot_repo_settings, bugbot_team_rule, bugbot_team_settings, bugbot_bulk_repo_update, grok_bot_created, grok_bot_lifecycle, sand_onboarding, grok_bot_access_changed, grok_bot_team_setup_manifest, grok_bot_group_settings, grok_bot_group_resource, grok_bot_resource, grok_bot_machine, grok_bot_vm, grok_bot_vm_bulk, grok_bot_routine, mcp_authentication, slack_account_link

search string

用于筛选事件的搜索词

page number

页码 (从1开始) 。默认值：1

pageSize number

每页结果数 (1-500) 。默认值：100

users string

按用户筛选。参见下方的 用户筛选

日期格式

startTime 和 endTime 参数支持多种格式：

  • 相对快捷方式：now、today、yesterday、7d (7 天前) 、5h (5 小时前) 、300s (300 秒前)
  • ISO 8601 字符串：2024-01-15T12:00:00Z 或 2024-01-15T10:00:00-05:00
  • YYYY-MM-DD 格式：2024-01-15 (时间默认为 00:00:00 UTC)
  • Unix 时间戳：1705315200 (秒) 或 1705315200000 (毫秒)

示例：

  • ?startTime=7d&endTime=now - 最近 7 天
  • ?startTime=5h&endTime=now - 最近 5 小时
  • ?startTime=2024-01-15&endTime=2024-01-20 - 指定日期范围
  • ?startTime=1705315200000&endTime=1705401600000 - Unix 时间戳

用户筛选

users 参数支持多种格式，使用逗号分隔：

你可以混合使用这些格式：[email protected],12345,user_PDSPmvukpYgZEDXsoNirw3CFhy

每次请求的最大用户数等于 pageSize。

curl -X GET "https://api.cursor.com/teams/[email protected],[email protected]&eventTypes=login,add_user" \  -u YOUR_API_KEY:

响应：

events 中的每个对象都包含 application_type：Grok Bot 为 grok_bot，其他 Cherri Code 界面为 cursor；当无法确定应用时为空字符串 (包括在该字段存在之前写入的记录) 。

例程记录通过 event_data.sand_agent_id 标识 Bot。

{  "events": [    {      "event_id": "evt_abc123",      "timestamp": "2024-01-15T12:30:00.000Z",      "ip_address": "203.0.113.42",      "user_email": "[email protected]",      "event_type": "add_user",      "application_type": "cursor",      "event_data": {        "email": "[email protected]",        "method": "manual"      }    },    {      "event_id": "evt_def456",      "timestamp": "2024-01-15T10:15:00.000Z",      "ip_address": "192.168.1.1",      "user_email": "[email protected]",      "event_type": "login",      "application_type": "grok_bot",      "event_data": {        "ip_address": "192.168.1.1",        "user_agent": "Cherri Code/0.42.0"      }    }  ],  "pagination": {    "page": 1,    "pageSize": 100,    "totalCount": 2,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  },  "params": {    "teamId": 12345,    "startDate": 1704729600000,    "endDate": 1705334400000  }}

获取每日使用情况数据

POST/teams/daily-usage-data

获取团队的每日用量指标。数据按小时汇总，建议对此端点每小时最多轮询一次。每个团队每分钟最多可发送 20 个请求。请参阅最佳实践。

参数

startDate 数值 必填

开始日期 (自纪元起的毫秒数)

endDate number 必填

结束日期 (Unix 纪元毫秒数)

page number

页码 (从 1 开始) 。与 pageSize 同时提供时，将启用分页，并返回在所请求日期范围内具有成员资格的所有团队成员的数据。

pageSize number

每页用户数。与 page 一同提供时，将启用分页，并返回在所请求日期范围内具有成员资格的所有团队成员的数据。

响应字段

data 数组中的每个对象包含：

  • userId number - 用户的唯一标识符
  • day string - 此记录所涵盖的日期 (ISO 日期，例如 2024-03-18)
  • date number - 以纪元毫秒为单位的日期
  • email string - 用户的电子邮件地址
  • isActive 布尔值 - 用户当天是否有活动 (仅在分页时提供)
  • totalLinesAdded number - 新增代码行总数
  • totalLinesDeleted number - 删除的代码行总数
  • acceptedLinesAdded number - 已接受的 AI 建议新增行数
  • acceptedLinesDeleted number - 已接受的 AI 建议删除行数
  • totalApplies number - 应用 AI 代码的操作总数
  • totalAccepts number - 已接受的 AI 建议总数
  • totalRejects number - 被拒绝的 AI 建议总数
  • totalTabsShown number - 向用户展示的 Tab 补全总数
  • totalTabsAccepted number - 用户接受的 Tab 补全数量
  • composerRequests number - 发起的 Composer 请求数
  • chatRequests number - 发起的 chat 请求数量
  • agentRequests number - 发起的 Agent 模式请求数
  • cmdkUsages number - Cmd+K 内联编辑的使用次数
  • subscriptionIncludedReqs number - 订阅方案包含的请求数
  • apiKeyReqs number - 通过 API 密钥发起的请求数
  • usageBasedReqs number - 按用量计费的 (超额) 请求数
  • bugbotUsages number - Bugbot 使用次数
  • mostUsedModel string | null - 当天使用频率最高的 AI 模型
  • applyMostUsedExtension string | null - 应用操作最常用的文件扩展名
  • tabMostUsedExtension string | null - Tab 补全最常用的文件扩展名
  • clientVersion string | null - 所使用的 Cherri Code 客户端版本
# 仅获取活跃用户的数据（不分页）curl -X POST https://api.cursor.com/teams/daily-usage-data \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "startDate": 1710720000000,    "endDate": 1710892800000  }'# 获取所有团队成员的数据（分页）curl -X POST https://api.cursor.com/teams/daily-usage-data \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "startDate": 1710720000000,    "endDate": 1710892800000,    "page": 1,    "pageSize": 1000  }'

响应 (不分页，仅限活跃用户) ：

{  "data": [    {      "userId": 12345,      "day": "2024-03-18",      "date": 1710720000000,      "isActive": true,      "totalLinesAdded": 1543,      "totalLinesDeleted": 892,      "acceptedLinesAdded": 1102,      "acceptedLinesDeleted": 645,      "totalApplies": 87,      "totalAccepts": 73,      "totalRejects": 14,      "totalTabsShown": 342,      "totalTabsAccepted": 289,      "composerRequests": 45,      "chatRequests": 128,      "agentRequests": 12,      "cmdkUsages": 67,      "subscriptionIncludedReqs": 180,      "apiKeyReqs": 0,      "usageBasedReqs": 5,      "bugbotUsages": 3,      "mostUsedModel": "gpt-5",      "applyMostUsedExtension": ".tsx",      "tabMostUsedExtension": ".ts",      "clientVersion": "0.25.1",      "email": "[email protected]"    }  ],  "period": {    "startDate": 1710720000000,    "endDate": 1710892800000  }}

响应 (含分页——所有团队成员) ：

{  "data": [    {      "userId": 12345,      "day": "2024-03-18",      "date": 1710720000000,      "isActive": true,      "totalLinesAdded": 1543,      "totalLinesDeleted": 892,      "acceptedLinesAdded": 1102,      "acceptedLinesDeleted": 645,      "totalApplies": 87,      "totalAccepts": 73,      "totalRejects": 14,      "totalTabsShown": 342,      "totalTabsAccepted": 289,      "composerRequests": 45,      "chatRequests": 128,      "agentRequests": 12,      "cmdkUsages": 67,      "subscriptionIncludedReqs": 180,      "apiKeyReqs": 0,      "usageBasedReqs": 5,      "bugbotUsages": 3,      "mostUsedModel": "gpt-5",      "applyMostUsedExtension": ".tsx",      "tabMostUsedExtension": ".ts",      "clientVersion": "0.25.1",      "email": "[email protected]"    },    {      "userId": 12346,      "day": "2024-03-18",      "date": 1710720000000,      "isActive": false,      "totalLinesAdded": 0,      "totalLinesDeleted": 0,      "acceptedLinesAdded": 0,      "acceptedLinesDeleted": 0,      "totalApplies": 0,      "totalAccepts": 0,      "totalRejects": 0,      "totalTabsShown": 0,      "totalTabsAccepted": 0,      "composerRequests": 0,      "chatRequests": 0,      "agentRequests": 0,      "cmdkUsages": 0,      "subscriptionIncludedReqs": 0,      "apiKeyReqs": 0,      "usageBasedReqs": 0,      "bugbotUsages": 0,      "mostUsedModel": null,      "applyMostUsedExtension": null,      "tabMostUsedExtension": null,      "clientVersion": null,      "email": "[email protected]"    }  ],  "period": {    "startDate": 1710720000000,    "endDate": 1710892800000  },  "pagination": {    "page": 1,    "pageSize": 1000,    "totalUsers": 150,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

获取支出数据

POST/teams/spend

获取当前计费周期的支出数据，支持搜索、排序和分页。

参数

searchTerm string

在用户姓名和邮箱地址中搜索

sortBy string

排序字段：amount、date、user。默认值：date

sortDirection string

排序方向：asc、desc。默认值：desc

page number

页码 (从 1 开始) 。默认值：1

pageSize number

每页返回的结果数量

响应字段

teamMemberSpend 中的每个对象包含：

  • userId string - 编码后的用户 ID (例如：user_PDSPmvukpYgZEDXsoNirw3CFhy) 。与 /teams/members 中的 teamMembers[].id 使用相同的标识符命名空间。
  • name string - 用户显示名称
  • email string - 用户邮箱地址
  • role string - 在团队中的角色 (例如：member、owner)
  • spendCents number - 当前计费周期内按需支出金额 (单位：美分)，不包括包含的用量
  • overallSpendCents number - 当前计费周期内的总支出金额 (单位：美分)，包括按需用量和包含的用量
  • fastPremiumRequests number - 该计费周期内按用量计费的高级请求次数
  • hardLimitOverrideDollars number - 为该用户设置的自定义硬性支出上限覆盖值 (单位：美元，0 表示不覆盖)
  • monthlyLimitDollars number | null - 为该用户设置的每月支出上限 (单位：美元)，若未设置上限则为 null
  • effectivePerUserLimitDollars number - 当前生效的按用户支出上限 (单位：美元)，由 monthlyLimitDollars 和 hardLimitOverrideDollars 推导得出
curl -X POST https://api.cursor.com/teams/spend \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "searchTerm": "[email protected]",    "page": 2,    "pageSize": 25  }'

响应：

{  "teamMemberSpend": [    {      "userId": "user_PDSPmvukpYgZEDXsoNirw3CFhy",      "spendCents": 2450.125487,      "overallSpendCents": 2450.125487,      "fastPremiumRequests": 1250,      "name": "Alex",      "email": "[email protected]",      "role": "member",      "hardLimitOverrideDollars": 100,      "monthlyLimitDollars": 200,      "effectivePerUserLimitDollars": 100    },    {      "userId": "user_kljUvI0ASZORvSEXf9hV0ydcso",      "spendCents": 1875.500123,      "overallSpendCents": 3200.750456,      "fastPremiumRequests": 980,      "name": "Sam",      "email": "[email protected]",      "role": "owner",      "hardLimitOverrideDollars": 0,      "monthlyLimitDollars": null,      "effectivePerUserLimitDollars": 50    }  ],  "subscriptionCycleStart": 1708992000000,  "totalMembers": 15,  "totalPages": 1}

获取使用事件数据

POST/teams/filtered-usage-events

为你的团队检索带有筛选、搜索和分页选项的详细使用事件。此端点可提供对 API 调用、模型使用、令牌消耗和费用的细致洞察。数据按小时汇总。我们建议最多每小时轮询此端点一次。每个团队的速率限制为每分钟 60 次请求。参见 API 指南。

参数

startDate number

起始时间 (纪元毫秒) 。此边界为包含边界。

endDate number

结束时间 (epoch 毫秒) 。此界限包含在内。

userId number

按指定用户 ID 筛选

page number

页码 (从 1 开始) 。默认：1

pageSize number

每页结果数量。默认：100。最大值：1000。

email string

按用户邮箱地址筛选

serviceAccountId string

按服务账户 ID 过滤

cloudAgentId string

按指定的云代理运行 ID 过滤。传入 * 可返回来自所有云代理运行的事件。

automationId string

按指定自动化 UUID 过滤。传入 * 可返回所有自动化的事件。

hostingType string

按执行地点筛选云端代理 (后台代理) 的运行。使用此选项可将自托管代理的推理开支与 Cherri Code 托管的运行区分开来。可接受的值：
  • CLOUD - Cherri Code 托管的运行
  • SELF_HOSTED - 任何自托管运行 (Team Pool worker 或我的机器 worker)
  • SELF_HOSTED_POOL - 仅限 Team Pool worker
  • SELF_HOSTED_MACHINE - 仅限个人 "My Machine" worker

响应字段

usageEvents 中的每个对象包含：

  • timestamp string - 事件时间戳 (epoch 毫秒，以字符串形式表示)
  • userEmail string - 发出该请求的用户邮箱地址
  • serviceAccountId string | undefined - 发出该请求的服务账户 ID。对于由人工用户发起的事件，此字段会被省略。
  • serviceAccountName string | undefined - 发出该请求的服务账户显示名称。人工用户事件中会省略此字段。
  • cloudAgentId string | undefined - 与此事件关联的云端代理运行 ID。对于云端代理之外的事件，会省略此字段。
  • automationId string | undefined - 与此事件关联的自动化 UUID。自动化之外的事件中会省略此字段。
  • conversationId string | undefined - 生成此事件的对话 (智能体会话) ID。可用它将费用归因于某个会话，或作为与其他提供对话 ID 的来源 (如 AI Code Tracking API) 进行关联的键。未关联对话的事件会省略此字段。
  • model string - 用于该请求的 AI 模型
  • kind string - 计费类别 (例如 Usage-based、Included in Business)
  • maxMode boolean - 请求是否使用 Max 模式
  • requestsCosts number - 按请求单位计算的成本
  • isTokenBasedCall boolean - 请求是否按 token 用量计费
  • isChargeable boolean - 此事件是否计费
  • isHeadless boolean - 此请求是否在没有连接客户端的情况下发出 (例如后台 Agent)
  • tokenUsage object | undefined - Token 使用明细 (当 isTokenBasedCall 为 true 时存在) ：
    • inputTokens number - 消耗的输入 token 数
    • outputTokens number - 生成的输出 token 数
    • cacheWriteTokens number - 写入缓存的 token 数
    • cacheReadTokens number - 从缓存读取的 token 数
    • totalCents number - 模型总费用 (美分)
    • discountPercentOff number | undefined - 已应用的折扣百分比 (如有)
  • chargedCents number - 此事件实际收取的总金额 (单位：美分)。对于适用 Cherri Code Token 费率的第三方模型请求，此金额包含模型费用以及 Cherri Code Token 费率。使用此字段可将事件级成本与 /teams/spend 总计对齐。适用于按 token 和按请求计费的方案。
  • cursorTokenFee number | undefined - Cherri Code Token 费率 (单位：美分)。仅当该费率适用于第三方模型请求时出现 (包括 Auto 路由到第三方模型时) 。
curl -X POST https://api.cursor.com/teams/filtered-usage-events \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "startDate": 1748411762359,    "endDate": 1751003762359,    "email": "[email protected]",    "page": 1,    "pageSize": 25  }'

响应：

{  "totalUsageEventsCount": 113,  "pagination": {    "numPages": 5,    "currentPage": 1,    "pageSize": 25,    "hasNextPage": true,    "hasPreviousPage": false  },  "usageEvents": [    {      "timestamp": "1750979225854",      "userEmail": "[email protected]",      "conversationId": "8f2e4a1b-6c3d-4e5f-9a7b-2d1c8e6f4a3b",      "model": "claude-4.5-sonnet",      "kind": "Usage-based",      "maxMode": true,      "requestsCosts": 5,      "isTokenBasedCall": true,      "isChargeable": true,      "isHeadless": false,      "tokenUsage": {        "inputTokens": 126,        "outputTokens": 450,        "cacheWriteTokens": 6112,        "cacheReadTokens": 11964,        "totalCents": 20.18232      },      "chargedCents": 21.36232,      "cursorTokenFee": 1.18    },    {      "timestamp": "1750979173824",      "userEmail": "[email protected]",      "conversationId": "8f2e4a1b-6c3d-4e5f-9a7b-2d1c8e6f4a3b",      "model": "claude-4.5-sonnet",      "kind": "Usage-based",      "maxMode": true,      "requestsCosts": 10,      "isTokenBasedCall": true,      "isChargeable": true,      "isHeadless": false,      "tokenUsage": {        "inputTokens": 5805,        "outputTokens": 311,        "cacheWriteTokens": 11964,        "cacheReadTokens": 0,        "totalCents": 40.167,        "discountPercentOff": 10      },      "chargedCents": 37.33,      "cursorTokenFee": 1.18    },    {      "timestamp": "1750978339901",      "userEmail": "[email protected]",      "model": "claude-4-sonnet-thinking",      "kind": "Included in Business",      "maxMode": true,      "requestsCosts": 1.4,      "isTokenBasedCall": false,      "isChargeable": false,      "isHeadless": false,      "chargedCents": 8    }  ],  "period": {    "startDate": 1748411762359,    "endDate": 1751003762359  }}

服务账户使用示例：

curl -X POST https://api.cursor.com/teams/filtered-usage-events \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "startDate": 1748411762359,    "endDate": 1751003762359,    "serviceAccountId": "sa_abc123",    "page": 1,    "pageSize": 10  }'

服务账户响应：

{  "totalUsageEventsCount": 1,  "pagination": {    "numPages": 1,    "currentPage": 1,    "pageSize": 10,    "hasNextPage": false,    "hasPreviousPage": false  },  "usageEvents": [    {      "timestamp": "1750979225854",      "userEmail": "[email protected]",      "serviceAccountId": "sa_abc123",      "serviceAccountName": "Nightly CI Agent",      "conversationId": "3b9d7c2e-1f4a-4b8c-a6d5-e9f0a2b4c6d8",      "model": "claude-4.5-sonnet",      "kind": "Usage-based",      "maxMode": true,      "requestsCosts": 5,      "isTokenBasedCall": true,      "isChargeable": true,      "isHeadless": true,      "tokenUsage": {        "inputTokens": 126,        "outputTokens": 450,        "cacheWriteTokens": 6112,        "cacheReadTokens": 11964,        "totalCents": 20.18232      },      "chargedCents": 21.36232,      "cursorTokenFee": 1.18    }  ],  "period": {    "startDate": 1748411762359,    "endDate": 1751003762359  }}

自动化使用示例：

使用自动化 UUID 获取其使用事件。自动化归因适用于以用户或服务账户身份运行的自动化。

curl -X POST https://api.cursor.com/teams/filtered-usage-events \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "startDate": 1748411762359,    "endDate": 1751003762359,    "automationId": "7fc64f90-6d7a-4a5d-91b1-bd1f529a85dd",    "page": 1,    "pageSize": 100  }'

每个匹配的事件都包含其 automationId 和 cloudAgentId。对所有事件的 chargedCents 求和，即可计算该自动化的总费用。

自托管代理支出示例：

curl -X POST https://api.cursor.com/teams/filtered-usage-events \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "startDate": 1748411762359,    "endDate": 1751003762359,    "hostingType": "SELF_HOSTED",    "page": 1,    "pageSize": 10  }'

设置用户支出限额

POST/teams/user-spend-limit

为团队中的单个成员设置支出限额。这样可以控制每个用户在团队内 AI 使用产生的费用。每个团队速率限制为每分钟 250 次请求。参见 速率限制。

如需在单次请求中最多更新 100 个成员，请使用 批量设置用户支出限额 (预览版)。

参数

userEmail string 必填

团队成员的电子邮件地址

spendLimitDollars number | null 必填

以美元计的支出限额 (仅允许整数，不含小数) 。设置为 null 可移除该上限。
curl -X POST https://api.cursor.com/teams/user-spend-limit \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userEmail": "[email protected]",    "spendLimitDollars": 100  }'

成功响应：

{  "outcome": "success",  "message": "Spend limit set to $100 for user [email protected]"}

错误响应：

{  "outcome": "error",  "message": "Invalid email format"}

批量设置用户支出限额 (预览版)

POST/teams/user-spend-limits

在单次请求中最多为 100 名团队成员设置支出限额。速率限制为每个团队每分钟 20 次请求。参见速率限制。

参数

updates array 必填

1 至 100 条用户支出限额更新。每条更新包含：
  • userEmail string - 团队成员的电子邮件地址
  • spendLimitDollars number | null - 以美元为单位的整数支出限额。设为 null 可移除限额。

响应字段

  • requestedCount number - 请求中的更新数量
  • updatedCount number - 发生变更的限额数量
  • unchangedCount number - 已与请求值相同的限额数量
  • failedCount number - Cherri Code 未能应用的更新数量
  • results array - 按请求顺序返回的结果。每条结果包含 userEmail 及状态 updated、unchanged 或 failed。失败结果还会包含 error 消息。
curl -X POST https://api.cursor.com/teams/user-spend-limits \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "updates": [      {        "userEmail": "[email protected]",        "spendLimitDollars": 100      },      {        "userEmail": "[email protected]",        "spendLimitDollars": null      },      {        "userEmail": "[email protected]",        "spendLimitDollars": 50      }    ]  }'

响应：

{  "requestedCount": 3,  "updatedCount": 1,  "unchangedCount": 1,  "failedCount": 1,  "results": [    {      "userEmail": "[email protected]",      "status": "updated"    },    {      "userEmail": "[email protected]",      "status": "unchanged"    },    {      "userEmail": "[email protected]",      "status": "failed",      "error": "User not found in team"    }  ]}

移除团队成员

POST/teams/remove-member

以编程方式从团队中移除成员。适用于自动化离职流程或与 HR 系统集成。每个团队的速率限制为每分钟 50 次。参见 速率限制。

参数

userId string

编码的用户 ID (例如：user_PDSPmvukpYgZEDXsoNirw3CFhy) 。当未提供 email 时必填。

email string

团队成员的邮箱地址。当未提供 userId 时必填。
curl -X POST https://api.cursor.com/teams/remove-member \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "email": "[email protected]"  }'

响应：

{  "success": true,  "userId": "user_PDSPmvukpYgZEDXsoNirw3CFhy",  "hasBillingCycleUsage": true}

通过 user ID 移除：

curl -X POST https://api.cursor.com/teams/remove-member \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userId": "user_PDSPmvukpYgZEDXsoNirw3CFhy"  }'

错误响应：

{  "error": "User is not a member of this team"}
{  "error": "Either userId or email must be provided"}
{  "error": "Only one of userId or email should be provided, not both"}

获取团队代码仓库屏蔽列表

GET/settings/repo-blocklists/repos

获取为团队配置的所有代码仓库屏蔽列表。添加仓库并使用模式，防止文件或目录被索引或用作上下文。

模式示例

常见的屏蔽列表模式：

  • * - 屏蔽整个仓库
  • *.env - 屏蔽所有 .env 文件
  • config/* - 屏蔽 config 目录中的所有文件
  • **/*.secret - 屏蔽任何子目录中的所有 .secret 文件
  • src/api/keys.ts - 屏蔽特定文件
curl -X GET https://api.cursor.com/settings/repo-blocklists/repos \  -u YOUR_API_KEY:

响应：

{  "repos": [    {      "id": "repo_123",      "url": "https://github.com/company/sensitive-repo",      "patterns": ["*.env", "config/*", "secrets/**"]    },    {      "id": "repo_456",      "url": "https://github.com/company/internal-tools",      "patterns": ["*"]    }  ]}

新增或更新代码仓库屏蔽列表

POST/settings/repo-blocklists/repos/upsert

替换指定代码仓库现有的屏蔽列表。此端点只会覆盖所提供代码仓库的匹配模式，其他仓库不会受到影响。

参数

repos array 必填

代码仓库屏蔽列表对象数组。每个代码仓库对象必须包含：

  • url string - 要加入屏蔽列表的代码仓库 URL
  • patterns string[] - 要屏蔽的文件模式数组 (支持 glob 模式)
curl -X POST https://api.cursor.com/settings/repo-blocklists/repos/upsert \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "repos": [      {        "url": "https://github.com/company/sensitive-repo",        "patterns": ["*.env", "config/*", "secrets/**"]      },      {        "url": "https://github.com/company/internal-tools",        "patterns": ["*"]      }    ]  }'

响应：

{  "repos": [    {      "id": "repo_123",      "url": "https://github.com/company/sensitive-repo",      "patterns": ["*.env", "config/*", "secrets/**"]    },    {      "id": "repo_456",      "url": "https://github.com/company/internal-tools",      "patterns": ["*"]    }  ]}

删除代码仓库屏蔽列表

DELETE/settings/repo-blocklists/repos/:repoId

从屏蔽列表中移除指定代码仓库。删除成功时返回 204 No Content。

参数

repoId string 必填

要删除的代码仓库屏蔽列表 ID
curl -X DELETE https://api.cursor.com/settings/repo-blocklists/repos/repo_123 \  -u YOUR_API_KEY:

响应：

204 No Content

团队目录组

Team Admin API 在 /teams/directory-groups 下的路由 用于管理团队目录组。这些群组在单个团队内设置支出和策略。关于它们与组织级群体的区别，参见 组织群组，以及 账单组。

当某个组织群组应当驱动该团队的成员关系时，请将群组映射到团队。可使用 Team API 密钥 创建、列出团队目录组以及添加或移除其成员。仪表盘和 SCIM 的设置方法参见目录组。

这些路由 与账单组分属不同的 API。请参照下表选择正确的路径和 id：

群组路径ID
组织群组/organizations/groupsid 使用 g_ 前缀。响应中还会返回带 grp_ 前缀的 publicId。参见组织群组。
团队目录组/teams/directory-groupspublic id 使用 team_group_… 前缀，例如 team_group_01k2ja2000e0080000000000n2。
账单组/teams/groupsgroup_…

:groupId 是该团队目录组的 public id，使用 team_group_… 前缀。请勿传入组织群组的 g_ 或 grp_ id，也不要传入账单组的 group_… id。

群组路由 共用以下错误响应：

状态码场景
400群组 ID、分页值或请求体格式不正确
401API 密钥无效，或密钥缺少 read:* (读取) 或 admin:* (写入) 权限范围
404该群组在此团队中不存在
429超出速率限制，响应中包含 Retry-After: 60 头

列出团队目录组

GET/teams/directory-groups

获取 API 密钥所属团队的团队目录组。

查询参数

page number

页码。默认为 1。

pageSize number

每页返回的群组数量。默认为 50。上限为 200；超过 200 的值会被截断为 200。

响应字段

groups 中的每个对象包含：

  • id string - 带有 team_group_… 前缀的群组 public id。在其他路由中将此值用作 :groupId。
  • name string - 群组名称
  • memberCount number - 群组中的成员数量
  • monthlySpendingLimitDollars number | null - 每位群组成员的支出限额，以整美元为单位。null 表示该群组无限额。
  • createdAt string - 创建时间，ISO 8601 格式
  • updatedAt string - 最后更新时间，ISO 8601 格式

pagination object

分页元数据：page、pageSize、totalCount、totalPages、hasNextPage 和 hasPreviousPage。
curl -X GET "https://api.cursor.com/teams/directory-groups?page=1&pageSize=50" \  -u YOUR_API_KEY:

响应：

{  "groups": [    {      "id": "team_group_01k2ja2000e0080000000000n2",      "name": "Engineering",      "memberCount": 12,      "monthlySpendingLimitDollars": 500,      "createdAt": "2026-01-15T10:30:00.000Z",      "updatedAt": "2026-01-20T14:22:00.000Z"    },    {      "id": "team_group_01k2jb4000e0080000000000p7",      "name": "Design",      "memberCount": 8,      "monthlySpendingLimitDollars": null,      "createdAt": "2026-01-16T09:00:00.000Z",      "updatedAt": "2026-01-16T09:00:00.000Z"    }  ],  "pagination": {    "page": 1,    "pageSize": 50,    "totalCount": 2,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

获取团队目录组

GET/teams/directory-groups/:groupId

获取某个团队目录组。

参数

groupId string 必填

群组的 public id，带 team_group_… 前缀，例如 team_group_01k2ja2000e0080000000000n2。组织群组的 g_ 或 grp_ id 以及账单组的 group_… id 会返回 400 或 404。

响应字段

group 对象包含 id、name、memberCount、monthlySpendingLimitDollars、createdAt 和 updatedAt。这些字段与 列出团队目录组 的响应一致。

curl -X GET https://api.cursor.com/teams/directory-groups/team_group_01k2ja2000e0080000000000n2 \  -u YOUR_API_KEY:

响应：

{  "group": {    "id": "team_group_01k2ja2000e0080000000000n2",    "name": "Engineering",    "memberCount": 12,    "monthlySpendingLimitDollars": 500,    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-20T14:22:00.000Z"  }}

创建团队目录组

POST/teams/directory-groups

创建一个成员手动管理的团队目录组。如需创建 SCIM 同步的群组，请改为从身份提供商同步。参见 SCIM。

请求体

name string 必填

群组名称。在团队的活跃目录组中必须唯一。Cherri Code 会去除首尾空白字符。

响应字段

返回 201 Created 及新建的 group 对象。该对象包含 id、name、memberCount、monthlySpendingLimitDollars、createdAt 和 updatedAt。其中 id 为该群组的 public id，带 team_group_… 前缀。

错误

  • 400 - 群组名称缺失、为空，或已被另一个活跃群组占用。
curl -X POST https://api.cursor.com/teams/directory-groups \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "name": "Engineering"  }'

响应：

{  "group": {    "id": "team_group_01k2ja2000e0080000000000n2",    "name": "Engineering",    "memberCount": 0,    "monthlySpendingLimitDollars": null,    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-15T10:30:00.000Z"  }}

更新团队目录组

PATCH/teams/directory-groups/:groupId

更新群组的名称或支出限额。支持部分更新：至少需包含一个字段，未提供的字段保持当前值不变。

参数

groupId string 必填

群组的 public id，带 team_group_… 前缀，例如 team_group_01k2ja2000e0080000000000n2。

请求体

name string

新的群组名称，在团队的活跃目录组中必须唯一。Cherri Code 会移除首尾空白字符。

monthlySpendingLimitDollars number

每位群组成员的支出限额，以整数美元计，取值范围为 0 到 2147483647。

clearMonthlySpendingLimitDollars boolean

设为 true 可移除群组支出限额。请勿在同一请求中包含 monthlySpendingLimitDollars。

响应字段

返回更新后的 group 对象，包含 id、name、memberCount、monthlySpendingLimitDollars、createdAt 和 updatedAt。

错误

  • 400 - 请求未包含任何更新字段、包含无效值、使用了另一个活跃群组的名称，或在同一请求中同时设置和清除支出限额。
curl -X PATCH https://api.cursor.com/teams/directory-groups/team_group_01k2ja2000e0080000000000n2 \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "name": "Platform Engineering",    "monthlySpendingLimitDollars": 500  }'

响应：

{  "group": {    "id": "team_group_01k2ja2000e0080000000000n2",    "name": "Platform Engineering",    "memberCount": 12,    "monthlySpendingLimitDollars": 500,    "createdAt": "2026-01-15T10:30:00.000Z",    "updatedAt": "2026-01-20T14:22:00.000Z"  }}

删除团队目录组

DELETE/teams/directory-groups/:groupId

删除团队目录组。该组必须为空：删除前请先移除全部成员。

参数

groupId string 必填

群组的 public id，带 team_group_… 前缀，例如 team_group_01k2ja2000e0080000000000n2。

响应

删除群组后返回 204 No Content。

错误

  • 400 - 群组中仍有成员，或群组存在启用中的 SCIM 映射。
curl -X DELETE https://api.cursor.com/teams/directory-groups/team_group_01k2ja2000e0080000000000n2 \  -u YOUR_API_KEY:

响应： 204 No Content

列出团队目录组成员

GET/teams/directory-groups/:groupId/members

获取团队目录组中的成员。

参数

groupId string 必填

群组的 public id，带 team_group_… 前缀，例如 team_group_01k2ja2000e0080000000000n2。

查询参数

page number

页码。默认为 1。

pageSize number

每页成员数量。默认为 50。上限为 200；超过 200 的值会被截断为 200。

响应字段

members 中的每个对象包含：

  • userId string - 公开用户 ID，带 user_ 前缀
  • name string - 成员的显示名称
  • email string - 成员的电子邮件地址
  • joinedAt string - 成员加入群组的时间，采用 ISO 8601 格式

pagination object

分页元数据：page、pageSize、totalCount、totalPages、hasNextPage 和 hasPreviousPage。
curl -X GET "https://api.cursor.com/teams/directory-groups/team_group_01k2ja2000e0080000000000n2/members?page=1&pageSize=50" \  -u YOUR_API_KEY:

响应：

{  "members": [    {      "userId": "user_abc123",      "name": "Alex Developer",      "email": "[email protected]",      "joinedAt": "2026-01-15T10:30:00.000Z"    },    {      "userId": "user_def456",      "name": "Sam Engineer",      "email": "[email protected]",      "joinedAt": "2026-01-16T09:15:00.000Z"    }  ],  "pagination": {    "page": 1,    "pageSize": 50,    "totalCount": 2,    "totalPages": 1,    "hasNextPage": false,    "hasPreviousPage": false  }}

添加团队目录组成员

POST/teams/directory-groups/:groupId/members/bulk-add

向手动管理的团队目录组添加成员。

参数

groupId string 必填

群组的 public id，带 team_group_… 前缀，例如 team_group_01k2ja2000e0080000000000n2。

请求体

userIds string[] 必填

公开用户 ID 数组，带 user_ 前缀。单次请求最多可包含 100 个用户。

响应字段

addedCount number

本次请求新建的成员关系数量。Cherri Code 会忽略团队之外的用户以及已在该群组中的用户，这些用户不计入总数。
curl -X POST https://api.cursor.com/teams/directory-groups/team_group_01k2ja2000e0080000000000n2/members/bulk-add \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userIds": ["user_abc123", "user_def456"]  }'

响应：

{  "addedCount": 2}

移除团队目录组成员

POST/teams/directory-groups/:groupId/members/bulk-remove

从手动管理的团队目录组中移除成员。

参数

groupId string 必填

群组的 public id，带 team_group_… 前缀，例如 team_group_01k2ja2000e0080000000000n2。

请求体

userIds string[] 必填

公开用户 ID 数组，带 user_ 前缀。单次请求最多可包含 100 个用户。

响应字段

removedCount number

本次请求移除的成员关系数量。Cherri Code 会忽略不在该群组中的用户，这些用户不计入总数。
curl -X POST https://api.cursor.com/teams/directory-groups/team_group_01k2ja2000e0080000000000n2/members/bulk-remove \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userIds": ["user_def456"]  }'

响应：

{  "removedCount": 1}

账单组

账单组 允许 Enterprise 管理员按用户分组了解和管理支出。此功能适用于报表、内部费用分摊和预算管理。

成员在同一时间只能属于一个账单组。未分配到任何分组的成员会被放入预留的 Unassigned 分组中。

列出分组

GET/teams/groups

获取团队中所有账单组，以及当前计费周期的支出数据。

参数

billingCycle string

ISO 日期字符串 (例如 2025-01-15) ，用于指定要查询的计费周期。默认为当前周期。
curl -X GET "https://api.cursor.com/teams/groups?billingCycle=2025-01-15" \  -u YOUR_API_KEY:

响应：

{  "groups": [    {      "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",      "name": "Engineering",      "type": "BILLING",      "directoryGroupId": null,      "memberCount": 12,      "createdAt": "2024-01-15T10:30:00.000Z",      "updatedAt": "2024-01-20T14:22:00.000Z",      "spendCents": 245000,      "currentMembers": [        {          "userId": "user_abc123",          "name": "Alex Developer",          "email": "[email protected]",          "joinedAt": "2024-01-15T10:30:00.000Z",          "leftAt": null,          "spendCents": 12500        }      ],      "formerMembers": [],      "dailySpend": [        { "date": "2025-01-15", "spendCents": 8500 },        { "date": "2025-01-16", "spendCents": 9200 }      ]    },    {      "id": "group_kljUvI0ASZORvSEXf9hV0ydcso",      "name": "Design",      "type": "BILLING",      "directoryGroupId": "dir_group_abc123xyz",      "memberCount": 5,      "createdAt": "2024-01-16T09:00:00.000Z",      "updatedAt": "2024-01-16T09:00:00.000Z",      "spendCents": 87500,      "currentMembers": [],      "formerMembers": [],      "dailySpend": []    }  ],  "unassignedGroup": {    "id": "group_unassigned",    "name": "Unassigned",    "type": "BILLING",    "directoryGroupId": null,    "memberCount": 3,    "createdAt": "2024-01-01T00:00:00.000Z",    "updatedAt": "2024-01-01T00:00:00.000Z",    "spendCents": 15000,    "currentMembers": [],    "formerMembers": [],    "dailySpend": []  },  "billingCycle": {    "cycleStart": "2025-01-01T00:00:00.000Z",    "cycleEnd": "2025-02-01T00:00:00.000Z"  }}

获取分组

GET/teams/groups/:groupId

获取单个计费分组，以及其成员和当前计费周期的消费数据。

参数

groupId string 必填

编码后的分组 ID (例如 group_PDSPmvukpYgZEDXsoNirw3CFhy)

billingCycle string

ISO 日期字符串 (例如 2025-01-15) ，用于指定要查询的计费周期。默认为当前周期。
curl -X GET "https://api.cursor.com/teams/groups/group_PDSPmvukpYgZEDXsoNirw3CFhy?billingCycle=2025-01-15" \  -u YOUR_API_KEY:

响应：

{  "group": {    "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Engineering",    "type": "BILLING",    "directoryGroupId": null,    "memberCount": 3,    "createdAt": "2024-01-15T10:30:00.000Z",    "updatedAt": "2024-01-20T14:22:00.000Z",    "spendCents": 125000,    "currentMembers": [      {        "userId": "user_abc123",        "name": "Alex Developer",        "email": "[email protected]",        "joinedAt": "2024-01-15T10:30:00.000Z",        "leftAt": null,        "spendCents": 75000,        "dailySpend": [          { "date": "2025-01-15", "spendCents": 5000 },          { "date": "2025-01-16", "spendCents": 7500 }        ]      },      {        "userId": "user_def456",        "name": "Sam Engineer",        "email": "[email protected]",        "joinedAt": "2024-01-16T09:15:00.000Z",        "leftAt": null,        "spendCents": 50000,        "dailySpend": [          { "date": "2025-01-15", "spendCents": 3500 },          { "date": "2025-01-16", "spendCents": 4200 }        ]      }    ],    "formerMembers": [      {        "userId": "user_xyz789",        "name": "Former Member",        "email": "[email protected]",        "joinedAt": "2024-01-10T08:00:00.000Z",        "leftAt": "2024-01-14T17:00:00.000Z",        "spendCents": 0      }    ],    "dailySpend": [      { "date": "2025-01-15", "spendCents": 8500 },      { "date": "2025-01-16", "spendCents": 11700 }    ]  },  "billingCycle": {    "cycleStart": "2025-01-01T00:00:00.000Z",    "cycleEnd": "2025-02-01T00:00:00.000Z"  }}

创建分组

POST/teams/groups

创建一个新的计费分组。每个团队每分钟最多 20 个请求。

参数

name string 必填

分组名称

type string

分组类型。目前仅支持 BILLING。默认值：BILLING
curl -X POST https://api.cursor.com/teams/groups \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "name": "Engineering"  }'

响应：

{  "group": {    "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Engineering",    "type": "BILLING",    "directoryGroupId": null,    "memberCount": 0,    "createdAt": "2024-01-15T10:30:00.000Z",    "updatedAt": "2024-01-15T10:30:00.000Z",    "members": []  }}

更新分组

PATCH/teams/groups/:groupId

更新计费分组的名称或目录分组关联。每个团队每分钟最多 20 个请求。

参数

groupId string 必填

编码后的分组 ID

name string

分组的新名称

directoryGroupId string | null

要同步的目录分组 ID，或设为 null 以取消目录同步
curl -X PATCH https://api.cursor.com/teams/groups/group_PDSPmvukpYgZEDXsoNirw3CFhy \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "name": "Platform Engineering"  }'

响应：

{  "group": {    "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Platform Engineering",    "type": "BILLING",    "directoryGroupId": null,    "memberCount": 3,    "createdAt": "2024-01-15T10:30:00.000Z",    "updatedAt": "2024-01-25T16:45:00.000Z",    "members": [      {        "userId": "user_abc123",        "name": "Alex Developer",        "email": "[email protected]",        "joinedAt": "2024-01-15T10:30:00.000Z"      }    ]  }}

删除分组

DELETE/teams/groups/:groupId

删除一个计费分组。成功时返回 204 No Content。每个团队每分钟最多 20 个请求。

参数

groupId string 必填

要删除的编码后的分组 ID
curl -X DELETE https://api.cursor.com/teams/groups/group_PDSPmvukpYgZEDXsoNirw3CFhy \  -u YOUR_API_KEY:

响应：

204 No Content

向分组添加成员

POST/teams/groups/:groupId/members

向计费分组添加团队成员。用户必须已是你团队的成员，且当前未分配到其他分组。每个团队每分钟最多 20 个请求。

参数

groupId string 必填

编码后的分组 ID

userIds string[] 必填

要添加的编码后用户 ID 数组 (例如 ["user_abc123", "user_def456"]) 
curl -X POST https://api.cursor.com/teams/groups/group_PDSPmvukpYgZEDXsoNirw3CFhy/members \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userIds": ["user_abc123", "user_def456"]  }'

响应：

{  "group": {    "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Engineering",    "type": "BILLING",    "directoryGroupId": null,    "memberCount": 2,    "createdAt": "2024-01-15T10:30:00.000Z",    "updatedAt": "2024-01-25T16:50:00.000Z",    "members": [      {        "userId": "user_abc123",        "name": "Alex Developer",        "email": "[email protected]",        "joinedAt": "2024-01-25T16:50:00.000Z"      },      {        "userId": "user_def456",        "name": "Sam Engineer",        "email": "[email protected]",        "joinedAt": "2024-01-25T16:50:00.000Z"      }    ]  }}

从分组中移除成员

DELETE/teams/groups/:groupId/members

从计费分组中移除团队成员。被移除的成员会移动到 Unassigned 分组。每个团队每分钟最多 20 个请求。

参数

groupId string 必填

编码后的分组 ID

userIds string[] 必填

待移除的编码后用户 ID 数组
curl -X DELETE https://api.cursor.com/teams/groups/group_PDSPmvukpYgZEDXsoNirw3CFhy/members \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "userIds": ["user_def456"]  }'

响应：

{  "group": {    "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Engineering",    "type": "BILLING",    "directoryGroupId": null,    "memberCount": 1,    "createdAt": "2024-01-15T10:30:00.000Z",    "updatedAt": "2024-01-25T17:00:00.000Z",    "members": [      {        "userId": "user_abc123",        "name": "Alex Developer",        "email": "[email protected]",        "joinedAt": "2024-01-25T16:50:00.000Z"      }    ]  }}

模型访问

读取和更新团队的模型访问策略：自定义策略是否已启用、新提供商和模型的默认值、按提供商和每个模型设置的开关，以及每个模型的设置，例如 Fast 和推理工作量。

启用未设置参数的模型时，将保留目录默认值。当这些默认值 (例如 Fast) 不符合团队策略时，请使用每个模型的设置。

这些路由返回团队基线配置。组织群组仍可为部分成员扩大访问权限；群组允许列表不在此 API 的管理范围内。个人 API 密钥 (BYOK) 控制仍需在仪表盘中设置。

如需读取组织范围的设置，或对关联团队进行批量切换，请参阅组织 API 模型访问路由。

获取模型访问配置

GET/teams/model-access/configuration

返回团队是否设置了自定义模型访问策略，以及新发现的提供商和模型的默认值。

响应字段

teamId number

由 API 密钥确定的整数团队 ID。

state string

取值为 unrestricted、custom 或 legacy。

newProviderDefault string | null

当 state 为 custom 时，取值为 enabled 或 disabled；否则为 null。

newModelDefault string | null

当 state 为 custom 时，取值为 enabled 或 disabled；否则为 null。
curl -X GET https://api.cursor.com/teams/model-access/configuration \  -u YOUR_API_KEY:

响应：

{  "teamId": 7,  "state": "unrestricted",  "newProviderDefault": null,  "newModelDefault": null}

更新模型访问配置

PUT/teams/model-access/configuration

创建自定义策略、更新默认值，或将团队恢复为不受限状态。

发送以下任一内容：

  • { "state": "unrestricted" }：清除自定义策略 (以及旧版允许/阻止列表) ，将 state 设为 unrestricted
  • { "newProviderDefault", "newModelDefault" }：创建或更新自定义策略 (state: "custom" 的向后兼容简写)

对于不受限团队，首次发送默认值 PUT 请求会创建自定义策略并初始化目录条目。后续默认值 PUT 请求仅更新默认值，保留现有开关设置。

请求体

state string

可选。使用 unrestricted 清除策略。发送默认值时请省略。

newProviderDefault string

enabled 或 disabled。创建或更新自定义策略时必填；当 state 为 unrestricted 时请省略。

newModelDefault string

enabled 或 disabled。创建或更新自定义策略时必填；当 state 为 unrestricted 时请省略。
curl -X PUT https://api.cursor.com/teams/model-access/configuration \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "newProviderDefault": "disabled",    "newModelDefault": "enabled"  }'

响应：

{  "teamId": 7,  "state": "custom",  "newProviderDefault": "disabled",  "newModelDefault": "enabled"}

将团队恢复为不受限状态：

curl -X PUT https://api.cursor.com/teams/model-access/configuration \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{ "state": "unrestricted" }'

响应：

{  "teamId": 7,  "state": "unrestricted",  "newProviderDefault": null,  "newModelDefault": null}

列出模型访问提供商

GET/teams/model-access/providers

列出目录中的提供商和模型，包括最终解析的启用状态及每个模型的 parameters。如果团队没有自定义策略，则返回 409。

每个模型都包含由目录定义的 parameters 数组。参数 ID 和支持的值来自模型目录 (例如 fast、reasoning、effort、context) 。在写入前，可通过此 GET 请求了解模型支持哪些参数。

模型 parameters 字段

id string

参数 ID (例如 fast 或 reasoning) 。

displayName string

易于理解的显示标签。

supportedValues string[]

目录允许该模型使用此参数的所有值。

allowedValues string[]

团队策略当前允许的值。

configuredDefaultValue string | null

管理员固定的默认值；未设置时为 null。

catalogDefaultValue string | null

该模型中此参数的目录默认值。
curl -X GET https://api.cursor.com/teams/model-access/providers \  -u YOUR_API_KEY:

响应：

{  "teamId": 7,  "state": "custom",  "providers": [    {      "id": "anthropic",      "displayName": "Anthropic",      "enabled": true,      "models": [        {          "id": "claude-opus-4-6",          "displayName": "Opus 4.6",          "enabled": true,          "parameters": [            {              "id": "fast",              "displayName": "Fast",              "supportedValues": ["false", "true"],              "allowedValues": ["false", "true"],              "configuredDefaultValue": null,              "catalogDefaultValue": "true"            }          ]        }      ]    },    {      "id": "openai",      "displayName": "OpenAI",      "enabled": true,      "models": [        {          "id": "gpt-5.4",          "displayName": "GPT-5.4",          "enabled": true,          "parameters": [            {              "id": "reasoning",              "displayName": "Reasoning",              "supportedValues": ["low", "medium", "high", "xhigh", "max"],              "allowedValues": ["low", "medium", "high"],              "configuredDefaultValue": "high",              "catalogDefaultValue": "medium"            }          ]        }      ]    }  ]}

更新模型访问提供商

PUT/teams/model-access/providers/:provider

启用或禁用提供商。如果团队仍为 unrestricted 或 legacy，则返回 409。

参数

provider string 必填

目录中的提供商 ID (例如 openai 或 anthropic) 。

请求体

enabled boolean 必填

curl -X PUT https://api.cursor.com/teams/model-access/providers/openai \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{"enabled": false}'

列出提供商的模型

GET/teams/model-access/providers/:provider/models

列出某个提供商的模型及其最终解析的启用状态和每个模型的 parameters。参数字段与提供商响应一致。如果团队没有自定义策略，则返回 409。

参数

provider string 必填

目录中的提供商 ID (例如 anthropic) 。
curl -X GET https://api.cursor.com/teams/model-access/providers/anthropic/models \  -u YOUR_API_KEY:

更新模型访问模型

PUT/teams/model-access/providers/:provider/models/:model

启用或禁用单个模型，并可选择设置每个模型的参数限制和默认值。团队仍为 unrestricted 或 legacy 时，返回 409。

参数

provider string 必填

目录中的提供商 ID (例如 anthropic) 。

model string 必填

模型目录中的模型 ID (例如 claude-opus-4-6) 。

请求体

enabled boolean 必填

parameters object

可选的从参数 ID 到设置的映射。未提供的参数和字段将保持不变。
  • allowedValues string[] | null: 限制成员可选择的值。传入 null 可清除限制。
  • defaultValue string | null: 团队的默认值。设置限制时，必须包含在 allowedValues 中。传入 null 可恢复目录默认值。

未知的参数 ID 或值、空的 allowedValues 数组、不在 allowedValues 中的默认值，以及解析后没有有效模型变体的设置均返回 400。

在模型上禁用 Fast：

curl -X PUT https://api.cursor.com/teams/model-access/providers/anthropic/models/claude-opus-4-6 \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "parameters": {      "fast": { "allowedValues": ["false"] }    }  }'

设置允许的推理级别和默认值：

curl -X PUT https://api.cursor.com/teams/model-access/providers/openai/models/gpt-5.4 \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "parameters": {      "reasoning": {        "allowedValues": ["low", "medium", "high"],        "defaultValue": "high"      }    }  }'

清除限制并恢复目录默认值：

curl -X PUT https://api.cursor.com/teams/model-access/providers/openai/models/gpt-5.4 \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "parameters": {      "reasoning": {        "allowedValues": null,        "defaultValue": null      }    }  }'

响应：

{  "id": "gpt-5.4",  "displayName": "GPT-5.4",  "enabled": true,  "provider": "openai",  "parameters": [    {      "id": "reasoning",      "displayName": "Reasoning",      "supportedValues": ["low", "medium", "high", "xhigh", "max"],      "allowedValues": ["low", "medium", "high", "xhigh", "max"],      "configuredDefaultValue": null,      "catalogDefaultValue": "medium"    }  ]}

错误

错误响应体使用：

{ "code": "error", "message": "…" }
状态发生情况
401Key 无效，或缺少 models:read / models:* (或 admin:*) 权限
403该团队无法使用模型访问控制
409当 state 为 unrestricted 或 legacy 时读取或写入 提供商 或模型
400提供商、模型、参数 ID 或参数值未知；响应体无效；allowedValues 为空；默认值不在 allowedValues 范围内；会解析为无有效模型变体的设置；或会阻止 Smart Auto 所需的模型

Grok Bot

启用 Grok Bot 并管理能力、Enforce Auto-Review、群组访问权限、网络策略、团队规则和 setup scripts。

启用 Grok Bot

POST/grok-bot/enable

为团队启用 Grok Bot。在符合条件的企业版团队中首次启用时会开启试用。成功时返回 204 No Content。

curl -X POST https://api.cursor.com/grok-bot/enable \  -u YOUR_API_KEY:

响应：

204 No Content

禁用 Grok Bot

POST/grok-bot/disable

为团队禁用 Grok Bot。成员将失去访问权限，但其 computers 不会被删除。在团队版上返回 403。

curl -X POST https://api.cursor.com/grok-bot/disable \  -u YOUR_API_KEY:

响应：

204 No Content

获取 Grok Bot 能力

GET/grok-bot/capabilities

返回团队的 Grok Bot 能力。

响应字段

enabled boolean

是否启用 Grok Bot。只读。

cloudAgents boolean

成员是否可以将工作委派给云端代理。

templateSharing string | null

all、team_only、none，或 null 表示使用团队默认值。

actionRecording boolean

是否启用 Action Recording。

localExecution string | null

机器人在成员本机上执行操作的团队上限：never、ask、always，或 null 表示未设置上限。

localEgressAllowed boolean

成员是否可以将 Grok Bot 的网络流量通过自己的计算机转发 (Allow Local Egress Routing；仅限企业版) 。
curl -X GET https://api.cursor.com/grok-bot/capabilities \  -u YOUR_API_KEY:

响应：

{  "enabled": true,  "cloudAgents": true,  "templateSharing": "team_only",  "actionRecording": false,  "localExecution": "ask",  "localEgressAllowed": true}

更新 Grok Bot 能力

PATCH/grok-bot/capabilities

更新 Grok Bot 能力。省略的字段保持不变。当团队无权使用某个字段时返回 403。

参数

cloudAgents boolean

成员是否可以将工作委派给云端代理。

templateSharing string | null

all、team_only、none，或使用 null 恢复团队默认值。

actionRecording boolean

是否启用 Action Recording。

localExecution string | null

never、ask、always，或使用 null 清除团队上限。

localEgressAllowed boolean

成员是否可以将 Grok Bot 的网络流量通过自己的计算机路由 (Allow Local Egress Routing；仅限企业版) 。当团队未启用本地出站路由控制时返回 403。
curl -X PATCH https://api.cursor.com/grok-bot/capabilities \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "cloudAgents": false,    "localExecution": "never",    "localEgressAllowed": false  }'

响应：

{  "enabled": true,  "cloudAgents": false,  "templateSharing": "team_only",  "actionRecording": false,  "localExecution": "never",  "localEgressAllowed": false}

获取 Enforce Auto-Review

GET/grok-bot/auto-review

返回团队的 Enforce Auto-Review 策略。

响应字段

enforced boolean

为 true 时，所有成员都必须保持 Enforce Auto-Review 开启。

rules object

供自动评审使用的团队 allow 与 block 指令列表。
curl -X GET https://api.cursor.com/grok-bot/auto-review \  -u YOUR_API_KEY:

响应：

{  "enforced": true,  "rules": {    "allow": ["Read-only git commands"],    "block": ["Publishing releases"]  }}

替换 Enforce Auto-review 模式

PUT/grok-bot/auto-review

替换团队的 Enforce Auto-review 模式策略。当团队无法使用 Enforce Auto-review 模式时返回 403。

参数

enforced boolean 必填

为 true 时，每位成员都必须保持开启 Enforce Auto-review 模式。

rules object 必填

允许与阻止的指令列表。
  • allow string[]：最多 20 条指令，每条最多 1,000 个字符。会被去除首尾空白并去重。
  • block string[]：最多 20 条指令，每条最多 1,000 个字符。会被去除首尾空白并去重。
curl -X PUT https://api.cursor.com/grok-bot/auto-review \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enforced": true,    "rules": {      "allow": ["Read-only git commands"],      "block": ["Publishing releases"]    }  }'

在不更改指令的情况下锁定 Enforce Auto-review 模式：

curl -X PUT https://api.cursor.com/grok-bot/auto-review \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enforced": true,    "rules": { "allow": [], "block": [] }  }'

响应：

{  "enforced": true,  "rules": {    "allow": ["Read-only git commands"],    "block": ["Publishing releases"]  }}

获取 Grok Bot 访问权限

GET/grok-bot/access

返回团队中可以使用 Grok Bot 的人员。

响应字段

mode string

all 或 limited。

groups array

当 mode 为 limited 时所选的群组。每一项包含编码后的 id 和 name。当 mode 为 all 时为空。
curl -X GET https://api.cursor.com/grok-bot/access \  -u YOUR_API_KEY:

响应：

{  "mode": "limited",  "groups": [    {      "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",      "name": "Platform Engineering"    }  ]}

更新 Grok Bot 访问权限

PUT/grok-bot/access

设置团队中哪些人可以使用 Grok Bot。团队不具备群组访问权限时返回 403。

参数

mode string 必填

all 表示所有成员，limited 表示选定的账单组。

groupIds array

来自 List Groups 的 编码 群组 ID。当 mode 为 limited 时必填 (1-100 个，重复项只计一次) ；当 mode 为 all 时请省略。

ID 未知或格式错误、limited 列表为空，或在 all 模式下传入群组 ID，均返回 400。

curl -X PUT https://api.cursor.com/grok-bot/access \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "mode": "limited",    "groupIds": ["group_PDSPmvukpYgZEDXsoNirw3CFhy"]  }'

响应：

{  "mode": "limited",  "groups": [    {      "id": "group_PDSPmvukpYgZEDXsoNirw3CFhy",      "name": "Platform Engineering"    }  ]}

获取 Grok Bot 网络策略

GET/grok-bot/network

返回团队的 Grok Bot 网络策略。

响应字段

egressMode string

unset、allow_all、default_with_network_settings 或 network_settings_only。

allowlist array

允许访问的导出目标：域名、通配符域名、IP 地址、CIDR 范围，或 host-or-CIDR:port 形式，例如 54.85.223.0/24:3306。

locked boolean

为 true 时，群组策略无法覆盖团队策略。
curl -X GET https://api.cursor.com/grok-bot/network \  -u YOUR_API_KEY:

响应：

{  "egressMode": "network_settings_only",  "allowlist": ["linkedin.com", "*.crunchbase.com", "10.0.0.0/8", "54.85.223.0/24:3306"],  "locked": true}

替换 Grok Bot 网络策略

PUT/grok-bot/network

替换团队的 Grok Bot 网络策略。团队方案会返回 403。

参数

egressMode string 必填

可选值之一：
  • unset：不应用任何策略
  • allow_all：允许所有导出目标
  • default_with_network_settings：Cherri Code 的默认目标以及允许列表中的目标
  • network_settings_only：允许列表中的目标，以及运行 Grok Bot 所需的目标

allowlist array 必填

最多 500 个导出目标，每条长度为 1 至 253 个字符。可以是域名、通配符域名、IP 地址、CIDR 范围，或形如 host-or-CIDR:port 的值，例如 54.85.223.0/24:3306。

locked boolean 必填

为 true 时，群组策略无法覆盖团队策略。

请求体不完整、模式未知或允许列表条目无效时返回 400。

curl -X PUT https://api.cursor.com/grok-bot/network \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "egressMode": "network_settings_only",    "allowlist": ["linkedin.com", "*.crunchbase.com", "10.0.0.0/8", "54.85.223.0/24:3306"],    "locked": true  }'

响应：

{  "egressMode": "network_settings_only",  "allowlist": ["linkedin.com", "*.crunchbase.com", "10.0.0.0/8", "54.85.223.0/24:3306"],  "locked": true}

列出 Grok Bot 团队规则

GET/grok-bot/team-rules

列出 Grok Bot 团队规则，按创建时间由新到旧排序。

参数

limit number

每页结果数。默认值：50。最大值：100。

cursor string

来自上一次响应中 nextCursor 的不透明游标。
curl -X GET "https://api.cursor.com/grok-bot/team-rules?limit=50" \  -u YOUR_API_KEY:

响应：

{  "teamRules": [    {      "id": "rule_PDSPmvukpYgZEDXsoNirw3CFhy",      "name": "Ask before publishing",      "content": "Never publish a release without an explicit go from the requester.",      "enabled": true,      "scope": "grokBot",      "createdAt": "2024-01-15T10:30:00.000Z",      "updatedAt": "2024-01-15T10:30:00.000Z"    }  ],  "nextCursor": null}

创建 Grok Bot 团队规则

POST/grok-bot/team-rules

创建一条 Grok Bot 团队规则。每个团队最多可存储 50 条 Grok Bot 规则。成功时返回 201。

参数

name string 必填

1 到 255 个字符。

content string 必填

1 到 30,000 个字符。

enabled boolean 必填

该规则是否处于启用状态。
curl -X POST https://api.cursor.com/grok-bot/team-rules \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "name": "Ask before publishing",    "content": "Never publish a release without an explicit go from the requester.",    "enabled": true  }'

响应：

{  "teamRule": {    "id": "rule_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Ask before publishing",    "content": "Never publish a release without an explicit go from the requester.",    "enabled": true,    "scope": "grokBot",    "createdAt": "2024-01-15T10:30:00.000Z",    "updatedAt": "2024-01-15T10:30:00.000Z"  }}

更新 Grok Bot 团队规则

PATCH/grok-bot/team-rules/:id

更新 Grok Bot 团队规则。规则不存在时返回 404。

参数

id string 必填

来自列表或创建响应的编码规则 ID。

name string

1 到 255 个字符。

content string

1 到 30,000 个字符。

enabled boolean

规则是否处于启用状态。
curl -X PATCH https://api.cursor.com/grok-bot/team-rules/rule_PDSPmvukpYgZEDXsoNirw3CFhy \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "enabled": false  }'

响应：

{  "teamRule": {    "id": "rule_PDSPmvukpYgZEDXsoNirw3CFhy",    "name": "Ask before publishing",    "content": "Never publish a release without an explicit go from the requester.",    "enabled": false,    "scope": "grokBot",    "createdAt": "2024-01-15T10:30:00.000Z",    "updatedAt": "2024-01-15T10:30:00.000Z"  }}

删除 Grok Bot 团队规则

DELETE/grok-bot/team-rules/:id

删除 Grok Bot 团队规则。成功时返回 204 No Content。

参数

id string 必填

要删除的编码规则 ID。
curl -X DELETE https://api.cursor.com/grok-bot/team-rules/rule_PDSPmvukpYgZEDXsoNirw3CFhy \  -u YOUR_API_KEY:

响应：

204 No Content

列出 Grok Bot 设置清单

GET/grok-bot/setup-manifests

列出 Grok Bot 设置清单，按 id 排序。

参数

limit number

每页结果数。默认值：50。最大值：100。

cursor string

来自上一次 nextCursor 的不透明游标。
curl -X GET "https://api.cursor.com/grok-bot/setup-manifests?limit=50" \  -u YOUR_API_KEY:

响应：

{  "manifests": [    {      "id": "toolchain",      "scripts": [        { "id": "node", "setup": "mise install node@22", "check": "node --version" },        { "id": "pnpm", "setup": "npm i -g pnpm" }      ]    }  ],  "nextCursor": null}

更新或插入 Grok Bot 设置清单

PUT/grok-bot/setup-manifests/:manifestId

创建或替换设置清单。每个团队最多可存储 100 个清单。若清单在请求期间发生变更，则返回 409。

参数

manifestId string 必填

1 到 128 个字符，以字母或数字开头，其后可使用字母、数字、.、_ 或 -。

scripts array 必填

设置脚本。
  • id string：格式与 manifestId 相同
  • setup string：非空的安装命令
  • check string：可选的验证命令
curl -X PUT https://api.cursor.com/grok-bot/setup-manifests/toolchain \  -u YOUR_API_KEY: \  -H "Content-Type: application/json" \  -d '{    "scripts": [      { "id": "node", "setup": "mise install node@22", "check": "node --version" },      { "id": "pnpm", "setup": "npm i -g pnpm" }    ]  }'

响应：

{  "manifest": {    "id": "toolchain",    "scripts": [      { "id": "node", "setup": "mise install node@22", "check": "node --version" },      { "id": "pnpm", "setup": "npm i -g pnpm" }    ]  }}

删除 Grok Bot 设置清单

DELETE/grok-bot/setup-manifests/:manifestId

删除设置清单。成功时返回 204 No Content。

参数

manifestId string 必填

要删除的清单键。
curl -X DELETE https://api.cursor.com/grok-bot/setup-manifests/toolchain \  -u YOUR_API_KEY:

响应：

204 No Content

错误

错误响应体使用：

{ "code": "error", "message": "…" }
状态发生情况
401Key 无效、缺少 read:* / admin:* 权限，或该团队未启用 Grok Bot Admin API
403该团队或其方案无法执行此写入操作
404路径中格式正确的规则 ID 或清单 ID 不存在
409设置清单在请求期间发生了变更
400响应体或 ID 无效；PATCH 内容为空；在能力上使用 enabled；未知群组；规则或清单数量过多；没有可归属设置清单的 所有者
429超出该 endpoint 的 rate limit