커뮤니티 오픈 API

1. 커뮤니티 플랜에 API 접근이 포함되어야 합니다

이것은 연동하는 쪽이 아니라 커뮤니티 소유자가 결정합니다. 플랜에 API 접근 기능이 있어야 하고, 없으면 모든 호출이 22203을 반환합니다. 또한 일일 할당량이 0이 아니어야 하며, 0이면 모든 호출이 22204를 반환합니다.

오류를 모아 알아낼 필요는 없습니다. /capabilities/get이 바로 답해 주며, 그 두 상태에서도 동작합니다.

2. 커뮤니티 관리자 콘솔에서 키 만들기

커뮤니티 관리자 → 통합 → API Keys → 생성. 키는 mfk_ 뒤에 64자리 16진수가 붙는 형태이며, 전체 값은 생성 시 단 한 번만 표시되고 이후에는 접두사만 보입니다.

생성할 때 고른 스코프가 그 키로 호출할 수 있는 엔드포인트를 결정합니다. 나중에 수정할 수 없으니, 바꾸려면 새 키를 만들고 기존 키를 폐기하세요.

선택적으로 키를 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자까지입니다. 같은 값을 재사용해도 두 번째 게시물이 만들어지지 않습니다.
• 그 범위는 커뮤니티와 요청 유형과 키의 조합이며, 어떤 API 키를 썼는지와는 무관합니다. 같은 커뮤니티의 서로 다른 두 키가 같은 idempotency_key로 같은 엔드포인트를 호출하면, 두 번째 호출은 첫 번째 결과를 그대로 돌려받습니다.
• 같은 키에 다른 본문을 보내면 성공한 재시도처럼 조용히 통과하지 않고 일관된 충돌 오류가 반환됩니다.
• 요청이 타임아웃되면 같은 키로 재시도하세요 — 절대 새 키를 만들지 마세요.

• 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 단위 버킷만 있어서, 하나의 출구 주소 뒤에 있는 여러 고객이 서로 자리를 다투는 한편 여러 주소에 흩어진 호출자는 거의 제약을 받지 않았습니다. 이제 예산은 키 단위로 등급이 나뉩니다 — 키야말로 커뮤니티 소유자가 발급하고, 교체할 수 있고, 책임지는 대상이니까요.

member/lookup이 훨씬 엄격한 것은 용량이 아니라 보안 때문입니다. 다른 제약들은 '한 번의 답이 얼마나 드러내는가'를 제한하지만, 이것만은 '몇 번 물을 수 있는가'를 제한합니다 — 조회를 명부 수집으로 바꾸는 단계가 바로 그것이기 때문입니다. 설계된 용도대로, 이미 가진 주소를 사람의 속도로 해석하는 데에는 분당 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로 다시 도착합니다. 하나의 이벤트가 커스텀 웹훅과 Zap 양쪽으로 갈 때도 두 쪽이 같은 event_id를 보므로 서로 맞출 수 있습니다.

전송은 at-least-once이며 순서가 뒤바뀔 수 있습니다. 중복도, 오래된 이벤트가 늦게 도착하는 것도 모두 정상입니다. 수신 측이 멱등해야 합니다.

• 커뮤니티는 API 키에서 도출됩니다. 경로에도 본문에도 사이트 id를 보내지 마세요.
• 스코프는 키 생성 시 고정됩니다. 바꾸려면 새 키를 만들고 기존 키를 폐기하세요.
• API 키는 서버 쪽에 두세요. 클라이언트 코드에 두면 읽을 수 있는 사람은 누구나 여러분의 멤버로 게시할 수 있습니다.
• OpenAPI 계약은 모든 경로와 스키마를 담고 있습니다. 한 가지 주의: 이를 생성한 도구가 요청 본문의 required를 내보내지 않으므로, 필수 필드는 명세 파일이 아니라 이 페이지를 기준으로 삼으세요.