v1.0.0 OpenAPI 3.1.0

MeetAgain API

以编程方式访问公开活动、成员相关操作（报名、评论、上传图片）以及平台内容、监控与日志板块。非公开端点需使用个人访问令牌（PAT）认证。

服务器: / 下载规范: JSON YAML

身份验证

个人访问令牌

使用个人访问令牌（PAT）对 API 进行认证——这是一个与你的账户绑定的长期 Bearer 令牌。

适用于你自己的 CLI、脚本或运维任务。在访问令牌页面签发一个长期 Bearer 令牌，并可在同一页面随时撤销。

Header： Authorization: Bearer mapat_...

身份： 你自己（签发令牌的用户）

cms

CMS 页面与区块编辑。仅限具有 ROLE_ADMIN 的用户使用。

GET /api/v1/cms/pages 列出所有CMS页面及其所属群组和各语言的区块数量

列出所有CMS页面及其所属群组和各语言的区块数量

响应

代码	描述
`200`	所有CMS页面，最新的在前	CmsPageSummaryList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足

示例请求

curl '/api/v1/cms/pages' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/cms/block-types 区块类型目录及每种类型接受的字段

区块类型目录及每种类型接受的字段

响应

代码	描述
`200`	写入端点据以校验的字段定义	CmsBlockTypeCatalog
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足

示例请求

curl '/api/v1/cms/block-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /api/v1/cms/blocks/{blockId} 删除一个区块

删除一个区块

参数

名称	位置	类型	描述
`blockId` *	path	`integer`

响应

代码	描述
`204`	区块已删除
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	未找到区块

示例请求

curl -X DELETE '/api/v1/cms/blocks/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

PATCH /api/v1/cms/blocks/{blockId} 将字段覆盖到已存储的区块上

将字段覆盖到已存储的区块上

负载会覆盖已存储的内容，因此部分请求体只会更改其中指定的字段。

参数

名称	位置	类型	描述
`blockId` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`type`	`any`	区块类型名称或数字ID；默认为已存储的类型
`payload`	`object`

响应

代码	描述
`200`	已存储的区块，经过填充和净化	CmsBlockSummary
`400`	请求体格式错误
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	未找到区块
`422`	不可用的区块类型或缺少必填字段	ValidationErrorResponse

示例请求

curl -X PATCH '/api/v1/cms/blocks/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"Text","payload":"value"}'

GET /api/v1/cms/pages/{id}/blocks 某页面在某语言下的有序区块

某页面在某语言下的有序区块

参数

名称	位置	类型	描述
`id` *	path	`integer`
`locale`	query	`string`	两字母语言代码；默认为已配置的默认语言

响应

代码	描述
`200`	按优先级排序的区块	CmsBlockList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	未找到页面
`422`	未知语言

示例请求

curl '/api/v1/cms/pages/1/blocks?locale=en' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/cms/pages/{id}/blocks 向页面的某个语言追加一个区块

向页面的某个语言追加一个区块

参数

名称	位置	类型	描述
`id` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`locale`	`string`
`type`	`any`	区块类型名称或来自区块类型目录的数字ID
`payload`	`object`

响应

代码	描述
`201`	已存储的区块，经过填充和净化	CmsBlockSummary
`400`	请求体格式错误
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	未找到页面
`422`	未知语言、不可用的区块类型或缺少必填字段	ValidationErrorResponse

示例请求

curl -X POST '/api/v1/cms/pages/1/blocks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locale":"en","type":"Text","payload":"value"}'

POST /api/v1/cms/blocks/{blockId}/move 在所属页面和语言范围内，将区块上移或下移一位

在所属页面和语言范围内，将区块上移或下移一位

参数

名称	位置	类型	描述
`blockId` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`direction`	`string`

响应

代码	描述
`200`	按新顺序排列的页面区块	CmsBlockList
`400`	请求体格式错误
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	未找到区块
`422`	up 或 down 之外的方向

示例请求

curl -X POST '/api/v1/cms/blocks/1/move' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"direction":"value"}'

images

分语言的图片替代文本。仅限具有 ROLE_ADMIN 的用户使用。

PUT /api/v1/images/{id}/alt 按语言保存某张图片的替代文本

按语言保存某张图片的替代文本

参数

名称	位置	类型	描述
`id` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`alt`	`object`	语言 => 替代文本；空字符串表示清除

响应

代码	描述
`200`	已刷新的条目，必需语言与缺失语言均重新计算	MissingAltImageItem
`400`	请求体格式错误
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	未找到图片
`422`	该语言不在此图片的必需语言范围内

示例请求

curl -X PUT '/api/v1/images/1/alt' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alt":"value"}'

GET /api/v1/images/missing-alt 列出缺少分语言替代文本的图片（键集分页）

列出缺少分语言替代文本的图片（键集分页）

参数

名称	位置	类型	描述
`after_id`	query	`integer`	键集游标：仅扫描 ID 更大的图片
`limit`	query	`integer`	每页扫描的候选数量（实际匹配项可能更少）默认值: `50`

响应

代码	描述
`200`	仍有至少一种必需语言缺少替代文本的图片列表页	MissingAltImageList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足

示例请求

curl '/api/v1/images/missing-alt?after_id=1&limit=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/images/{id}/content 输出原图的缩小预览

输出原图的缩小预览

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	预览字节流（通常为 image/webp；转换失败时为原始媒体类型）
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	未找到图片或其原始文件

示例请求

curl '/api/v1/images/1/content' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

security

安全事件流。只读，仅限具有 ROLE_ADMIN 的用户使用。

GET /api/v1/security/incidents 列出近期安全事件

列出近期安全事件

参数

名称	位置	类型	描述
`limit`	query	`integer`	默认值: `100`
`since`	query	`string` (date-time)	以 ISO-8601 时间作为 endedAt 的下界

响应

代码	描述
`200`	事件列表	IncidentList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色权限不足

示例请求

curl '/api/v1/security/incidents?limit=1&since=value' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/security/incidents/{id} 获取单个安全事件及其完整的来源报告

获取单个安全事件及其完整的来源报告

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	事件详情	IncidentDetail
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色权限不足
`404`	未找到该事件

示例请求

curl '/api/v1/security/incidents/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

seo

搜索引擎监控状态、问题与操作。仅限具有 ROLE_ADMIN 的用户使用。

GET /api/v1/seo/status 单个站点资源的 SEO 状况，并给出与上次抓取的差值

单个站点资源的 SEO 状况，并给出与上次抓取的差值

参数

名称	位置	类型	描述
`property`	query	`integer`	站点资源 ID；省略时使用第一个已启用的资源

响应

代码	描述
`200`	当前状态概览	SeoStatus
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	没有受监控的站点资源

示例请求

curl '/api/v1/seo/status?property=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/seo/issues 列出检测到的 SEO 问题

列出检测到的 SEO 问题

参数

名称	位置	类型	描述
`property`	query	`integer`
`filter`	query	`string`	默认值: `open`

响应

代码	描述
`200`	问题列表	SeoIssueList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`404`	没有受监控的站点资源

示例请求

curl '/api/v1/seo/issues?property=1&filter=value' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/seo/actions 列出最近记录的 SEO 操作

列出最近记录的 SEO 操作

参数

名称	位置	类型	描述
`limit`	query	`integer`	默认值: `100`

响应

代码	描述
`200`	操作列表	SeoActionList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足

示例请求

curl '/api/v1/seo/actions?limit=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/seo/actions 记录与 SEO 相关的操作，以便日后归因分析

记录与 SEO 相关的操作，以便日后归因分析

请求体

必填

内容类型: application/json

名称	类型	描述
`kind`	`string`
`title`	`string`
`detail`	`string \| null`
`git_sha`	`string \| null`
`issue_id`	`integer \| null`
`occurred_at`	`string \| null` (date-time)

响应

代码	描述
`201`	已保存的操作	SeoAction
`400`	请求体格式错误
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色或授权范围不足
`422`	未知的操作类型或无法解析的时间戳

示例请求

curl -X POST '/api/v1/seo/actions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"value","title":"value","detail":"value","git_sha":"value","issue_id":"value","occurred_at":"value"}'

logs

定时任务与邮件发送日志。只读，仅限具有 ROLE_ADMIN 的用户使用。

GET /api/v1/logs/cron 列出近期的定时任务运行日志

列出近期的定时任务运行日志

参数

名称	位置	类型	描述
`limit`	query	`integer`	默认值: `100`

响应

代码	描述
`200`	分页的定时任务日志列表	CronLogList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色权限不足

示例请求

curl '/api/v1/logs/cron?limit=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/logs/sendlog 列出邮件发送日志

列出邮件发送日志

参数

名称	位置	类型	描述
`limit`	query	`integer`	默认值: `100`

响应

代码	描述
`200`	分页的发送日志列表	SendlogList
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色权限不足

示例请求

curl '/api/v1/logs/sendlog?limit=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/logs/cron/{id} 获取单条定时任务日志

获取单条定时任务日志

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	定时任务日志详情	CronLogDetail
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色权限不足
`404`	未找到该定时任务日志

示例请求

curl '/api/v1/logs/cron/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/logs/sendlog/{id} 获取单条发送日志

获取单条发送日志

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	发送日志详情	SendlogDetail
`401`	缺少 Bearer 令牌或令牌无效
`403`	角色权限不足
`404`	未找到该发送日志

示例请求

curl '/api/v1/logs/sendlog/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

auth

使用邮箱和密码登录以获取个人访问令牌

POST /api/v1/auth/login 登录并获取个人访问令牌

登录并获取个人访问令牌

为此设备签发新的个人访问令牌，并撤销此前以相同设备名称登录时签发的令牌。每次调用都将其作为 Bearer 令牌发送，收到 401 时重新登录。

请求体

必填

内容类型: application/json

名称	类型	描述
`email`	`string` (email)
`password`	`string` (password)
`deviceName`	`string`	此安装的固定名称，会显示在成员的令牌列表中

响应

代码	描述
`200`	已登录	LoginResult
`400`	请求体格式错误或设备名称无效（bad_request、invalid_device_name）	ErrorResponse
`401`	邮箱或密码错误（invalid_credentials）	ErrorResponse
`403`	该账户尚不能或已不能登录（account_blocked、email_not_verified、pending_approval）；成员需在网站上处理	ErrorResponse
`429`	尝试次数过多（too_many_attempts，带 Retry-After）或登录保护已启用（login_restricted）；请在网站上登录	ErrorResponse

示例请求

curl -X POST '/api/v1/auth/login' \
  -H "Content-Type: application/json" \
  -d '{"email":"value","password":"value","deviceName":"value"}'

POST /api/v1/auth/logout 退出登录并撤销调用所用的令牌

退出登录并撤销调用所用的令牌

响应

代码	描述
`204`	令牌已撤销
`401`	缺少 Bearer 令牌或令牌无效

示例请求

curl -X POST '/api/v1/auth/logout' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

community

GET /api/v1/community/blocks 列出调用者已屏蔽的成员

列出调用者已屏蔽的成员

响应

代码	描述
`200`	已屏蔽的成员	MemberList
`401`	缺少 Bearer 令牌或令牌无效

示例请求

curl '/api/v1/community/blocks' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/community/members 列出平台成员

列出平台成员

调用成员可见的成员，已屏蔽者除外。选择不出现在目录中的成员同样不在此列出，与网站一致；其个人资料仍可通过 ID 访问。

参数

名称	位置	类型	描述
`limit`	query	`integer`	默认值: `20`
`offset`	query	`integer`	默认值: `0`

响应

代码	描述
`200`	成员	MemberList
`401`	缺少 Bearer 令牌或令牌无效

示例请求

curl '/api/v1/community/members?limit=1&offset=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/community/blocks/{id} 屏蔽成员

屏蔽成员

屏蔽会解除双向的关注关系，并在双方收件箱中隐藏该会话。重复调用是安全的。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`204`	已屏蔽
`401`	缺少 Bearer 令牌或令牌无效
`404`	成员不存在 (not_found)	ErrorResponse
`422`	屏蔽自己 (self_target)	ErrorResponse

示例请求

curl -X POST '/api/v1/community/blocks/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /api/v1/community/blocks/{id} 解除屏蔽成员

解除屏蔽成员

重复调用是安全的。解除屏蔽不会恢复因屏蔽而取消的关注关系。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`204`	未屏蔽
`401`	缺少 Bearer 令牌或令牌无效
`404`	成员不存在 (not_found)	ErrorResponse

示例请求

curl -X DELETE '/api/v1/community/blocks/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/community/members/{id} 读取单个成员资料

读取单个成员资料

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	成员资料	MemberProfile
`401`	缺少 Bearer 令牌或令牌无效
`403`	该成员已屏蔽调用者 (forbidden)	ErrorResponse
`404`	成员不存在 (not_found)	ErrorResponse

示例请求

curl '/api/v1/community/members/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/community/conversations 列出调用成员的会话

列出调用成员的会话

每位联系人一条记录，最新的在前。任一方向上被屏蔽的联系人不会出现。

参数

名称	位置	类型	描述
`limit`	query	`integer`	默认值: `20`
`offset`	query	`integer`	默认值: `0`

响应

代码	描述
`200`	会话	ConversationList
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 community:read 权限范围 (insufficient_scope)	ErrorResponse

示例请求

curl '/api/v1/community/conversations?limit=1&offset=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

PATCH /api/v1/community/messages/{id} 在编辑时限内修改消息

在编辑时限内修改消息

消息发出后十分钟内可以编辑。网站在此返回 403，本接口返回 409，因为时间窗口属于状态冲突而非授权失败。

参数

名称	位置	类型	描述
`id` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`content`	`string`

响应

代码	描述
`200`	已保存的消息	ThreadMessage
`401`	缺少 Bearer 令牌或令牌无效
`404`	消息不存在，或由他人发送 (not_found)	ErrorResponse
`409`	十分钟时限已过 (edit_window_expired)	ErrorResponse
`422`	content_required 或 content_too_long	ErrorResponse

示例请求

curl -X PATCH '/api/v1/community/messages/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"value"}'

POST /api/v1/community/members/{id}/follow 关注成员

关注成员

重复调用是安全的：它声明期望的最终状态，而不是来回切换。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`204`	已关注
`401`	缺少 Bearer 令牌或令牌无效
`404`	成员不存在 (not_found)	ErrorResponse
`409`	任一方向上存在屏蔽 (blocked)	ErrorResponse
`422`	关注自己 (self_target)	ErrorResponse

示例请求

curl -X POST '/api/v1/community/members/1/follow' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /api/v1/community/members/{id}/follow 取消关注成员

取消关注成员

重复调用是安全的。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`204`	未关注
`401`	缺少 Bearer 令牌或令牌无效
`404`	成员不存在 (not_found)	ErrorResponse

示例请求

curl -X DELETE '/api/v1/community/members/1/follow' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/community/groups/{slug}/members 列出某个群组的成员

列出某个群组的成员

同一列表，限定到某个群组。调用者无法访问的群组返回与未知 slug 相同的 404；访问私密或隐藏群组还需要令牌带有 me:read，因为成员关系通过该 scope 解析。

参数

名称	位置	类型	描述
`slug` *	path	`string`
`limit`	query	`integer`	默认值: `20`
`offset`	query	`integer`	默认值: `0`

响应

代码	描述
`200`	该群组的成员	MemberList
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到群组或无法访问 (not_found)	ErrorResponse

示例请求

curl '/api/v1/community/groups/slug/members?limit=1&offset=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/community/conversations/{userId} 读取单个会话

读取单个会话

按时间从旧到新。该读取不产生副作用：与在网站上打开页面不同，它不会把会话标记为已读。请改用 POST /api/v1/community/conversations/{userId}/read。

参数

名称	位置	类型	描述
`userId` *	path	`integer`
`limit`	query	`integer`	默认值: `20`
`offset`	query	`integer`	默认值: `0`

响应

代码	描述
`200`	会话内容	MessageThread
`401`	缺少 Bearer 令牌或令牌无效
`404`	成员不存在 (not_found)	ErrorResponse

示例请求

curl '/api/v1/community/conversations/1?limit=1&offset=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/community/conversations/{userId} 发送私信

发送私信

参数

名称	位置	类型	描述
`userId` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`content`	`string`

响应

代码	描述
`201`	已保存的消息	ThreadMessage
`401`	缺少 Bearer 令牌或令牌无效
`404`	成员不存在 (not_found)	ErrorResponse
`409`	任一方向上存在屏蔽 (blocked)	ErrorResponse
`422`	content_required、content_too_long 或 self_target	ErrorResponse

示例请求

curl -X POST '/api/v1/community/conversations/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"value"}'

POST /api/v1/community/conversations/{userId}/read 将会话标记为已读

将会话标记为已读

参数

名称	位置	类型	描述
`userId` *	path	`integer`

响应

代码	描述
`204`	已标记为已读
`401`	缺少 Bearer 令牌或令牌无效
`404`	成员不存在 (not_found)	ErrorResponse

示例请求

curl -X POST '/api/v1/community/conversations/1/read' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/community/groups/{slug}/town-hall/topics 列出一个群组的市政厅话题

列出一个群组的市政厅话题

该群组的完整论坛树，深度优先，与网站加载方式一致。不分页。没有市政厅的群组，或市政厅对调用者关闭的群组，返回 404 - 与未知 slug 的回答相同。

参数

名称	位置	类型	描述
`slug` *	path	`string`

响应

代码	描述
`200`	话题树	TopicList
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到群组、群组不可访问，或市政厅对调用者关闭（not_found）	ErrorResponse

示例请求

curl '/api/v1/community/groups/slug/town-hall/topics' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/community/groups/{slug}/town-hall/topics 新建话题或子话题

新建话题或子话题

参数

名称	位置	类型	描述
`slug` *	path	`string`

请求体

必填

内容类型: application/json

名称	类型	描述
`title`	`string`
`parentId`	`integer \| null`	在此话题下新建子话题。

响应

代码	描述
`201`	话题已创建	Topic
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到群组或父话题，或市政厅对调用者关闭（not_found）	ErrorResponse
`422`	empty_title、title_too_long 或 too_deep	ErrorResponse

示例请求

curl -X POST '/api/v1/community/groups/slug/town-hall/topics' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"value","parentId":"value"}'

GET /api/v1/community/groups/{slug}/town-hall/gallery 列出一个群组的市政厅相册

列出一个群组的市政厅相册

上传到该群组活动的照片，最新的在前，每张附带其活动。被会员举报的照片不会列出，与活动页面一致。

参数

名称	位置	类型	描述
`slug` *	path	`string`
`limit`	query	`integer`	默认值: `20`
`offset`	query	`integer`	默认值: `0`
`locale`	query	`string`	活动标题的语言

响应

代码	描述
`200`	一页照片	GalleryList
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到群组、群组不可访问，或市政厅对调用者关闭（not_found）	ErrorResponse

示例请求

curl '/api/v1/community/groups/slug/town-hall/gallery?limit=1&offset=1&locale=en' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /api/v1/community/groups/{slug}/town-hall/topics/{id} 删除话题

删除话题

作者可在话题没有子话题和回复时删除它；管理员删除时会连同整个子树一起删除。

参数

名称	位置	类型	描述
`slug` *	path	`string`
`id` *	path	`integer`

响应

代码	描述
`204`	话题已删除
`401`	缺少 Bearer 令牌或令牌无效
`403`	不允许删除（forbidden）	ErrorResponse
`404`	未找到群组或话题，或市政厅对调用者关闭（not_found）	ErrorResponse

示例请求

curl -X DELETE '/api/v1/community/groups/slug/town-hall/topics/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

PATCH /api/v1/community/groups/{slug}/town-hall/topics/{id} 重命名话题（作者或管理员）

重命名话题（作者或管理员）

参数

名称	位置	类型	描述
`slug` *	path	`string`
`id` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`title`	`string`

响应

代码	描述
`200`	话题已重命名	Topic
`401`	缺少 Bearer 令牌或令牌无效
`403`	既不是作者也不是管理员（forbidden）	ErrorResponse
`404`	未找到群组或话题，或市政厅对调用者关闭（not_found）	ErrorResponse
`422`	empty_title 或 title_too_long	ErrorResponse

示例请求

curl -X PATCH '/api/v1/community/groups/slug/town-hall/topics/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"value"}'

GET /api/v1/community/groups/{slug}/town-hall/topics/{id}/replies 列出话题的回复

列出话题的回复

最新的在前，与活动评论一样向前翻页：传入上一页的 nextBefore。

参数

名称	位置	类型	描述
`slug` *	path	`string`
`id` *	path	`integer`
`before`	query	`integer`	只返回早于此回复 ID 的回复
`limit`	query	`integer`	默认值: `20`

响应

代码	描述
`200`	一页回复	CommentList
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到群组或话题，或市政厅对调用者关闭（not_found）	ErrorResponse

示例请求

curl '/api/v1/community/groups/slug/town-hall/topics/1/replies?before=1&limit=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/community/groups/{slug}/town-hall/topics/{id}/replies 回复话题

回复话题

参数

名称	位置	类型	描述
`slug` *	path	`string`
`id` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`content`	`string`

响应

代码	描述
`201`	回复已创建	CommentCreated
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到群组或话题，或市政厅对调用者关闭（not_found）	ErrorResponse
`422`	content_required 或 content_too_long	ErrorResponse

示例请求

curl -X POST '/api/v1/community/groups/slug/town-hall/topics/1/replies' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"value"}'

DELETE /api/v1/community/groups/{slug}/town-hall/topics/{id}/replies/{replyId} 删除回复（自己的，或管理员）

删除回复（自己的，或管理员）

参数

名称	位置	类型
`slug` *	path	`string`
`id` *	path	`integer`
`replyId` *	path	`integer`

响应

代码	描述
`204`	回复已删除
`401`	缺少 Bearer 令牌或令牌无效
`403`	不是你的回复，也不是管理员（forbidden）	ErrorResponse
`404`	未找到群组、话题或回复，回复属于其他话题，或市政厅对调用者关闭（not_found）	ErrorResponse

示例请求

curl -X DELETE '/api/v1/community/groups/slug/town-hall/topics/1/replies/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

event-actions

已认证用户对活动的操作：报名、评论、上传图片

PUT /api/v1/events/{id}/rsvp 设置活动的出席状态与同行人数

设置活动的出席状态与同行人数

幂等：一次调用即可设置出席状态与同行人数，并返回最终状态。

参数

名称	位置	类型	描述
`id` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`going`	`boolean`
`guests`	`integer`	成员携带的同行人数，0 到 5；不参加时忽略

响应

代码	描述
`200`	最终的出席状态	RsvpResult
`401`	缺少 Bearer 令牌或令牌无效
`403`	不允许（not_a_member）	ErrorResponse
`404`	未找到该活动	ErrorResponse
`409`	活动已取消或已开始（event_canceled、event_started）	ErrorResponse
`400`	请求体不是对象，或 going 不是布尔值（bad_request）	ErrorResponse
`422`	携伴人数超出范围（validation_failed）	ErrorResponse

示例请求

curl -X PUT '/api/v1/events/1/rsvp' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"going":"value","guests":"value"}'

POST /api/v1/events/{id}/rsvp 报名参加活动

报名参加活动

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	报名已添加（或此前已报名）	RsvpResult
`401`	缺少 Bearer 令牌或令牌无效
`403`	不允许（小组成员资格／已被封禁）	ErrorResponse
`404`	未找到该活动	ErrorResponse
`409`	活动已取消或已开始	ErrorResponse

示例请求

curl -X POST '/api/v1/events/1/rsvp' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /api/v1/events/{id}/rsvp 取消活动报名

取消活动报名

取消报名永不会被拒绝：活动已取消、已开始或已失去群组成员身份，会员都仍可从参加名单中退出。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	报名已取消（或本就没有报名）	RsvpResult
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到该活动	ErrorResponse

示例请求

curl -X DELETE '/api/v1/events/1/rsvp' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/events/{id}/images 列出活动的照片

列出活动的照片

活动的照片，包含所有已生成的尺寸。被会员举报的照片不会列出，与活动页面一致。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	活动的照片	ImageList
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 event-actions:read 权限范围（insufficient_scope）	ErrorResponse
`404`	未找到活动，或调用方不可见（not_found）	ErrorResponse

示例请求

curl '/api/v1/events/1/images' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/events/{id}/images 向活动上传图片

向活动上传图片

参数

名称	位置	类型	描述
`id` *	path	`integer`

请求体

必填

内容类型: multipart/form-data

名称	类型	描述
`file`	`string` (binary)

响应

代码	描述
`201`	图片已上传	ImageUploaded
`400`	file_required、file_rejected 或 upload_failed	ErrorResponse
`401`	缺少 Bearer 令牌或令牌无效
`403`	不允许	ErrorResponse
`404`	未找到该活动	ErrorResponse

示例请求

curl -X POST '/api/v1/events/1/images' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@/path/to/file"

GET /api/v1/events/{id}/comments 列出活动的评论

列出活动的评论

最新的在前，与活动页面一致。传入上一页的 nextBefore 可翻到下一页。

参数

名称	位置	类型	描述
`id` *	path	`integer`
`before`	query	`integer`	仅早于该评论 ID 的评论
`limit`	query	`integer`	默认值: `25`

响应

代码	描述
`200`	一页评论	CommentList
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 event-actions:read 权限范围（insufficient_scope）	ErrorResponse
`404`	未找到活动，或调用方不可见（not_found）	ErrorResponse

示例请求

curl '/api/v1/events/1/comments?before=1&limit=1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/events/{id}/comments 在活动下发表评论

在活动下发表评论

参数

名称	位置	类型	描述
`id` *	path	`integer`

请求体

必填

内容类型: application/json

名称	类型	描述
`content`	`string`

响应

代码	描述
`201`	评论已创建	CommentCreated
`400`	content_required 或 content_too_long	ErrorResponse
`401`	缺少 Bearer 令牌或令牌无效
`403`	不允许	ErrorResponse
`404`	未找到该活动	ErrorResponse

示例请求

curl -X POST '/api/v1/events/1/comments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"value"}'

GET /api/v1/events/{id}/attendees 列出参加活动的人

列出参加活动的人

活动页面向已登录会员展示的参加者：已回复出席的人及其携带的客人，以及由主办方维护的外部人数。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	参加的人	AttendeeList
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 event-actions:read 权限范围（insufficient_scope）	ErrorResponse
`404`	未找到活动，或调用方不可见（not_found）	ErrorResponse

示例请求

curl '/api/v1/events/1/attendees' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/events/{id}/occurrences 列出周期性聚会的其他日期

列出周期性聚会的其他日期

同一系列中可见的近期活动，每个都带有调用方自己的出席状态。没有系列的活动只返回它自己。

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`200`	该系列的近期场次	EventList
`401`	缺少 Bearer 令牌或令牌无效
`404`	未找到该活动	ErrorResponse

示例请求

curl '/api/v1/events/1/occurrences' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /api/v1/events/{id}/images/{imageId} 删除活动图片（本人上传或管理员）

删除活动图片（本人上传或管理员）

参数

名称	位置	类型	描述
`id` *	path	`integer`
`imageId` *	path	`integer`

响应

代码	描述
`204`	图片已删除
`401`	缺少 Bearer 令牌或令牌无效
`403`	不是你的图片，且没有管理员权限	ErrorResponse
`404`	未找到图片或活动	ErrorResponse

示例请求

curl -X DELETE '/api/v1/events/1/images/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /api/v1/events/{id}/comments/{commentId} 删除活动评论（本人或管理员）

删除活动评论（本人或管理员）

参数

名称	位置	类型	描述
`id` *	path	`integer`
`commentId` *	path	`integer`

响应

代码	描述
`204`	评论已删除
`401`	缺少 Bearer 令牌或令牌无效
`403`	不是你的评论，且没有管理员权限	ErrorResponse
`404`	未找到评论或活动	ErrorResponse

示例请求

curl -X DELETE '/api/v1/events/1/comments/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

events

公开活动的列表与详情

GET /api/v1/events 列出公开的即将举行的活动

列出公开的即将举行的活动

参数

名称	位置	类型	描述
`locale`	query	`string`
`from`	query	`string` (date-time)	ISO-8601 下界（默认：当前时间）
`to`	query	`string` (date-time)	ISO-8601 上界
`limit`	query	`integer`	默认值: `20`
`offset`	query	`integer`	默认值: `0`
`group`	query	`string`	群组 slug；未知的 slug 返回空列表

响应

代码	描述
`200`	分页的活动列表	EventList

示例请求

curl '/api/v1/events?locale=en&from=value&to=value&limit=1&offset=1&group=weiqi-club'

GET /api/v1/events/{id} 按 ID 获取单个活动

按 ID 获取单个活动

参数

名称	位置	类型	描述
`id` *	path	`integer`
`locale`	query	`string`

响应

代码	描述
`200`	活动详情	EventDetail
`404`	未找到活动，或活动在当前上下文中不可见	ErrorResponse

示例请求

curl '/api/v1/events/1?locale=value'

group-admin

限定于单个小组的管理操作。需要在指定小组中拥有所有者或组织者角色，或拥有平台的 ROLE_ADMIN。

GET /api/v1/groups/{groupSlug}/admin/members 列出小组成员

列出小组成员

参数

名称	位置	类型	描述
`groupSlug` *	path	`string`

响应

代码	描述
`200`	成员列表	GroupMemberList
`401`	缺少 Bearer 令牌或令牌无效
`403`	调用者不是该小组的所有者或组织者
`404`	未找到该小组	ErrorResponse

示例请求

curl '/api/v1/groups/groupSlug/admin/members' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/groups/{groupSlug}/admin/settings 读取小组设置

读取小组设置

参数

名称	位置	类型	描述
`groupSlug` *	path	`string`

响应

代码	描述
`200`	小组设置	GroupSettings
`401`	缺少 Bearer 令牌或令牌无效
`403`	调用者不是该小组的所有者或组织者
`404`	未找到该小组	ErrorResponse

示例请求

curl '/api/v1/groups/weiqi-club/admin/settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

groups

租户小组（多站点）

GET /api/v1/groups 列出活跃的小组

列出活跃的小组

响应

代码	描述
`200`	小组概要数组	GroupList

示例请求

curl '/api/v1/groups'

GET /api/v1/groups/{groupSlug} 按 slug 获取小组

按 slug 获取小组

参数

名称	位置	类型	描述
`groupSlug` *	path	`string`

响应

代码	描述
`200`	小组详情	GroupDetail
`404`	未找到该小组	ErrorResponse

示例请求

curl '/api/v1/groups/groupSlug'

GET /api/v1/groups/{groupSlug}/cms 列出某个小组的 CMS 页面

列出某个小组的 CMS 页面

参数

名称	位置	类型	描述
`groupSlug` *	path	`string`
`language`	query	`string`	两位字母的语言代码。省略时使用每个条目的第一种可用语言；若指定的语言在该页面不存在，则回退到 “en”（或第一种可用语言）。

响应

代码	描述
`200`	CMS 页面列表	CmsPageList
`404`	未找到该小组	ErrorResponse

示例请求

curl '/api/v1/groups/weiqi-club/cms?language=en'

GET /api/v1/groups/{groupSlug}/cms/{cmsSlug} 按小组和 slug 获取 CMS 页面的元数据

按小组和 slug 获取 CMS 页面的元数据

参数

名称	位置	类型
`groupSlug` *	path	`string`
`cmsSlug` *	path	`string`
`language`	query	`string`

响应

代码	描述
`200`	CMS 页面元数据	CmsPage
`404`	未找到小组，或页面不存在／在此小组中不可见	ErrorResponse

示例请求

curl '/api/v1/groups/platform/cms/about?language=value'

me

已认证用户（令牌范围内的读取）

GET /api/v1/me 获取已认证用户的个人资料

获取已认证用户的个人资料

响应

代码	描述
`200`	用户资料	MeProfile
`401`	缺少 Bearer 令牌或令牌无效

示例请求

curl '/api/v1/me' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

PATCH /api/v1/me 编辑已登录会员的个人资料

编辑已登录会员的个人资料

只有请求体中出现的字段会被修改。姓名沿用网站规则：已保存且超出上限的姓名仍然有效，但修改后的姓名必须符合上限。

请求体

必填

内容类型: application/json

名称	类型	描述
`name`	`string`
`bio`	`string \| null`
`locale`	`string`	本平台已启用的语言之一
`public`	`boolean`

响应

代码	描述
`200`	已保存的个人资料	MeProfile
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:write 权限范围（insufficient_scope）	ErrorResponse
`422`	某个字段被拒绝（validation_failed）；errors 会列出：name_required、name_too_long、locale_not_enabled、bio_invalid、public_invalid	ValidationErrorResponse

示例请求

curl -X PATCH '/api/v1/me' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"value","bio":"value","locale":"value","public":"value"}'

GET /api/v1/me/rsvps 列出已认证用户即将参加的活动报名

列出已认证用户即将参加的活动报名

参数

名称	位置	类型	描述
`locale`	query	`string`	语言代码；优先于 Accept-Language

响应

代码	描述
`200`	用户已报名的即将举行的活动数组	MeRsvpList
`401`	缺少 Bearer 令牌或令牌无效

示例请求

curl '/api/v1/me/rsvps?locale=en' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/me/avatar 更换已登录会员的头像

更换已登录会员的头像

更换会员头像。与网站一致，之前的图片仍保留在会员自己的图库中。

请求体

必填

内容类型: multipart/form-data

名称	类型	描述
`file`	`string` (binary)

响应

代码	描述
`200`	带有新头像的个人资料	MeProfile
`400`	file_required、file_rejected 或 upload_failed	ErrorResponse
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:write 权限范围（insufficient_scope）	ErrorResponse

示例请求

curl -X POST '/api/v1/me/avatar' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@/path/to/file"

GET /api/v1/me/groups 列出已登录会员所在的群组

列出已登录会员所在的群组

该会员加入或申请加入的每个群组，包括已将其屏蔽的群组，并附上角色与成员状态。

响应

代码	描述
`200`	已登录会员的成员身份	MembershipList
`401`	缺少 Bearer 令牌或令牌无效

示例请求

curl '/api/v1/me/groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/me/events 列出已登录成员的近期聚会

列出已登录成员的近期聚会

成员所在群组的近期活动，加上其在别处已确认出席且可见的近期活动；包含已取消的活动并作标记。

参数

名称	位置	类型	描述
`from`	query	`string` (date-time)	ISO-8601 下界（默认：当前时间）
`limit`	query	`integer`	默认值: `20`
`offset`	query	`integer`	默认值: `0`
`locale`	query	`string`	语言代码；优先于 Accept-Language

响应

代码	描述
`200`	分页的活动列表	EventList
`401`	缺少 Bearer 令牌或令牌无效

示例请求

curl '/api/v1/me/events?from=value&limit=1&offset=1&locale=en' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/me/signal-token 为此设备签发通知信号令牌

为此设备签发通知信号令牌

为调用的应用设备签发第二个令牌，它只能读取 GET /api/v1/signal，有效期 90 天。再次请求会替换它，撤销该设备的应用令牌也会一并撤销它。

响应

代码	描述
`201`	信号令牌	SignalTokenResult
`400`	调用的令牌不是通过 API 登录签发的 (not_an_app_token)	ErrorResponse
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:write 权限范围（insufficient_scope）	ErrorResponse

示例请求

curl -X POST '/api/v1/me/signal-token' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/me/notifications 列出已认证成员的通知

列出已认证成员的通知

网站导航栏的通知铃，以数据形式提供。每一条都由与网站相同的提供者实时计算；不做任何存储，因此没有已读状态、没有历史记录，也没有游标。标签以请求的语言返回。

响应

代码	描述
`200`	通知铃	NotificationList
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:read 权限范围 (insufficient_scope)	ErrorResponse

示例请求

curl '/api/v1/me/notifications' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/v1/me/push-subscriptions 列出已注册的推送设备

列出已注册的推送设备

同时返回客户端订阅前所需的 VAPID 公钥，以及本平台是否已配置推送。

响应

代码	描述
`200`	已注册的设备	PushSubscriptionList
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:read 权限范围 (insufficient_scope)	ErrorResponse

示例请求

curl '/api/v1/me/push-subscriptions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/me/push-subscriptions 注册一台推送设备

注册一台推送设备

将 Web Push 端点注册到发起调用的令牌上，因此在 /profile/access-tokens 撤销该设备也会停止其推送。重复提交同一端点会将其转移到当前设备并返回 200。

请求体

必填

内容类型: application/json

名称	类型	描述
`endpoint`	`string`
`p256dh`	`string`
`auth`	`string`
`transport`	`string`

响应

代码	描述
`200`	已更新一个已知端点	PushSubscriptionEntry
`201`	端点已注册	PushSubscriptionEntry
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:write 权限范围（insufficient_scope）	ErrorResponse
`422`	validation_failed、endpoint_rejected 或 too_many_subscriptions	ValidationErrorResponse
`503`	本平台未配置 VAPID 密钥 (push_unavailable)	ErrorResponse

示例请求

curl -X POST '/api/v1/me/push-subscriptions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"value","p256dh":"value","auth":"value","transport":"value"}'

GET /api/v1/me/notification-settings 读取已认证成员的通知偏好设置

读取已认证成员的通知偏好设置

与成员在 /profile/config 中编辑的总开关和六个开关相同。

响应

代码	描述
`200`	当前存储的偏好设置	MeNotificationSettings
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:read 权限范围 (insufficient_scope)	ErrorResponse

示例请求

curl '/api/v1/me/notification-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

PATCH /api/v1/me/notification-settings 编辑已认证成员的通知偏好设置

编辑已认证成员的通知偏好设置

仅请求体中出现的键会被修改。写入通过与网站相同的服务完成，因此此处的更改会显示在 /profile/config 中。

请求体

必填

内容类型: application/json

响应

代码	描述
`200`	已保存的偏好设置	MeNotificationSettings
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:write 权限范围（insufficient_scope）	ErrorResponse
`422`	某个字段被拒绝（validation_failed）；errors 会列出：name_required、name_too_long、locale_not_enabled、bio_invalid、public_invalid	ValidationErrorResponse

示例请求

curl -X PATCH '/api/v1/me/notification-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/v1/me/push-subscriptions/{id} 移除一台推送设备

移除一台推送设备

移除一台已注册的设备。其他成员的记录返回 404 而非 403，以免该端点泄露某个 ID 是否存在。

参数

名称	位置	类型	描述
`id` *	path	`integer`	来自列表接口的订阅 ID

响应

代码	描述
`204`	已移除
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 me:write 权限范围（insufficient_scope）	ErrorResponse
`404`	该成员没有这台设备
`503`	本平台未配置 VAPID 密钥 (push_unavailable)	ErrorResponse

示例请求

curl -X DELETE '/api/v1/me/push-subscriptions/1' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

memberships

调用会员的群组成员身份：邀请、加入与退出

GET /api/v1/memberships/invitations 列出待处理的群组邀请

列出待处理的群组邀请

发给调用会员的邀请，其中因任一方向的屏蔽而隐藏的不会列出。

响应

代码	描述
`200`	待处理的邀请	InvitationList
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 memberships:read 权限范围（insufficient_scope）	ErrorResponse

示例请求

curl '/api/v1/memberships/invitations' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/memberships/groups/{slug} 加入已列出的群组，或提出申请

加入已列出的群组，或提出申请

此处只能加入在群组目录中列出的群组。隐藏群组需在其自有域名加入，私密群组仅可通过邀请加入，因此两者都返回 group_not_joinable。若群组需要审核，返回的成员身份为 pending。

参数

名称	位置	类型	描述
`slug` *	path	`string`

请求体

内容类型: application/json

名称	类型	描述
`platformMailConsent`	`boolean`	回答平台加入问题：平台是否可以发送公告与活动邮件

响应

代码	描述
`200`	由此产生的成员身份，已通过或待审核	Membership
`401`	缺少 Bearer 令牌或令牌无效
`404`	没有该群组（not_found）	ErrorResponse
`409`	group_not_joinable、blocked_in_group 或 platform_crossing_required	ErrorResponse

示例请求

curl -X POST '/api/v1/memberships/groups/slug' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platformMailConsent":"value"}'

DELETE /api/v1/memberships/groups/{slug} 退出群组

退出群组

与网站规则一致：最后一位拥有者不能退出，被屏蔽的成员也不能，平台群组只有在不再为其他成员身份所需时才可退出。

参数

名称	位置	类型	描述
`slug` *	path	`string`

响应

代码	描述
`204`	成员身份已结束
`401`	缺少 Bearer 令牌或令牌无效
`404`	没有该群组，或不是其成员（not_found）	ErrorResponse
`409`	last_owner、blocked_in_group 或 may_not_leave_platform	ErrorResponse

示例请求

curl -X DELETE '/api/v1/memberships/groups/slug' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

POST /api/v1/memberships/invitations/{id}/accept 接受群组邀请

接受群组邀请

接受后将以受邀角色确立成员身份。若该会员仍需加入平台群组，此接口返回 409 platform_crossing_required；请携带 platformMailConsent 重试以先回答该问题。

参数

名称	位置	类型	描述
`id` *	path	`integer`

请求体

内容类型: application/json

名称	类型	描述
`platformMailConsent`	`boolean`	回答平台加入问题：平台是否可以发送公告与活动邮件

响应

代码	描述
`200`	由此产生的成员身份	Membership
`401`	缺少 Bearer 令牌或令牌无效
`404`	该会员没有此邀请（invitation_not_found）	ErrorResponse
`409`	blocked_in_group、membership_rejected 或 platform_crossing_required	ErrorResponse

示例请求

curl -X POST '/api/v1/memberships/invitations/1/accept' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platformMailConsent":"value"}'

POST /api/v1/memberships/invitations/{id}/decline 拒绝群组邀请

拒绝群组邀请

参数

名称	位置	类型	描述
`id` *	path	`integer`

响应

代码	描述
`204`	邀请已拒绝
`401`	缺少 Bearer 令牌或令牌无效
`404`	该会员没有此邀请（invitation_not_found）	ErrorResponse

示例请求

curl -X POST '/api/v1/memberships/invitations/1/decline' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

signal

成员是否有新变化，但不透露具体内容

GET /api/v1/signal 成员是否有新变化

成员是否有新变化

一个不透明的值：当铃铛通知变化、成员已确认参加的活动被取消、改期或改地点、以及活动提醒到期时，它都会改变。它不透露任何其他信息，因此只能读取此部分的令牌可以存放在应用无法保护的地方。

响应

代码	描述
`200`	当前值	SignalState
`401`	缺少 Bearer 令牌或令牌无效
`403`	令牌缺少 signal:read 权限范围 (insufficient_scope)	ErrorResponse

示例请求

curl '/api/v1/signal' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

status

状态

GET /api/status 健康检查端点

健康检查端点

响应

代码	描述
`200`	服务运行正常	HealthStatus

示例请求

curl '/api/status'