{"openapi":"3.0.0","info":{"title":"兽展日历 Open API","version":"1.0.0","description":"公开接口文档试点。调用业务接口需要具有 read 权限的应用令牌。"},"servers":[{"url":"https://api.furrycons.cn","description":"生产环境"}],"components":{"securitySchemes":{"applicationToken":{"type":"http","scheme":"bearer","description":"应用访问令牌，需要 read 权限；用户登录令牌不能用于这些接口。"}},"schemas":{"OpenEventPageDto":{"type":"object","properties":{"total":{"type":"number","example":1},"current":{"type":"number","example":1},"pageSize":{"type":"number","example":20},"data":{"type":"array","items":{"$ref":"#/components/schemas/OpenEventDto"},"example":[{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e11","name":"示例兽聚 2026","scale":"medium","status":"scheduled","slug":"sample-con-2026","urlKey":"a1b2c3d","eventKey":"sample-con-2026-a1b2c3d","startDate":"2026-08-01T02:00:00.000Z","endDate":"2026-08-02T10:00:00.000Z","address":"上海市浦东新区示例路 1 号","region":"上海","thumbnail":"https://images.furrycons.cn/event/cover.png","detail":"活动说明示例。","url":"https://www.furrycons.cn/event/sample-con-2026-a1b2c3d","place":{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e22","name":"示例会展中心","kind":"venue","address":"上海市浦东新区示例路 1 号"},"organization":{"name":"示例主办","slug":"sample-org","logoUrl":"https://images.furrycons.cn/organization/logo.png","url":"https://www.furrycons.cn/sample-org"}}]},"info":{"type":"string","description":"列表查询失败时可能返回 No event available 和空数据","example":"No event available"}},"required":["total","current","pageSize","data"]},"OpenEventDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e11"},"name":{"type":"string","example":"示例兽聚 2026"},"scale":{"type":"string","enum":["cosy","small","medium","large","xlarge","xxlarge","mega"],"example":"medium"},"status":{"type":"string","enum":["cancelled","movedOnline","postponed","rescheduled","scheduled"],"example":"scheduled"},"slug":{"type":"string","example":"sample-con-2026"},"urlKey":{"type":"string","example":"a1b2c3d"},"eventKey":{"type":"string","example":"sample-con-2026-a1b2c3d"},"startDate":{"type":"string","nullable":true,"format":"date-time","example":"2026-08-01T02:00:00.000Z"},"endDate":{"type":"string","nullable":true,"format":"date-time","example":"2026-08-02T10:00:00.000Z"},"address":{"type":"string","nullable":true,"example":"上海市浦东新区示例路 1 号"},"region":{"type":"string","nullable":true,"example":"上海"},"thumbnail":{"type":"string","nullable":true,"example":"https://images.furrycons.cn/event/cover.png"},"detail":{"type":"string","nullable":true,"example":"活动说明示例。"},"url":{"type":"string","nullable":true,"example":"https://www.furrycons.cn/event/sample-con-2026-a1b2c3d"},"place":{"anyOf":[{"$ref":"#/components/schemas/OpenEventPlaceDto"},{"type":"object","nullable":true,"enum":[null]}]},"organization":{"anyOf":[{"$ref":"#/components/schemas/OpenEventOrganizationDto"},{"type":"object","nullable":true,"enum":[null]}]}},"required":["id","name","scale","status","slug","urlKey","eventKey","startDate","endDate","address","region","thumbnail","detail","url","place","organization"]},"OpenEventPlaceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e22"},"name":{"type":"string","example":"示例会展中心"},"kind":{"type":"string","example":"venue"},"address":{"type":"string","nullable":true,"example":"上海市浦东新区示例路 1 号"}},"required":["id","name","kind","address"]},"OpenEventOrganizationDto":{"type":"object","properties":{"name":{"type":"string","nullable":true,"example":"示例主办"},"slug":{"type":"string","nullable":true,"example":"sample-org"},"logoUrl":{"type":"string","nullable":true,"example":"https://images.furrycons.cn/organization/logo.png"},"url":{"type":"string","nullable":true,"example":"https://www.furrycons.cn/sample-org"}},"required":["name","slug","logoUrl","url"]},"ApiErrorDto":{"type":"object","properties":{"message":{"type":"string","example":"未登录或登录已过期"},"code":{"type":"string","example":"E_UNAUTHORIZED"},"params":{"type":"object","additionalProperties":true,"example":{"retryAfter":60}}},"required":["message","code"]},"ValidationErrorDto":{"type":"object","properties":{"message":{"type":"string","example":"参数校验失败"},"code":{"type":"string","example":"E_VALIDATION"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssueDto"},"example":[{"field":"id","rule":"uuid","message":"id 必须是有效的 UUID"}]}},"required":["message","code","errors"]},"ValidationIssueDto":{"type":"object","properties":{"field":{"type":"string","example":"id"},"rule":{"type":"string","example":"uuid"},"message":{"type":"string","example":"id 必须是有效的 UUID"},"meta":{"type":"object","additionalProperties":true}},"required":["field","rule","message"]},"OpenOrganizationDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e33"},"slug":{"type":"string","example":"sample-org"},"name":{"type":"string","example":"示例主办"},"description":{"type":"string","nullable":true,"example":"示例主办方简介。"},"status":{"type":"string","example":"active"},"type":{"type":"string","nullable":true,"example":"agency"},"logoUrl":{"type":"string","nullable":true,"example":"https://images.furrycons.cn/organization/logo.png"},"richMediaConfig":{"type":"object","additionalProperties":true,"nullable":true,"example":{}},"contactMail":{"type":"string","nullable":true,"example":"info@example.com"},"website":{"type":"string","nullable":true,"example":"https://example.com"},"twitter":{"type":"string","nullable":true,"example":"https://twitter.com/example"},"weibo":{"type":"string","nullable":true,"example":"https://weibo.com/example"},"qqGroup":{"type":"string","nullable":true,"example":"123456789"},"bilibili":{"type":"string","nullable":true,"example":"https://space.bilibili.com/1"},"rednote":{"type":"string","nullable":true,"example":"https://www.xiaohongshu.com/user/profile/example"},"wikifur":{"type":"string","nullable":true,"example":"https://en.wikifur.com/wiki/Example"},"facebook":{"type":"string","nullable":true,"example":"https://www.facebook.com/example"},"plurk":{"type":"string","nullable":true,"example":"https://www.plurk.com/example"},"extra":{"type":"object","additionalProperties":true,"example":{}},"creationTime":{"type":"string","nullable":true,"format":"date-time","example":"2018-06-01T00:00:00.000Z"}},"required":["id","slug","name","description","status","type","logoUrl","richMediaConfig","contactMail","website","twitter","weibo","qqGroup","bilibili","rednote","wikifur","facebook","plurk","extra","creationTime"]}}},"paths":{"/open/event":{"get":{"operationId":"listOpenEvents","summary":"查询活动列表","tags":["活动"],"responses":{"200":{"description":"分页活动列表；查询失败时可能返回空列表与 info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenEventPageDto"},"examples":{"result":{"summary":"有数据","value":{"total":1,"current":1,"pageSize":20,"data":[{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e11","name":"示例兽聚 2026","scale":"medium","status":"scheduled","slug":"sample-con-2026","urlKey":"a1b2c3d","eventKey":"sample-con-2026-a1b2c3d","startDate":"2026-08-01T02:00:00.000Z","endDate":"2026-08-02T10:00:00.000Z","address":"上海市浦东新区示例路 1 号","region":"上海","thumbnail":"https://images.furrycons.cn/event/cover.png","detail":"活动说明示例。","url":"https://www.furrycons.cn/event/sample-con-2026-a1b2c3d","place":{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e22","name":"示例会展中心","kind":"venue","address":"上海市浦东新区示例路 1 号"},"organization":{"name":"示例主办","slug":"sample-org","logoUrl":"https://images.furrycons.cn/organization/logo.png","url":"https://www.furrycons.cn/sample-org"}}]}},"empty":{"summary":"查询失败","value":{"info":"No event available","total":0,"current":1,"pageSize":20,"data":[]}}}}}},"401":{"description":"应用令牌缺失或无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"未登录或登录已过期","code":"E_UNAUTHORIZED"}}}},"403":{"description":"应用没有 read 权限或没有接口访问权限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"当前应用没有权限","code":"E_APPLICATION_FORBIDDEN"}}}},"422":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorDto"},"example":{"message":"参数校验失败","code":"E_VALIDATION","errors":[{"field":"id","rule":"uuid","message":"id 必须是有效的 UUID"}]}}}},"429":{"description":"请求频率超限；Retry-After 响应头给出等待秒数","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"请求过于频繁，请 60 秒后再试","code":"E_TOO_MANY_REQUESTS","params":{"retryAfter":60}}}}},"500":{"description":"服务器错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"服务器内部错误","code":"E_INTERNAL"}}}}},"parameters":[{"in":"query","name":"eventStartAt","required":false,"description":"活动开始时间下限，UTC 时间","schema":{"type":"string","format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$"}},{"in":"query","name":"eventEndAt","required":false,"description":"活动结束时间上限，UTC 时间","schema":{"type":"string","format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$"}},{"in":"query","name":"search","required":false,"description":"活动名称关键词","schema":{"type":"string"}},{"in":"query","name":"orgSearch","required":false,"description":"组织名称关键词","schema":{"type":"string"}},{"in":"query","name":"current","required":false,"schema":{"type":"number","default":1}},{"in":"query","name":"pageSize","required":false,"schema":{"type":"number","default":20}}],"security":[{"applicationToken":[]}]}},"/open/event/recent":{"get":{"operationId":"listRecentOpenEvents","summary":"查询近期活动","description":"查询从今天起 30 天内开始的 scheduled 活动，第一页最多 10 条；keepOld=true 且结果为空时改查已结束的 scheduled 活动。日期边界按服务器时区计算。","tags":["活动"],"responses":{"200":{"description":"近期活动列表","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenEventPageDto"},"example":{"total":1,"current":1,"pageSize":20,"data":[{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e11","name":"示例兽聚 2026","scale":"medium","status":"scheduled","slug":"sample-con-2026","urlKey":"a1b2c3d","eventKey":"sample-con-2026-a1b2c3d","startDate":"2026-08-01T02:00:00.000Z","endDate":"2026-08-02T10:00:00.000Z","address":"上海市浦东新区示例路 1 号","region":"上海","thumbnail":"https://images.furrycons.cn/event/cover.png","detail":"活动说明示例。","url":"https://www.furrycons.cn/event/sample-con-2026-a1b2c3d","place":{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e22","name":"示例会展中心","kind":"venue","address":"上海市浦东新区示例路 1 号"},"organization":{"name":"示例主办","slug":"sample-org","logoUrl":"https://images.furrycons.cn/organization/logo.png","url":"https://www.furrycons.cn/sample-org"}}]}}}},"401":{"description":"应用令牌缺失或无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"未登录或登录已过期","code":"E_UNAUTHORIZED"}}}},"403":{"description":"应用没有 read 权限或没有接口访问权限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"当前应用没有权限","code":"E_APPLICATION_FORBIDDEN"}}}},"422":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorDto"},"example":{"message":"参数校验失败","code":"E_VALIDATION","errors":[{"field":"id","rule":"uuid","message":"id 必须是有效的 UUID"}]}}}},"429":{"description":"请求频率超限；Retry-After 响应头给出等待秒数","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"请求过于频繁，请 60 秒后再试","code":"E_TOO_MANY_REQUESTS","params":{"retryAfter":60}}}}},"500":{"description":"服务器错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"服务器内部错误","code":"E_INTERNAL"}}}}},"parameters":[{"in":"query","name":"keepOld","required":false,"description":"只有字符串 true 才启用已结束活动回退","example":"true","schema":{"type":"string"}}],"security":[{"applicationToken":[]}]}},"/open/event/{id}":{"get":{"operationId":"getOpenEvent","summary":"查询活动详情","tags":["活动"],"responses":{"200":{"description":"公开活动详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenEventDto"},"example":{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e11","name":"示例兽聚 2026","scale":"medium","status":"scheduled","slug":"sample-con-2026","urlKey":"a1b2c3d","eventKey":"sample-con-2026-a1b2c3d","startDate":"2026-08-01T02:00:00.000Z","endDate":"2026-08-02T10:00:00.000Z","address":"上海市浦东新区示例路 1 号","region":"上海","thumbnail":"https://images.furrycons.cn/event/cover.png","detail":"活动说明示例。","url":"https://www.furrycons.cn/event/sample-con-2026-a1b2c3d","place":{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e22","name":"示例会展中心","kind":"venue","address":"上海市浦东新区示例路 1 号"},"organization":{"name":"示例主办","slug":"sample-org","logoUrl":"https://images.furrycons.cn/organization/logo.png","url":"https://www.furrycons.cn/sample-org"}}}}},"401":{"description":"应用令牌缺失或无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"未登录或登录已过期","code":"E_UNAUTHORIZED"}}}},"403":{"description":"应用没有 read 权限或没有接口访问权限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"当前应用没有权限","code":"E_APPLICATION_FORBIDDEN"}}}},"404":{"description":"活动不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"未找到该活动","code":"E_EVENT_NOT_FOUND"}}}},"422":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorDto"},"example":{"message":"参数校验失败","code":"E_VALIDATION","errors":[{"field":"id","rule":"uuid","message":"id 必须是有效的 UUID"}]}}}},"429":{"description":"请求频率超限；Retry-After 响应头给出等待秒数","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"请求过于频繁，请 60 秒后再试","code":"E_TOO_MANY_REQUESTS","params":{"retryAfter":60}}}}},"500":{"description":"服务器错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"服务器内部错误","code":"E_INTERNAL"}}}}},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"applicationToken":[]}]}},"/open/organization/{id}":{"get":{"operationId":"getOpenOrganization","summary":"查询组织详情","tags":["组织"],"responses":{"200":{"description":"公开组织详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenOrganizationDto"},"example":{"id":"018f6b3e-8a10-7c3d-8e2b-4f6a8c0d1e33","slug":"sample-org","name":"示例主办","description":"示例主办方简介。","status":"active","type":"agency","logoUrl":"https://images.furrycons.cn/organization/logo.png","richMediaConfig":{},"contactMail":"info@example.com","website":"https://example.com","twitter":"https://twitter.com/example","weibo":"https://weibo.com/example","qqGroup":"123456789","bilibili":"https://space.bilibili.com/1","rednote":"https://www.xiaohongshu.com/user/profile/example","wikifur":"https://en.wikifur.com/wiki/Example","facebook":"https://www.facebook.com/example","plurk":"https://www.plurk.com/example","extra":{},"creationTime":"2018-06-01T00:00:00.000Z"}}}},"401":{"description":"应用令牌缺失或无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"未登录或登录已过期","code":"E_UNAUTHORIZED"}}}},"403":{"description":"应用没有 read 权限或没有接口访问权限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"当前应用没有权限","code":"E_APPLICATION_FORBIDDEN"}}}},"404":{"description":"组织不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"未找到该组织，请检查 id","code":"E_ORGANIZATION_NOT_FOUND"}}}},"422":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorDto"},"example":{"message":"参数校验失败","code":"E_VALIDATION","errors":[{"field":"id","rule":"uuid","message":"id 必须是有效的 UUID"}]}}}},"429":{"description":"请求频率超限；Retry-After 响应头给出等待秒数","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"请求过于频繁，请 60 秒后再试","code":"E_TOO_MANY_REQUESTS","params":{"retryAfter":60}}}}},"500":{"description":"服务器错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorDto"},"example":{"message":"服务器内部错误","code":"E_INTERNAL"}}}}},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"applicationToken":[]}]}}}}