开发者

用 Welley 开发

你可以用 Welley API 开发客户端、脚本、社区工具和集成。在线的 Swagger 参考文档介绍了可用的操作和数据结构。

打开在线 Swagger UI下载 OpenAPI JSON

我们计划将来把 Welley 开源。发布日期和许可证目前都还没有公布。

从公开请求开始

API 通过 HTTPS 运行，大多数操作接收和返回 JSON。公开的读取操作不需要账号也能用。

读取服务器信息

这个请求会返回服务器的公开元数据，不会改动任何服务器数据。

curl --fail --silent --show-error "https://welley.social/api/v1/instance"

在 Swagger 里查找操作

编写客户端之前，先看一下这个操作的参数、请求结构、响应结构和权限。

为集成做身份验证

受保护的操作需要在 Authorization 头里带上有效的令牌。我们的官方 CLI 发送令牌时会加上 Bearer 前缀。

读取你在服务器上的有效权限

请按你平时处理密钥的方式，把 WELLEY_TOKEN 设为你自己的有效令牌。这个示例只会读取数据。

curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"
  • 如果是做集成，请在账号设置里创建一个个人访问令牌。
  • 给它起个名字，再设一个有效期。API 也接受 expiresInDays=0，表示令牌不记录有效期。
  • 限定这个令牌可以使用哪些全局权限、群组权限和哪些群组。
  • 如果某个允许列表留空，这一项就只受你当前访问权限的限制。令牌给不了你本来没有的权限。
  • 令牌密钥只会显示一次。请在关闭创建结果之前保存好。
  • 管理令牌需要账号的登录会话。个人访问令牌不能创建、列出、复制或撤销令牌。

检查权限和范围

身份验证让 API 知道是谁在调用，角色权限则决定调用者能使用哪些操作。

  • 受保护的请求没有有效的身份验证时，API 会返回 401。
  • 调用者缺少所需权限时，API 会返回 403。
  • 权限名称的格式是 Resource.Action，例如 GroupSettings.Manage。
  • 对于带范围的 webhook 和权限操作，省略 scope 就使用服务器范围。要用群组范围，请传入群组的 TypeId。
  • 请阅读每个操作的说明。有些端点使用 HTTP 签名或其他协议，而不是账号令牌。

选择 API 分类

参考文档涵盖社交功能、集成和服务器管理。这里的示例只是 API 的一小部分。

账号和个人资料

读取个人资料、管理账号下的身份，也可以使用账号导出或迁移操作。

方法路径操作访问权限
GET/api/v1/users按用户名读取本地或远程的个人资料。公开，或可选令牌
POST/api/v1/users在当前账号下再添加一个个人资料，数量不超过服务器的上限。需要令牌

帖子和动态

读取动态并创建帖子。其他操作处理回复、投票、回应、草稿和收藏的帖子。

方法路径操作访问权限
GET/api/v1/posts以访客身份读取公开帖子，通过身份验证后则读取个性化动态。公开，或可选令牌
POST/api/v1/posts创建帖子，并设置内容和谁能看到。需要令牌

群组和活动

用群组、成员关系、频道、管理和活动来开发社区工具。

方法路径操作访问权限
POST/api/v1/groups创建一个群组，使用已验证用户的权限。需要令牌
GET/api/v1/events列出公开活动，或已验证用户能看到的活动。公开，或可选令牌
POST/api/v1/events创建一个活动。群组活动需要 GroupEvents.Create。需要令牌

对话和通知

读取对话房间和其中的消息。读取通知集合，并更新它们是否已读。

方法路径操作访问权限
GET/api/v1/rooms列出当前用户的房间。要继续获取后面的列表，请使用响应正文里的 nextCursor。需要令牌
GET/api/v1/user-notifications列出当前用户的通知。需要令牌

Webhook 和 AI 智能体

用 webhook 连接外部服务，通过智能体 API 设置 AI 智能体。

方法路径操作访问权限
GET/api/v1/webhooks/events获取支持的 webhook 事件类型列表。需要令牌
POST/api/v1/webhooks在你有权限的服务器范围或群组范围内创建 webhook。HTTP 签名密钥只显示一次。需要令牌
GET/api/v1/ai-agents列出调用者能看到的 AI 智能体。需要令牌

服务器和群组管理

用 API 处理设置、举报、管理、联合控制、配额和部署管理。

方法路径操作访问权限
GET/api/v1/rbac/permissions读取当前用户在指定范围内的有效权限。需要令牌
GET/api/v1/settings如果账号有所需权限，就可以读取平台设置。公开，或可选令牌

处理响应和媒体

请按各个操作自己的分页和上传流程来做。

  • 对于游标式动态，请沿用服务器返回的分页链接。不要凭对 ID 的猜测自己构造游标。
  • 房间会在响应正文里返回一个不透明的 nextCursor。继续获取列表时，请保持相同的筛选条件。
  • 上传媒体时，先创建一个上传条目，再把内容发送到它返回的 URL。
  • 请查看每个操作的错误响应和限制。即使是文档里有的操作，也可能需要特定角色、服务器配置或外部服务提供方。