Neotask API 参考

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

认证

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

许多端点结合了多种认证要求。例如，"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 路径参数必须是以下值之一：

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 格式：

{
  "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 支持。