# Neotask API 参考

Neotask 平台的完整 API 参考文档。本文档涵盖所有可用端点、认证方法、错误处理和速率限制。

---

## 认证

所有 API 请求需要通过以下方法之一进行认证：

- **Bearer JWT**：传递请求头 `Authorization: Bearer <token>`。Token 通过下文描述的登录端点获取。
- **License HMAC**：Neotask 桌面应用程序使用的设备绑定 HMAC-SHA256 签名。客户端使用从许可证密钥和设备指纹派生的密钥对请求进行签名。
- **Tenant Header**：对于任何租户范围的端点，需包含 `x-tenant-id: <tenantId>`。此请求头标识请求适用于哪个租户（工作区）。

许多端点结合了多种认证要求。例如，"Tenant + Admin" 意味着请求必须同时包含有效的 JWT（属于具有 Admin 角色的用户）和 `x-tenant-id` 请求头。

---

## Auth 端点

跨 Web、iOS 和桌面平台的用户认证端点。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/auth/login` | 使用邮箱和密码进行认证。成功时返回 JWT。 | 无 |
| POST | `/api/auth/google` | 通过 Web 端 Google OAuth 进行认证。需要 Google 授权码。 | 无 |
| POST | `/api/auth/google-ios` | 通过 iOS 端 Google OAuth 进行认证。需要 iOS 特定的授权载荷。 | 无 |
| POST | `/api/auth/google-token` | 验证 Google 访问令牌并返回 Neotask JWT。 | 无 |
| POST | `/api/auth/apple` | 通过 Apple Sign-In 进行认证。需要 Apple 身份令牌。 | 无 |
| GET | `/api/auth/me` | 返回已认证用户的个人资料（姓名、邮箱、头像、角色）。 | JWT |
| DELETE | `/api/auth/account` | 永久删除已认证用户的账户及所有关联数据。 | JWT |

---

## Dashboard Auth 端点

Neotask 控制面板特定的认证端点，包括许可证密钥登录和双因素认证（TOTP）。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/dashboard/auth/login` | 使用许可证密钥进行认证。成功时返回 JWT，或提示需要 TOTP。 | 无 |
| POST | `/api/dashboard/auth/totp-login` | 在启用双因素认证时，通过提供 TOTP 代码或备用代码完成登录。 | 无 |
| GET | `/api/dashboard/auth/me` | 返回已认证控制面板用户的当前许可证信息和功能权限。 | JWT |
| POST | `/api/dashboard/totp/setup` | 生成 TOTP 密钥和二维码，用于设置双因素认证。 | JWT |
| POST | `/api/dashboard/totp/verify` | 验证 TOTP 代码以确认并启用账户的双因素认证。 | JWT |

---

## Billing 端点

通过 Stripe 和 RevenueCat 管理订阅、结账会话和应用内购买。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/billing/checkout` | 为 Pro 套餐创建 Stripe Checkout 会话。返回结账 URL。 | Tenant + Admin |
| POST | `/api/billing/checkout/enterprise` | 为 Enterprise 套餐创建 Stripe Checkout 会话。返回结账 URL。 | Tenant + Admin |
| GET | `/api/billing/status` | 返回租户的当前套餐、消息计数和使用限额。 | Tenant + Viewer |
| POST | `/api/billing/portal` | 创建 Stripe 客户门户会话，用于管理支付方式和发票。 | Tenant + Admin |
| POST | `/api/billing/agent-addon` | 为租户购买额外的代理插槽附加项。 | Tenant + Admin |
| POST | `/api/billing/webhook` | Stripe webhook 处理程序。验证 Stripe 签名并处理订阅生命周期事件。 | Stripe Signature |
| POST | `/api/billing/revenuecat-sync` | 通过 RevenueCat 验证 iOS 应用内购买并将权限同步到租户。 | Tenant + Admin |
| POST | `/api/billing/revenuecat-webhook` | RevenueCat webhook 处理程序。处理来自 App Store 的订阅事件。 | Bearer |

---

## Chat 端点

发送和接收消息、管理会话，以及轮询异步任务结果。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/chat/init` | 为已认证用户自动配置租户、代理和会话。使用此端点在单次调用中引导新用户的聊天环境。 | JWT |
| POST | `/api/chat/send` | 向代理发送消息。消息异步处理；立即返回任务 ID。 | Tenant + Admin |
| GET | `/api/chat/jobs/:jobId` | 通过任务 ID 轮询异步聊天任务的状态和结果。 | Tenant + Viewer |
| GET | `/api/chat/messages` | 获取给定会话的所有消息。通过查询参数传递会话 ID。 | Tenant + Viewer |
| GET | `/api/chat/sessions` | 列出租户的所有聊天会话。 | Tenant + Viewer |
| POST | `/api/chat/sessions` | 创建新的聊天会话。 | Tenant + Admin |

---

## Agent 和 Activity 端点

浏览与租户关联的代理、会话、工具、文件、技能、频道、定时任务和团队。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| GET | `/api/activity/agents` | 列出属于租户的所有代理。 | Tenant |
| GET | `/api/activity/sessions` | 列出会话。支持通过 `agentId`、`status` 和日期范围查询参数进行筛选。 | Tenant |
| GET | `/api/activity/sessions/:id/entries` | 获取特定会话的所有条目（消息和事件）。 | Tenant |
| GET | `/api/activity/tools` | 列出租户代理可用的所有工具。 | Tenant |
| GET | `/api/activity/files` | 列出与租户代理关联的所有文件。 | Tenant |
| GET | `/api/activity/skills` | 列出与租户代理关联的所有技能。 | Tenant |
| GET | `/api/activity/channels` | 列出与租户代理关联的所有频道。 | Tenant |
| GET | `/api/activity/cron-jobs` | 列出租户的所有定时（cron）任务。 | Tenant |
| GET | `/api/activity/teams` | 列出租户内的所有团队。 | Tenant |

---

## Skills 端点

管理技能目录、安装和配置技能，以及发布自定义技能。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| GET | `/api/skills/catalog` | 浏览完整的技能目录。返回所有已发布的可安装技能。 | Tenant |
| GET | `/api/skills/list` | 列出用户当前已安装的技能。 | Tenant + Viewer |
| POST | `/api/skills/sync` | 从文件系统同步技能。在部署新技能文件后使用此端点刷新注册表。 | Tenant + Admin |
| POST | `/api/skills/register` | 从目录中注册（安装）技能。 | Tenant + Viewer |
| DELETE | `/api/skills/register/:skillId` | 通过 ID 注销（卸载）技能。 | Tenant + Viewer |
| POST | `/api/skills/:skillId/publish` | 发布技能使其在目录中可用。 | Tenant + Admin |
| POST | `/api/skills/:skillId/unpublish` | 取消发布技能，将其从目录中移除。 | Tenant + Admin |
| GET | `/api/skills/all` | 列出所有技能，包括未发布的。仅管理员可用的技能管理端点。 | Tenant + Admin |
| PUT | `/api/skills/:skillId/env-schema` | 定义或更新技能的环境变量模式。控制向用户展示哪些配置字段。 | Tenant + Admin |
| POST | `/api/skills/:skillId/configure` | 保存已安装技能的配置值。 | Tenant + Viewer |
| DELETE | `/api/skills/:skillId/configure` | 移除技能的所有配置，将其重置为默认值。 | Tenant + Viewer |

---

## Channel 端点

链接、配置、启用和断开消息频道（例如 Slack、Discord、WhatsApp）。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| GET | `/api/channels/` | 列出所有频道及其当前状态。 | Tenant + Viewer |
| GET | `/api/channels/:channel/status` | 获取特定频道的详细状态。 | Tenant + Viewer |
| POST | `/api/channels/:channel/link` | 开始频道链接流程。根据频道类型返回链接 URL 或会话令牌。 | Tenant + Admin |
| GET | `/api/channels/:channel/link/wait` | 长轮询等待频道链接流程完成。在频道成功链接或操作超时后返回。 | Tenant + Admin |
| GET | `/api/channels/:channel/jobs/:jobId` | 获取频道特定异步任务的结果。 | Tenant + Admin |
| POST | `/api/channels/:channel/enable` | 启用已链接的频道，使代理开始接收该频道的消息。 | Tenant + Admin |
| POST | `/api/channels/:channel/disable` | 禁用频道但不取消链接。代理停止接收消息，但频道连接保持不变。 | Tenant + Admin |
| POST | `/api/channels/:channel/disconnect` | 完全断开并取消链接频道。 | Tenant + Admin |
| GET | `/api/channels/:channel/config` | 获取频道的当前配置。 | Tenant + Admin |
| POST | `/api/channels/:channel/config` | 更新频道的配置。 | Tenant + Admin |

---

## Google OAuth 端点

发起和管理 Google OAuth 流程，用于将 Google 服务连接到 Neotask。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| GET/POST | `/oauth/google/start` | 发起 Google OAuth 流程。接受可选参数以指定请求访问哪些 Google 服务。 | 可选 |
| GET | `/oauth/google/services` | 列出 Neotask 支持的所有 Google 服务定义，按类别分组。 | 无 |
| GET | `/oauth/google/callback` | OAuth 回调处理程序。用户授予或拒绝访问后 Google 重定向到此处。 | 无 |
| GET | `/oauth/google/status` | 轮询正在进行的 OAuth 流程的状态。返回流程是待处理、已完成还是失败。 | 无 |

### 可用 Google 服务

Neotask 支持连接 25 个 Google 服务，按类别组织：

| 类别 | 服务 |
|----------|----------|
| **核心** | Gmail、Calendar、Drive、Docs、Sheets、Slides、Forms、Keep、Tasks |
| **通信** | People/Contacts、Chat、Meet、YouTube、Photos |
| **位置** | Places API、Routes/Directions、Business Profile |
| **专业** | Classroom、Play Developer、AdSense、Google Ads |

---

## Provider Keys 端点

管理第三方 API 密钥（例如 LLM 提供商的密钥）。密钥在静态存储时加密，可按需解密。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| PUT | `/api/provider-keys/:provider` | 保存或更新指定提供商的 API 密钥。密钥在存储前加密。 | HMAC + Auth |
| GET | `/api/provider-keys/` | 列出所有已保存的提供商密钥。密钥值被掩码显示（仅显示最后四个字符）。 | Auth |
| DELETE | `/api/provider-keys/:provider` | 移除指定提供商已保存的 API 密钥。 | HMAC + Auth |
| GET | `/api/provider-keys/:provider/resolve` | 解密并返回指定提供商的完整 API 密钥。 | Auth |
| GET | `/api/provider-keys/mode` | 获取当前密钥模式（用户提供 vs. 平台积分）和剩余积分余额。 | Auth |

### 允许的提供商

`:provider` 路径参数必须是以下值之一：

- `anthropic`
- `openai`
- `openai-codex`
- `openrouter`
- `google-ai`

---

## Usage 端点

跟踪使用量、查询分析数据、监控支出和管理预算。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/usage/ingest` | 摄入使用数据记录（例如 token 计数、使用的模型）。 | Auth |
| GET | `/api/usage/query` | 使用灵活的筛选器（日期范围、模型、代理）查询使用分析数据。 | Auth |
| GET | `/api/usage/summary` | 获取给定时间段的使用摘要。通过查询参数传递 `period`（例如 `day`、`week`、`month`）。 | Auth |
| GET | `/api/usage/analytics` | 检索详细的使用分析数据，包括按模型和代理的明细。 | Auth |
| GET | `/api/usage/spending` | 获取给定时间段的支出数据。通过查询参数传递 `period`。 | Auth |
| GET | `/api/usage/budget` | 获取预算信息，包括总限额、已使用金额和剩余金额。 | Auth |
| POST | `/api/usage/cron-runs` | 记录定时（cron）任务的执行情况以进行使用跟踪。 | Auth |
| POST | `/api/usage/budget-snapshot` | 捕获当前预算状态的时间点快照。 | Auth |

---

## Onboarding 端点

引导新用户完成初始设置，包括选择模型提供商和配置 API 密钥。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/onboarding/init` | 为已认证用户初始化引导配置。创建默认设置并返回引导状态。 | JWT |
| GET | `/api/onboarding/models` | 列出可用的模型提供商及其支持的模型。此端点是公开的，不需要认证。 | 无 |
| POST | `/api/onboarding/setup` | 在引导过程中配置提供商 API 密钥。保存前验证密钥。 | Tenant + Admin |
| POST | `/api/onboarding/complete` | 为当前用户标记引导完成。 | Dashboard Auth |

---

## Tenant 端点

创建和管理租户（工作区）、存储加密密钥，以及直接创建会话和任务。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/tenants/` | 创建新租户（工作区）。返回租户 ID 和默认设置。 | JWT |
| GET | `/api/tenants/:tenantId` | 获取特定租户的详情，包括设置和成员数量。 | JWT |
| POST | `/api/tenants/secrets` | 存储与租户关联的加密密钥。用于服务集成。 | Tenant + Admin |
| POST | `/api/tenants/sessions` | 在租户内创建新会话。 | Tenant + Admin |
| POST | `/api/tenants/jobs` | 在租户内创建新的异步任务。 | Tenant + Admin |

---

## Memory 端点

管理代理记忆配置、文件和内容。记忆允许代理跨会话持久化信息。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| GET | `/api/memory/config` | 获取当前记忆配置（启用状态、保留策略、限制）。 | Auth |
| POST | `/api/memory/config` | 更新记忆设置，如保留期限和存储限制。 | Auth |
| GET | `/api/memory/files` | 列出为代理存储的所有记忆文件。 | Auth |
| GET | `/api/memory/files/:filename` | 通过文件名检索特定记忆文件的内容。 | Auth |
| DELETE | `/api/memory/files/:filename` | 通过文件名删除特定记忆文件。 | Auth |
| GET | `/api/memory/content` | 检索存储的记忆内容。 | Auth |
| POST | `/api/memory/content` | 为代理存储新的记忆内容。 | Auth |

---

## Google Accounts 端点

管理通过 OAuth 连接到 Neotask 的 Google 账户。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| GET | `/api/google-accounts/` | 列出所有已连接的 Google 账户及其服务范围和状态。 | Auth |
| POST | `/api/google-accounts/:accountId/activate` | 激活已连接的 Google 账户，使代理能够使用其授权的服务。 | Auth |
| DELETE | `/api/google-accounts/:accountId` | 移除已连接的 Google 账户并撤销其存储的令牌。 | Auth |

---

## Contact 和 Support 端点

提交和管理支持联系请求。

| 方法 | 端点 | 描述 | 认证 |
|--------|----------|-------------|------|
| POST | `/api/contact/` | 提交联系表单消息。每个 IP 地址每 15 分钟限制 5 次请求。 | 无 |
| GET | `/api/contacts/` | 列出所有联系提交记录，支持分页。仅管理员可用。 | Admin |
| PATCH | `/api/contacts/:id` | 更新联系提交记录的状态（例如标记为已解决）。 | Admin |
| DELETE | `/api/contacts/:id` | 删除联系提交记录。 | Admin |

---

## 速率限制

Neotask 对某些端点实施速率限制以保护服务稳定性。当超过速率限制时，API 返回 `429 Too Many Requests` 响应。

| 端点类别 | 限制 |
|-------------------|-------|
| 联系表单 | 每个 IP 每 15 分钟 5 次请求 |
| 登录尝试 | 每个 IP 每 15 分钟 10 次请求 |
| 跟踪/分析 | 每个 IP 每 60 秒 30 次请求 |

---

## 错误响应

所有错误响应遵循一致的 JSON 格式：

```json
{
  "error": "Error message description",
  "status": 400
}
```

### 状态码

| 代码 | 含义 |
|------|---------|
| 400 | **Bad Request** -- 请求格式错误或包含无效参数。 |
| 401 | **Unauthorized** -- 缺少认证或提供的令牌无效。 |
| 402 | **Payment Required** -- 租户的积分已耗尽。升级套餐或添加积分以继续。 |
| 403 | **Forbidden** -- 已认证用户没有足够的权限执行此操作。 |
| 404 | **Not Found** -- 请求的资源不存在。 |
| 429 | **Rate Limited** -- 请求过多。等待并在响应头指示的时间后重试。 |
| 500 | **Internal Server Error** -- 服务器发生意外错误。如果持续出现，请联系 Neotask 支持。 |