开发者

# 用 Welley 开发

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

[打开在线 Swagger UI](https://welley.social/q/swagger-ui/) [下载 OpenAPI JSON](https://welley.social/q/openapi?format=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` | 列出当前用户的通知。 | 需要令牌 |

### 媒体、搜索和翻译

上传媒体、搜索你能看到的内容，也可以请求文本翻译。

| 方法 | 路径 | 操作 | 访问权限 |
| --- | --- | --- | --- |
| POST | `/api/v1/uploads` | 先创建一个上传条目，再用 PUT 把文件内容发送到它返回的上传 URL。 | 需要令牌 |
| GET | `/api/v1/search` | 搜索调用者能看到的内容，或解析受支持的 URL。 | 公开，或可选令牌 |
| POST | `/api/v1/translate/text` | 把文本翻译成指定的语言。 | 需要令牌 |

### 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。
-   请查看每个操作的错误响应和限制。即使是文档里有的操作，也可能需要特定角色、服务器配置或外部服务提供方。