AI밋업 API

즉석만남 앱 AI밋업(com.croninc.meetup)의 백엔드 API 문서입니다.

• Base URL : https://api.meetup.croninc.com
• 버전 : 2.0.0 (경로 접두사 /api/v1)
• 형식 : 요청·응답 모두 application/json; charset=utf-8
• 시간 : 모든 시각은 ISO 8601 UTC 문자열 (2026-08-25T10:30:00+00:00)
• 대화형 문서 : /swagger · /redoc

1. 인증

토큰 방식

로그인하면 액세스 토큰(7일)과 리프레시 토큰(60일)을 함께 받습니다. 인증이 필요한 API 는 헤더에 액세스 토큰을 담아 보냅니다.

Authorization: Bearer <access_token>

• 액세스 토큰이 만료되면 POST /api/v1/auth/refresh 로 새 토큰 쌍을 받습니다. 이때 기존 토큰 쌍은 폐기됩니다(리프레시 토큰 재사용 방지).
• 로그아웃·회원탈퇴 시 서버에 저장된 세션이 삭제되어, 남아 있는 토큰도 즉시 무효가 됩니다.

두 가지 로그인 방법

게스트로 쓰다가 정식 계정으로 바꾸려면 POST /api/v1/auth/email/link 를 씁니다. 기존 활동 기록(참여한 번개, 관심 목록)이 그대로 유지됩니다.

2. 공통 규약

오류 형식

{ "detail": "이메일 또는 비밀번호가 올바르지 않습니다." }

목록 응답

목록은 { "count": n, "items": [...] } 형태로 통일되어 있습니다.

3. 시스템

GET /api/v1/health

curl https://api.meetup.croninc.com/api/v1/health

{ "status": "ok", "service": "meetup", "version": "2.0.0", "time": "2026-08-24T14:42:00+00:00" }

4. 인증 API

POST /api/v1/auth/guest

게스트 로그인. 인증 불필요.

curl -X POST https://api.meetup.croninc.com/api/v1/auth/guest \
  -H 'Content-Type: application/json' \
  -d '{"device_id": "ios-6C1A2F80"}'

응답 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "user": {
    "user_id": "u_e37ef3331c50474c",
    "nickname": "지금게스트1628",
    "email": null,
    "is_guest": true,
    "gender": "unknown",
    "interests": [],
    "created_at": "2026-08-24T14:40:12+00:00"
  }
}

POST /api/v1/auth/email/signup

이메일 회원가입. 인증 불필요. 성공 시 201 Created.

curl -X POST https://api.meetup.croninc.com/api/v1/auth/email/signup \
  -H 'Content-Type: application/json' \
  -d '{"email": "hong@example.com", "password": "meetup1234", "nickname": "홍길동"}'

이미 가입된 이메일이면 409 Conflict.

POST /api/v1/auth/email/login

이메일 로그인. 인증 불필요. 응답은 게스트 로그인과 같은 토큰 묶음입니다. 이메일이 없거나 비밀번호가 틀리면 401 이며, 어느 쪽이 틀렸는지는 구분해서 알려주지 않습니다.

curl -X POST https://api.meetup.croninc.com/api/v1/auth/email/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "hong@example.com", "password": "meetup1234"}'

POST /api/v1/auth/email/link

인증 필요. 게스트 계정에 이메일·비밀번호를 붙여 정식 계정으로 승격합니다. 이미 이메일 계정이면 400, 이메일이 중복이면 409.

POST /api/v1/auth/refresh

인증 불필요 (본문의 리프레시 토큰으로 검증).

{ "refresh_token": "eyJhbGciOiJIUzI1NiIs..." }

POST /api/v1/auth/logout

인증 필요. 현재 세션의 액세스·리프레시 토큰을 서버에서 삭제합니다.

{ "ok": true, "message": "로그아웃되었습니다." }

5. 사용자 API

모두 인증 필요.

GET /api/v1/users/me

내 정보를 반환합니다.

PATCH /api/v1/users/me

프로필 수정. 보낸 필드만 바뀝니다.

PUT /api/v1/users/me/location

현재 위치 저장. 주변찾기에 노출되려면 반드시 먼저 호출해야 합니다.

{ "lat": 37.4979, "lng": 127.0276, "region": "서울시 강남구 역삼동" }

PUT /api/v1/users/me/settings

알림 설정 저장. 값은 계정에 저장되어 다른 기기에서도 같게 적용됩니다.

{ "push_meetup": true, "push_request": true, "push_marketing": false }

응답은 갱신된 사용자 객체이며, settings 필드로 현재 값을 확인할 수 있습니다.

GET /api/v1/users/me/meetups

내 번개 목록. role=joined(기본) 또는 role=hosted.

GET /api/v1/users/{user_id}

다른 사용자 공개 프로필. 이메일은 반환하지 않습니다.

DELETE /api/v1/users/me

회원탈퇴. 다음이 한 번에 처리됩니다.

1. 내가 연 모집 중 번개를 모두 cancelled 로 변경
2. 번개 참여 기록 삭제
3. 이메일·비밀번호·기기 ID·위치·자기소개 등 개인정보 삭제 후 status=deleted 로 표시
4. 모든 기기의 토큰 폐기

같은 이메일로 다시 가입할 수 있습니다.

6. 번개 API

GET /api/v1/meetups

모집 중인 번개 목록. 인증 선택 (토큰을 주면 joined 값이 채워집니다).

좌표를 주지 않으면 시작 시간이 빠른 순으로 정렬합니다.

{
  "count": 1,
  "items": [
    {
      "meetup_id": "mt_81f02a0584dd47",
      "host_id": "u_38eb8669c8cf4fe4",
      "host_nickname": "테스터",
      "title": "퇴근하고 맥주 한잔 🍺",
      "category": "술모임",
      "place": "강남역 11번 출구",
      "meet_at": "2026-08-24T17:42:11+00:00",
      "capacity": 4,
      "joined_count": 2,
      "status": "open",
      "lat": 37.4985,
      "lng": 127.0278,
      "distance_m": 69,
      "joined": true,
      "created_at": "2026-08-24T14:42:11+00:00"
    }
  ]
}

POST /api/v1/meetups

번개 만들기. 인증 필요. 201 Created. 개설자는 자동으로 참여 처리됩니다.

GET /api/v1/meetups/{meetup_id}

번개 상세. 인증 선택.

PATCH /api/v1/meetups/{meetup_id}

개설자만. 이미 참여한 인원보다 작게 capacity 를 줄이면 400.

DELETE /api/v1/meetups/{meetup_id}

개설자만. 삭제가 아니라 status=cancelled 로 바뀝니다.

POST /api/v1/meetups/{meetup_id}/join

참여. 정원이 차면 409, 이미 참여했으면 409. 정원 초과는 DynamoDB 조건부 갱신으로 막기 때문에 동시에 신청해도 초과되지 않습니다.

DELETE /api/v1/meetups/{meetup_id}/join

참여 취소. 개설자는 취소할 수 없고 번개 자체를 취소해야 합니다(400).

GET /api/v1/meetups/{meetup_id}/participants

참여자 목록. 인증 필요.

7. 주변찾기 API

GET /api/v1/nearby/users

인증 필요. 내 위치 기준으로 가까운 사용자를 거리순으로 반환합니다.

{
  "count": 1,
  "radius_m": 3000,
  "items": [
    {
      "user_id": "u_38eb8669c8cf4fe4",
      "nickname": "테스터",
      "age": 28,
      "gender": "unknown",
      "status_message": "커피 한잔 하실 분",
      "distance_m": 127,
      "online": true,
      "last_active_at": "2026-08-24T14:42:10+00:00"
    }
  ]
}

• 위치를 한 번도 올리지 않은 사용자는 목록에 나오지 않습니다.
• online 은 최근 15분 안에 활동한 경우 true.
• 내부적으로 0.1도 지오 격자로 후보를 좁힌 뒤 하버사인 거리로 다시 거릅니다.

8. 번개 신청 API

주변찾기에서 만난 상대에게 1:1 로 보내는 신청입니다. 모두 인증 필요.

상태값은 pending → accepted / rejected 이며, 받은 사람만 응답할 수 있습니다(403). 이미 처리한 신청에 다시 응답하면 409.

9. 관심 목록 API

10. 데이터 저장소

DynamoDB (리전 ap-northeast-2, 전부 온디맨드 과금). 테이블 이름은 모두 meetup_ 으로 시작합니다.

meetup_sessions 는 expires_at 속성으로 TTL 이 걸려 있어 만료된 토큰 기록이 자동 삭제됩니다.

11. 앱 화면 ↔ API 매핑

12. 레거시 API

meetup.croninc.com 랜딩 페이지가 쓰는 데모 엔드포인트입니다. 앱에서는 쓰지 않습니다.

/api/health · /api/stats · /api/profiles · /api/profiles/{id} · /api/signup · /api/signup/{id} · /api/matches

13. 정책

• 비밀번호는 PBKDF2-HMAC-SHA256(210,000회)로 해시해 저장하며 평문은 보관하지 않습니다.
• 위치 정보는 주변찾기 노출 목적으로만 쓰이며, 회원탈퇴 시 즉시 삭제됩니다.
• 주변찾기 응답에는 상대의 정확한 좌표 대신 거리(m) 만 내려갑니다.
• 자동화된 대량 수집(스크래핑)은 금지되며, 위반 시 차단될 수 있습니다.

문의: support@croninc.com · © 2026 CronInc