社区开放 API

1. 社区的订阅方案必须包含 API 权限

这一步由社区所有者控制，不是集成方能自助完成的。方案需要同时满足：包含 API 访问能力，否则每次调用返回 22203；以及每日额度不为 0，否则每次调用返回 22204。

你不必靠撞错误来发现这一点：/capabilities/get 会直接告诉你，而且在上述两种情况下它仍然调得通。

2. 在社区后台创建密钥

社区后台 → 集成 → API Keys → 创建。密钥形如 mfk_ 加 64 位十六进制，完整值只在创建时展示一次，之后只能看到前缀。

创建时勾选的 scope 决定这把密钥能调哪些端点，之后无法修改；要换 scope 只能新建一把密钥并吊销旧的。

可选：给密钥配置 IP 白名单（单 IP 或 CIDR 段）。来源 IP 不在其中的请求会返回 10007——和密钥无效是同一个错误码，当一把昨天还能用的密钥换台机器就不行了的时候，这一点值得记住。

Scope 一览

所以老密钥调不了后来新增的端点——空间、成员以及签名 URL 读取。请重新签发一把并勾上这些 scope。这是有意的：没有人应该因为平台上线了一项新功能，就在不知情的情况下把成员目录交出去。

X-API-Key: mfk_xxx

Authorization: Bearer mfk_xxx

密钥本身即凭据——请只在服务端保存和使用。它既不该出现在浏览器代码里，也不该打进移动端包体：任何能读出它的人都可以以你的成员身份发帖。

• 所有端点一律 POST。没有 GET / PUT / DELETE——读取也是 POST。
• 请传 Content-Type: application/json。即使某个端点不需要任何参数，也要传一个空 JSON 对象。
• 所有 id 都是 hashid 字符串，例如 "kZ3mQ9x"——社区、用户、帖子、空间、媒体一律如此。数字 ID 会被拒绝。
• 出参时间为 RFC3339，例如 2026-08-18T10:00:00Z。
• 金额一律是以最小货币单位（分）计的整数。
• 可选的 Accept-Language 请求头（zh、en、ja、ko、es、fr、de、pt）会影响错误文案的语言。
• 社区由你的 API Key 反查得出。不要在路径或请求体里传 site id。

成功与失败共用同一层信封

{
  "code": 0,
  "msg": "success",
  "data": { }
}

curl -X POST https://api.mateflow.com/site_open_api/v1/capabilities/get \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" -d '{}'

# → data: {
#     "api_version": "v1",
#     "site_id": "kZ3mQ9x",
#     "scopes": ["site.read", "content.read"],
#     "api_access": true,
#     "quota_limit": 5000,     // -1 means unlimited
#     "quota_used": 128,
#     "quota_reset_at": "2026-09-15T00:00:00Z"
#   }

• 接受 id 列表的读接口上限为 50 条，所有分页端点的 limit 上限同样是 50。
• /space/feed/list 的游标编码跟随 sort，所以换 sort 就必须重置分页。问答空间会忽略 sort，改按 qa_sort 排序。新接入建议用 /space/feed/list 加 sort=top，而不是 /space/feed/top。
• 成员响应是一份收窄过的投影：id、username、display_name、avatar_url、status、role 与 created_at。邮箱永远不在返回字段里，即使你就是用邮箱查的——那个地址你本来就持有，而把每个成员的地址回显出去会让 /member/get 变成一次通讯录导出。lookup 只做精确匹配，未命中是正常成功而不是错误，所以命中与未命中在状态码和耗时上都无法区分。它也是全 API 里限流最严的一条。

• author_user_id

  新帖子以哪位成员的身份发布。该成员必须已属于本社区，否则返回 20303。

• actor_user_id

  执行编辑或删除的人。权限按这个人来判定——既不是作者、也不是管理员就会返回 10004。

• viewer_user_id

  读取时可选。以该成员的视角返回结果：私密空间可见性、点赞与收藏状态等。不传即匿名视角，只能看到公开内容。

• 信息流和列表接口会连同 next_cursor 一起返回结果。把 next_cursor 原样回传即可翻到下一页；next_cursor 为空表示已经到底。
• 所有接口的 limit 上限都是 50。
• /space/feed/list 的游标里编码了当前的 sort。翻页途中改 sort 会让游标失效——请退回第一页重新开始。

• idempotency_key 在所有写接口都必填，长度不超过 190 字符。同一个 key 重复调用不会产生第二条帖子。
• 它的作用域是「社区 + 请求类型 + 幂等键」，与你用的是哪把 API Key 无关：同一社区的两把不同密钥，用同一个 idempotency_key 调同一个端点，第二次会命中第一次的结果。
• 同一个 key 配不同的请求体会返回一个稳定的冲突错误，而不会被静默当成一次成功的重试。
• 请求超时后重试，请复用同一个 key，绝不要换新的。

• scheduled_at 是 i64 Unix 秒时间戳——不是其他所有时间字段用的 RFC3339 字符串。
• 在 /post/update 里省略 scheduled_at 表示保持既有排期不变，它不是「清空」。

1. 通过 /media/get_token 用 API Key 换一个短期上传令牌。
2. 以 multipart 形式把文件 POST 给媒体服务，令牌放在字面名为 "token" 的请求头里，file_cate 取 Media、Avatar、Header、Audio 或 File 之一。
3. 发帖时把返回的媒体 id 传进 media_ids。

# 1. Exchange the API key for a short-lived upload token.
#    Since 2026-09 a token with no explicit scope is upload-only.
curl -X POST https://api.mateflow.com/site_open_api/v1/media/get_token \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id": "kZ3mQ9x", "scope": "upload"}'

# 2. Upload the file to the media service (token goes in a "token" header)
curl -X POST https://media.mateflow.com/api/v1/media/upload \
  -H "token: <token from step 1>" \
  -F "file_cate=Media" -F "file=@photo.jpg"

# 3. Attach the media id when creating the post
curl -X POST https://api.mateflow.com/site_open_api/v1/post/create \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id":"kZ3mQ9x","idempotency_key":"6f1c...","body":"Hi","media_ids":["m8Yq2Lp"]}'

私有媒体通过 /media/get_signed_urls 读取，它接受 items 与 access_level（1 公开 / 2 半私有 / 3 私有），返回带过期时间的 URL。请按需签发而不要落库保存，否则它们会开始返回 403。

给帖子附加媒体

• 要么传 medias——一组 media_id 与 alt 的组合——要么传 media_ids，即一个纯 id 列表。两个同传会返回 10005。
• alt 可选。传空串表示清空已有的替代文本；不传该字段表示保持原样。

错误响应会带上 request_id。报告问题时请附上它——我们靠它在日志里定位你那一次具体调用。

套餐类错误带有结构化元数据

两个套餐类错误都会带上足以告诉社区所有者该怎么做的信息，所以你可以给出一条真正有用的提示，而不是「出错了」。

// The plan does not include API access
{
  "code": 22203,
  "msg": "...",
  "request_id": "00de5640-8ae5-4a71-aef8-2f2cab0ce8a7",
  "data": {
    "error_code": "feature_not_available",
    "feature": "api_access",
    "required_plan": "Growth"
  }
}

// The community is out of daily quota
{
  "code": 22204,
  "data": {
    "error_code": "quota_exceeded",
    "resource": "api_requests_per_day",
    "current": "5001",
    "limit": "5000",
    "required_plan": "Business"
  }
}

日配额统计的是通过鉴权的请求，UTC 零点重置，并在 data.limit 里给出实际生效的上限——包括平台为该社区单独放宽的额度。计数器后端异常时会放行而不是拒绝，所以偶发的少计不代表配额失效了。

按密钥的突发预算（2026 年 9 月新增）

此前唯一的桶是按 IP 的：同一出口地址背后的多个客户会互相挤占，而分散在多个地址的调用方几乎不受约束。现在预算按密钥分级——密钥才是社区所有者签发、可轮换、并需要为之负责的那个东西。

member/lookup 明显更严，是出于安全而非容量。它的其他约束都在限制「单次回答泄露多少」，只有这一条限制「能问多少次」——而后者才是把查询变成通讯录抓取的那一步。按它被设计的用法，即以人的节奏解析你已经持有的地址，每分钟十次绰绰有余。

• 超限返回 HTTP 429 与 code 10202，并带上 Retry-After 以及 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 响应头。
• 请把这些数字当作起点而不是实测值——它们会依据观测到的流量调整。不要把它们写死进重试逻辑，认 429 与 Retry-After 即可。整套限流默认关闭，会先以观察模式运行一段时间再启用。
• 无论如何都请实现 429 退避，并把读取流量控制在大约每秒 10 次以内。

请用 event_id 去重。你已经处理成功但响应太慢的那一次，重试到达时 delivery_id 是新的、event_id 不变。同一个事件同时投给自定义 Webhook 和 Zap 时，两边看到的 event_id 也相同，可以对齐。

投递是至少一次的，并且可能乱序。收到重复、以及收到迟到的旧事件，都是正常的；接收方需要自己做幂等。

• 社区由你的 API Key 反查得出。不要在路径或请求体里传 site id。
• scope 在密钥创建时即固定。要修改只能新建一把密钥并吊销旧的。
• 请把 API 密钥保存在服务端。放进客户端代码，等于让任何能读到它的人以你的成员身份发帖。
• OpenAPI 契约覆盖全部路径与 schema。有一处需要注意：生成它的工具不会输出请求体的 required，所以必填字段请以本页为准，而不是以 spec 为准。