v1.0.0 OpenAPI 3.1.0

MeetAgain API

以编程方式访问公开活动、成员相关操作（报名、评论、上传图片）以及管理员范围的读取。非公开端点需使用个人访问令牌（PAT）认证。

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

身份验证

个人访问令牌

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

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

Header： Authorization: Bearer mapat_...

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

admin

通过 API 进行的平台管理操作。仅限具有 ROLE_ADMIN 的用户使用。

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

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

参数

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

响应

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

示例请求

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

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

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

参数

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

响应

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

示例请求

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

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

列出检测到的 SEO 问题

参数

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

响应

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

示例请求

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

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

列出最近记录的 SEO 操作

参数

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

响应

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

示例请求

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

POST /api/v1/admin/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/admin/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"}'

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

列出邮件发送日志

参数

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

响应

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

示例请求

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

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

获取单条定时任务日志

参数

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

响应

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

示例请求

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

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

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

参数

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

请求体

必填

内容类型: application/json

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

响应

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

示例请求

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

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

获取单条发送日志

参数

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

响应

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

示例请求

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

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

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

参数

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

响应

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

示例请求

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

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

列出近期安全事件

参数

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

响应

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

示例请求

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

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

输出原图的缩小预览

参数

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

响应

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

示例请求

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

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

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

参数

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

响应

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

示例请求

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

event-actions

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

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

报名参加活动

响应

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

示例请求

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

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

取消活动报名

响应

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

示例请求

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

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

向活动上传图片

请求体

必填

内容类型: multipart/form-data

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

响应

代码	描述
`201`	图片已上传	ImageUploaded
`400`	没有文件或格式不受支持	ErrorResponse
`401`	缺少 Bearer 令牌或令牌无效
`403`	不允许
`404`	未找到该活动

示例请求

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

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

在活动下发表评论

请求体

必填

内容类型: application/json

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

响应

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

示例请求

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

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

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

响应

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

示例请求

curl -X DELETE '/api/v1/events/{id}/images/{imageId}' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

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

响应

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

示例请求

curl -X DELETE '/api/v1/events/{id}/comments/{commentId}' \
  -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`

响应

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

示例请求

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

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"

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

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

响应

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

示例请求

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

status

状态

GET /api/status 健康检查端点

健康检查端点

响应

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

示例请求

curl '/api/status'