REST API

Shayan Taslim更新

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 和身份验证

text
Base URL:      https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKEN

UserJot 的 /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 作用域);只有在授权用户仍是该工作区的所有者或管理员期间,令牌才有效。

发起第一个请求

Bash
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,使用按住以撤销撤销不再需要的令牌。

这是否解答了您的问题?