コミュニティ Open API

1. コミュニティのプランに API アクセスが含まれていること

これを決めるのは連携する側ではなくコミュニティオーナーです。プランには API アクセス機能が必要で、なければすべての呼び出しが 22203 を返します。さらに日次割り当てが 0 でないことも必要で、0 ならすべての呼び出しが 22204 を返します。

エラーを集めて突き止める必要はありません。/capabilities/get が直接答えますし、その 2 つの状態でも動きます。

2. コミュニティ管理画面でキーを作る

コミュニティ管理画面 → インテグレーション → API Keys → 作成。キーは mfk_ に 64 桁の 16 進数が続く形式で、全体が表示されるのは作成時の 1 回だけ。それ以降は先頭のプレフィックスしか見えません。

作成時に選んだスコープが、そのキーで呼べるエンドポイントを決めます。後から編集はできません。変更するには新しいキーを作り、古いものを失効させてください。

任意で、キーを IP 許可リスト（単一アドレスまたは CIDR）に限定できます。それ以外からのリクエストは 10007 で失敗します——無効なキーと同じコードなので、昨日まで動いていたキーが別のホストから動かなくなったときに思い出す価値があります。

スコープ

したがって古いキーでは新しいエンドポイント——スペース、メンバー、署名付き URL の読み取り——を呼べません。必要なスコープを選んで新しいキーを発行してください。これは意図的な仕様です。プラットフォームが新機能を出したからといって、知らないうちにメンバー名簿が渡されてよいはずがありません。

X-API-Key: mfk_xxx

Authorization: Bearer mfk_xxx

キーはそれ自体が資格情報です——サーバー側に保管してください。ブラウザのコードにもモバイルアプリのバンドルにも置いてはいけません。読み取れる人は誰でも、あなたのメンバーとして投稿できてしまいます。

• すべてのエンドポイントは POST です。GET・PUT・DELETE はありません——読み取りも POST です。
• Content-Type: application/json を送ってください。パラメーターを取らないエンドポイントでも、空の JSON ボディが必要です。
• すべての id は "kZ3mQ9x" のような hashid 文字列です——コミュニティ・ユーザー・投稿・スペース・メディアいずれも同様。数値 id は拒否されます。
• タイムスタンプは RFC3339 で返ります。例: 2026-08-18T10:00:00Z。
• 金額は最小通貨単位（セント）の整数です。
• 任意の Accept-Language ヘッダー（zh, en, ja, ko, es, fr, de, pt）でエラーメッセージが各言語になります。
• コミュニティは API キーから導かれます。パスにもボディにもサイト 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 を変えたらページネーションをやり直す必要があります。Q&A スペースは sort を無視し、代わりに qa_sort で並びます。新規の連携では /space/feed/top ではなく /space/feed/list に sort=top を渡してください。
• メンバーのレスポンスは絞り込まれた投影です。id、username、display_name、avatar_url、status、role、created_at のみ。メールで検索した場合でも、メールアドレスは返りません——そのアドレスは既に手元にあるはずですし、全員分を返せば /member/get は連絡先のエクスポートになってしまいます。検索は完全一致のみで、見つからないのはエラーではなく正常な成功なので、ヒットとミスはステータスコードでも所要時間でも区別できません。レート制限もこの 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 文字までです。同じものを再利用しても 2 つ目の投稿が作られることはありません。
• そのスコープはコミュニティとリクエスト種別とキーの組み合わせで、どの API キーを使ったかには依存しません。同じコミュニティの別々の 2 つのキーが同じ idempotency_key を同じエンドポイントに送った場合、2 回目は 1 回目の結果を返します。
• 同じキーで異なるボディを送ると、成功したリトライとして黙って通るのではなく、安定した競合エラーが返ります。
• リクエストがタイムアウトしたら同じキーで再試行してください——決して新しいキーを生成しないこと。

• scheduled_at は秒単位の i64 Unix タイムスタンプです——他のすべての時刻が使う RFC3339 文字列ではありません。
• /post/update で scheduled_at を省略すると、既存の予約はそのまま残ります。クリアではありません。

1. /media/get_token で API キーを短命のアップロードトークンと交換します。
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 を返し始めます。

投稿にメディアを添付する

• media_id と alt の組のリストである medias か、id だけのリストである media_ids のどちらかを送ってください。両方を送ると 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 0 時にリセットされ、実際に効いている上限を data.limit で返します——そのコミュニティのために個別に引き上げられた枠も含みます。カウンターのバックエンドに不調があった場合は拒否ではなく通過させるので、たまに数え漏れても割り当てが機能しなくなったわけではありません。

キー単位のバースト予算（2026 年 9 月に追加）

以前は IP 単位のバケツしかなく、1 つの出口アドレスの背後にいる複数の顧客が互いに枠を奪い合う一方、多数のアドレスに分散した呼び出し元はほとんど制約を受けませんでした。今は予算がキー単位で段階付けされます——キーこそコミュニティオーナーが発行し、ローテーションでき、責任を持つ対象だからです。

member/lookup が格段に厳しいのは、容量ではなくセキュリティ上の理由です。ほかの制約は「1 回の回答がどれだけ明かすか」を制限しますが、これだけは「何回聞けるか」を制限します——検索を名簿の収集に変えるのは、まさにその一歩だからです。設計どおりの使い方、つまり既に手元にあるアドレスを人間のペースで解決する用途なら、1 分に 10 回で十分すぎます。

• 超過すると 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 で再び届きます。1 つのイベントがカスタム Webhook と Zap の両方に送られる場合も、双方が同じ event_id を見るので突き合わせられます。

配信は at-least-once で、順序が入れ替わることがあります。重複も、古いイベントの遅着もどちらも正常です。受信側が冪等である必要があります。

• コミュニティは API キーから導かれます。パスにもボディにもサイト id を送らないでください。
• スコープはキーの作成時に固定されます。変更するには新しいキーを作り、古いものを失効させてください。
• API キーはサーバー側に置いてください。クライアントコードに置けば、読み取れる人は誰でもあなたのメンバーとして投稿できます。
• OpenAPI 契約はすべてのパスとスキーマを網羅します。1 点だけ注意: 生成元のツールはリクエストボディの required を出力しないため、必須フィールドは仕様ファイルではなくこのページを参照してください。