REST API
UserJot REST API 可让你的代码访问与仪表板相同的工作区数据:工作区元数据、看板、请求(包括合并、相似请求、标签、订阅和附件)、评论、投票、更新日志条目、成员(包括 GDPR 删除)、公司、对话、资产,以及帮助中心的内容集和文章。
包含所有路由、架构和示例的完整交互式参考文档可在 userjot.com/docs/api 查看,也可直接访问 https://api.userjot.com/v1/docs。该文档所用的 OpenAPI 文件位于 https://api.userjot.com/v1/openapi.json(同时镜像于 https://userjot.com/docs/api/openapi.json),你可以用它为所用语言生成类型化客户端。
基础 URL 和身份验证
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENUserJot 的 /v1/* 路由接受两种 Bearer 令牌:
API 令牌:管理员和所有者可在设置 → MCP & API中创建令牌。令牌以
uj_live_为前缀,属于单个工作区,在撤销前不会过期,并且可以重命名。使用按住以撤销(按住不放)即可立即撤销令牌;已撤销的令牌仍会保留在列表中,以供审计追溯。OAuth 2.0 访问令牌:支持 PKCE(
S256)、动态客户端注册(/oauth/register)、客户端 ID 元数据文档(CIMD)、令牌撤销(/oauth/revoke),以及位于https://api.userjot.com/.well-known/oauth-authorization-server和https://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp的发现元数据。访问令牌有效期为 1 小时,刷新令牌有效期为 30 天且会轮换(workspace和offline_access作用域);只有在授权用户仍是该工作区的所有者或管理员期间,令牌才有效。
发起第一个请求
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"速率限制
API 和 MCP 请求共用一个工作区速率限制额度:
套餐 | 每分钟 | 每小时 |
|---|---|---|
免费版 | 10 个请求 | 150 个请求 |
入门版 | 60 个请求 | 1,500 个请求 |
专业版 | 120 个请求 | 5,000 个请求 |
此外,各项操作还适用单独的额度:
资产:资产导入、多部分上传和自动导入的 Markdown 图片共用独立的工作区额度:每分钟 20 个请求、每小时 300 个请求(上传完成操作另有每分钟 20 次、每小时 300 次的额度)。
外发对话(
POST /v1/conversations):仅付费方案可用;Starter方案每天最多5 次,Professional方案每天最多15 次(免费方案会返回409 plan_feature_unavailable)。
超出限制时,API 会返回 HTTP 429,并附带 Retry-After 标头和 error.details.retry_after_seconds。
分页、错误和幂等性
游标分页。列表端点接受
cursor和limit(最多100;默认值因端点而异,例如丰富列表端点/v1/requests和/v1/changelogs的默认值为10),并返回next_cursor以继续向后翻页。错误封装。错误响应会返回
{ "error": { "code", "message", "details" } },并且每个响应都包含X-Request-Id响应头。常见代码包括422 validation_error(带有details.issues)、409 plan_limit_reached、409 plan_feature_unavailable、409 request_merged、410 member_erased(在GET/PATCH /v1/members/{member_id}上,适用于经过DELETE /v1/members/{member_id}GDPR 删除的情况)、409 member_erased(用于引用已删除成员的路由)、409 help_slug_taken和409 help_version_conflict。幂等性。发送
Idempotency-Key标头(保存 24 小时,并关联请求正文指纹),即可安全重试以下八个路由上的创建请求:/v1/requests、/v1/changelogs、/v1/conversations、/v1/conversations/{conversation_id}/replies、/v1/conversations/{conversation_id}/notes、/v1/assets/import、/v1/help/articles和/v1/help/collections。
资源和图片
可通过以下三种方式上传图片(PNG、JPEG、GIF 或 WebP,最大 10 MiB):
多部分上传:
POST /v1/assets(createAsset,仅限 REST)可通过单个multipart/form-data请求上传图片。URL 导入:
POST /v1/assets/import会将公开的 HTTPS 图片下载到工作区存储空间。预签名三步上传:
POST /v1/assets/uploads(提供准确的size_bytes;每个工作区最多可有 100 个未完成的上传会话)→ 将PUT字节上传到有效期为 30 分钟的预签名 URL →POST /v1/assets/uploads/{upload_id}/complete。
在 Markdown 中使用 asset:<id> 引用已上传的资产。发送到更新日志和帮助文章端点的 Markdown 中所嵌入的公开 HTTPS 图片 URL 也会自动导入(每个更新日志请求最多 10 张内嵌图片,每个帮助中心文章请求最多 20 张),并计入工作区资产额度。
Webhook
目前尚不支持向外发送客户 Webhook。如需实时团队提醒,请使用 连接 Slack 或 连接 Discord,也可以通过 REST API 轮询变更。
REST 还是 MCP
MCP 服务器基于此 API 构建,可将 100 个 REST 操作中的 98 个作为 MCP 工具提供(POST /v1/assets多部分上传和 DELETE /v1/members/{member_id} GDPR 删除仅支持 REST)。如果你希望全面控制请求和响应,可在自己的后端、自动化流程或应用程序代码中使用 REST API。如果要连接支持模型上下文协议的 AI 客户端,则可使用 MCP。
令牌管理
像对待其他机密一样保护 API 令牌:
不要将其硬编码到已提交的配置文件中。
建议使用环境变量或密钥管理器。
如有可能,请为不同环境或团队成员使用单独的令牌。
前往设置 → MCP & API,使用按住以撤销撤销不再需要的令牌。