Eventus API

Eventus 행사 데이터를 프로그램으로 다루는 REST API 입니다. 발급받은 API 키로 인증해 본인 권한 범위 안의 행사·참가자·쿠폰·공지 등을 조회·관리할 수 있습니다.

시작하기

1. API 키 발급

로그인 후 키 대시보드에서 API 키를 발급합니다. 발급한 키는 대시보드에서 다시 확인(재조회)하거나 폐기할 수 있습니다.

2. 인증

모든 요청 헤더에 발급받은 키를 담습니다.

X-Api-Key: evt_live_xxxxxxxxxxxxxxxx

3. 권한(read / write / pii)

키 발급 시 권한을 고릅니다.

• read — 조회만 가능. 변경(생성·수정·삭제) 요청은 403 으로 거부됩니다.
• read,write — 조회 + 변경 가능.
• pii — 가산 권한. 참가자·팀원 등 타인의 개인정보(이름·이메일·전화·결제·세금·문의 본문 등) 를 반환하는 호스트/관리자 엔드포인트는 pii 가 포함된 키(read,pii 또는 read,write,pii)만 호출할 수 있고, 없으면 403 입니다. 본인 정보·공개 엔드포인트에는 적용되지 않습니다.

키의 실제 권한 천장은 키 소유자의 실시간 권한입니다. 키로 남의 데이터는 조작할 수 없습니다.

4. 호출 예시 (curl)

curl -H "X-Api-Key: evt_live_xxxxxxxxxxxxxxxx" \
  https://api.event-us.kr/api/search/events?q=컨퍼런스

5. 호출 제한 / 에러

• 요청이 많으면 429 Too Many Requests 가 반환됩니다.
• 에러 응답은 표준 Problem Details(JSON) 형식입니다.

아래는 공개 API의 카테고리별 기능을 엔드포인트별로 정리한 것입니다. 각 엔드포인트의 read/write 표기는 키 발급 시 필요한 스코프이며, 경로의 {eventId}는 행사 식별자입니다. 예시의 필드명·타입은 실제 응답 기준이고 값은 예시입니다. 더 정밀한 스키마는 API 레퍼런스에서 확인하세요.

참가자 (Attendee)

행사 참가자(신청자)의 조회를 다루는 카테고리입니다. 모든 엔드포인트는 행사 호스트 전용입니다.

참가자 조회·관리

참가자 목록 조회

POST /api/events/{eventId}/attendees/query · read · 행사 호스트 전용

행사 참가자를 다양한 필터(상태·그룹·출석·취소잠금·결제·쿠폰·메모·도메인·키워드)로 검색하고 페이지네이션·정렬하여 반환합니다. 모든 필터 필드는 선택이며, 6개월 만료 행사는 빈 목록을 반환합니다.

경로 파라미터

요청 본문

{
  "stateFilter": "add",
  "groupFilters": [
    "VIP"
  ],
  "paymentFilter": "completed",
  "searchKeyword": "홍길동",
  "sortKey": "registeredAt",
  "sortOrder": "desc",
  "page": 1,
  "pageSize": 20
}

응답 200 (PagedResult + isExpired 플래그)

{
  "items": [
    {
      "id": 1024,
      "userDataId": "9f1c2e3a-4b5c-6d7e-8f90-abcdef012345",
      "joinCode": "jR8kQ2",
      "name": "홍길동",
      "email": "hong@example.com",
      "phone": "01012345678",
      "affiliation": "이벤터스",
      "state": "add",
      "registeredAt": "2026-06-23T10:15:00+09:00",
      "isAttendance": true,
      "isCancelLock": false,
      "hasSurvey": true,
      "memo": "현장 결제 예정",
      "tickets": [
        {
          "id": 55,
          "groupId": "G1",
          "ticketName": "VIP",
          "price": 50000,
          "state": "add",
          "couponAmount": 5000,
          "couponName": "얼리버드"
        }
      ],
      "payment": {
        "method": "신용카드",
        "status": "completed",
        "amount": 45000,
        "paidAt": "2026-06-23T10:20:00+09:00"
      },
      "deposit": {
        "id": 12,
        "amount": 10000,
        "isRefunded": false,
        "paidAt": "2026-06-20T12:00:00+09:00"
      }
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20,
  "isExpired": false
}

관리 초기 메타데이터

GET /api/events/{eventId}/attendees/init · read · 행사 호스트 전용

참가자 관리 화면 진입 시 필요한 초기 메타데이터(행사 제목·Pro 등급·결제 방식·그룹·번들·설문 문항·이메일 도메인 목록 등)를 한 번에 반환합니다.

경로 파라미터

응답 200

{
  "eventTitle": "2026 봄 컨퍼런스",
  "proNum": 2,
  "isDeposit": true,
  "paymentMethod": "pg",
  "isSurvey": true,
  "isCoupon": true,
  "maxCapacity": 300,
  "isExpired": false,
  "groups": [
    {
      "id": 1,
      "groupId": "G1",
      "name": "VIP",
      "soldCount": 80,
      "applicantCount": 75
    }
  ],
  "bundles": [
    {
      "id": 3,
      "name": "1일권"
    }
  ],
  "surveys": [
    {
      "id": 10,
      "title": "참가 동기",
      "answerType": "Choice",
      "choiceType": "single",
      "sort": 1,
      "items": [
        {
          "id": 100,
          "item": "업무",
          "number": 1
        }
      ]
    }
  ],
  "domains": [
    {
      "domain": "gmail.com",
      "count": 120
    }
  ]
}

설문 답변 조회

GET /api/events/{eventId}/attendees/{userDataId}/survey-answers · read · 행사 호스트 전용

특정 참가자가 제출한 설문 항목별 답변을 반환합니다. 설문 미활성화 행사이거나 6개월 만료 행사인 경우 빈 답변을 반환합니다.

경로 파라미터

응답 200

{
  "isExpired": false,
  "isSurvey": true,
  "answers": [
    {
      "attendSurveyId": 10,
      "questionTitle": "참가 동기",
      "answerType": "Choice",
      "value": null,
      "selectedItems": [
        "업무 (신제품 조사)"
      ],
      "answeredAt": "2026-06-22T11:30:00+09:00"
    }
  ]
}

출석 순번 조회

GET /api/events/{eventId}/attendees/{userDataId}/attendance-number · read · 행사 호스트 전용

참가자의 첫 출석 시각 기준 순번과 출석 일시를 반환합니다. 티켓이 없거나 6개월 만료 행사인 경우 순번은 null입니다.

경로 파라미터

응답 200

{
  "isExpired": false,
  "number": 12,
  "formattedNumber": "012",
  "attendanceDate": "2026-06-23T09:01:00+09:00"
}

전체 스키마·오류코드는 API 레퍼런스의 Attendee 태그에서도 확인 가능.

참가자 CRM (Crm)

행사 참가자의 CRM 지표(요약 통계, 리드등급 매겨진 참가자 목록, 컴포넌트 참여지표)를 조회합니다. 모든 엔드포인트는 읽기 전용이며 행사 호스트 전용입니다.

CRM 요약 통계

GET /api/events/{eventId}/crm/summary · read · 행사 호스트 전용

행사의 확정 참가자 수, CRM 대상자 수, 평균 점수, 리드 전환율, 평균 솔루션 참여수를 반환합니다.

경로 파라미터

응답 200

{
  "targetCount": 84,
  "participantCount": 120,
  "averageScore": 57.3,
  "leadConversionRate": 70,
  "averageParticipantSolutionCount": 3.2
}

참가자 CRM 목록

GET /api/events/{eventId}/crm · read · 행사 호스트 전용

확정 참가자 목록을 리드등급·점수·컴포넌트 참여지표와 함께 반환합니다. 페이징, 리드등급 필터, 텍스트 검색, 컴포넌트 참여지표 부가 조회를 지원합니다.

경로 파라미터

쿼리 파라미터

응답 200

{
  "items": [
    {
      "userDataId": "ud_10293",
      "name": "홍길동",
      "phoneNumber": "010-1234-5678",
      "email": "hong@example.com",
      "company": "이벤터스",
      "department": "마케팅팀",
      "jobTitle": "팀장",
      "applicantGroup": "VIP",
      "totalScore": 88,
      "participantSolutionCount": 5,
      "leadGrade": "SQL",
      "component": {
        "componentId": "42",
        "accessCount": 3,
        "activeCount": 2
      }
    }
  ],
  "totalCount": 84,
  "page": 1,
  "pageSize": 20
}

CRM 컴포넌트 목록

GET /api/events/{eventId}/crm/components · read · 행사 호스트 전용

행사에 연결된 컴포넌트 목록을 반환합니다. CRM 목록 조회의 componentId 부가 지표 파라미터에 사용할 후보입니다.

경로 파라미터

응답 200

{
  "items": [
    {
      "componentId": "42",
      "name": "사전 설문",
      "type": "Survey"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 1
}

전체 스키마·오류코드는 API 레퍼런스의 Crm 태그에서도 확인 가능.

쿠폰 (Coupon)

행사 쿠폰의 목록·사용내역을 조회합니다. 모든 엔드포인트는 행사 호스트 전용입니다.

쿠폰 목록 조회

GET /api/events/{eventId}/coupons · read · 행사 호스트 전용

생성일 내림차순으로 쿠폰을 반환합니다.

경로 파라미터

응답 200

{
  "items": [
    {
      "id": 101,
      "name": "얼리버드 20%",
      "type": "auto",
      "discountAmount": 20,
      "discountOption": "percent",
      "targetTicketId": 5001,
      "totalCount": 100,
      "usedCount": 37,
      "code": "EARLY20",
      "state": "active",
      "createdAt": "2026-06-01T09:00:00+09:00"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 1
}

쿠폰 적용 옵션 조회

GET /api/events/{eventId}/coupon-options · read · 행사 호스트 전용

targetTicketId 선택용 티켓·묶음 목록.

경로 파라미터

응답 200

{
  "ticketGroups": [
    {
      "id": 5001,
      "name": "일반 입장권",
      "money": 30000,
      "bundleId": 0
    }
  ],
  "bundles": [
    {
      "id": 9001,
      "name": "VIP 패키지"
    }
  ]
}

쿠폰 사용 내역 조회

GET /api/events/{eventId}/coupons/{couponId}/usage · read · 행사 호스트 전용

사용 참가자 목록(페이징). 이메일 마스킹, 탈퇴자는 취소자.

경로 파라미터

쿼리 파라미터

응답 200

{
  "items": [
    {
      "email": "ho***@gmail.com",
      "name": "홍길동",
      "usedAt": "2026-06-10T14:22:00+09:00"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

전체 스키마·오류코드는 API 레퍼런스의 Coupon 태그에서도 확인 가능.

공지 (Notice)

행사 호스트가 공지 목록·상세를 조회합니다. 모든 엔드포인트는 행사 호스트 전용입니다.

호스트 공지 목록

GET /api/events/{eventId}/notices/admin · read · 행사 호스트 전용

행사 호스트가 관리하는 공지 전체를 페이징으로 반환합니다. 공개·비공개 여부와 카테고리·이메일 발송 상태를 포함합니다.

경로 파라미터

쿼리 파라미터

응답 200

{
  "items": [
    {
      "id": 101,
      "title": "행사 일정 안내",
      "contentPreview": "안녕하세요. 이번 행사 일정을 ...",
      "categoryId": 3,
      "categoryName": "일반 공지",
      "isOpen": true,
      "openDate": "2026-06-23T10:15:00+09:00",
      "createDate": "2026-06-20T09:00:00+09:00",
      "isEmailSent": false,
      "authorUserId": "host-user-001"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

호스트 공지 상세

GET /api/events/{eventId}/notices/admin/{noticeId} · read · 행사 호스트 전용

공지 단건의 전체 내용(HTML 포함)과 카테고리·공개 상태·이메일 발송 여부를 조회합니다. 존재하지 않으면 404.

경로 파라미터

응답 200

{
  "id": 101,
  "title": "행사 일정 안내",
  "content": "<p>안녕하세요. 이번 행사 일정을 안내드립니다.</p>",
  "categoryId": 3,
  "categoryName": "일반 공지",
  "isOpen": true,
  "openDate": "2026-06-23T10:15:00+09:00",
  "createDate": "2026-06-20T09:00:00+09:00",
  "isEmailSent": false,
  "authorUserId": "host-user-001"
}

전체 스키마·오류코드는 API 레퍼런스의 Notice 태그에서도 확인 가능.

행사 운영 (EventHost)

행사 팀원과 내 호스트 행사 목록을 조회합니다. "내 호스트 행사 목록"만 로그인 사용자 본인 기반이고, 나머지는 행사 호스트 전용입니다.

내 호스트 행사 목록

GET /api/me/events/hosted · read · 로그인 사용자

채널 호스트·행사 주인·보조 운영자로 참여 중인 게시(Start/Stop) 상태 행사 목록을 반환합니다. 본인 역할(myRole)이 함께 제공됩니다.

응답 200

{
  "items": [
    {
      "eventId": "82012",
      "title": "2024 개발자 컨퍼런스",
      "subdomain": "devconf",
      "state": "Start",
      "startDate": "2024-09-01T10:00:00+09:00",
      "endDate": "2024-09-01T18:00:00+09:00",
      "myRole": "event-owner"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 1
}

행사 팀원 목록

GET /api/events/{eventId}/team · read · 행사 호스트 전용

행사 보조 운영자(Project_Manager) 등급의 팀원 목록을 반환합니다. 이메일·이름 등 PII가 포함됩니다.

경로 파라미터

응답 200

{
  "items": [
    {
      "authId": 1024,
      "userId": "u_abc123",
      "email": "manager@example.com",
      "name": "홍길동",
      "addedDate": "2024-08-15T14:30:00+09:00"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 1
}

전체 스키마·오류코드는 API 레퍼런스의 EventHost 태그에서도 확인 가능.

대시보드 (Dashboard)

행사 신청 라이프사이클·출석·결제·매출 요약과 티켓 그룹/등록 경로별 분포를 제공합니다. 모두 읽기 전용이며 행사 호스트 전용입니다.

행사 요약

GET /api/events/{eventId}/dashboard/summary · read · 행사 호스트 전용

전체·확정·미결·취소 신청 수, 출석 인원, 결제 완료 인원 및 총 매출액.

경로 파라미터

응답 200

{
  "eventId": "82012",
  "totalCount": 1280,
  "confirmedCount": 940,
  "outstandingCount": 210,
  "cancelledCount": 130,
  "attendedCount": 712,
  "paidCount": 605,
  "paidAmount": 18150000
}

티켓 그룹별 신청 분포

GET /api/events/{eventId}/dashboard/ticket-groups · read · 행사 호스트 전용

각 티켓 그룹에 확정 신청된 인원 수.

경로 파라미터

응답 200

{
  "eventId": "82012",
  "totalGroups": 3,
  "totalRegistrations": 940,
  "groups": [
    {
      "groupId": "grp-vip",
      "groupName": "VIP",
      "registeredCount": 120
    }
  ]
}

티켓 그룹별 출석 현황

GET /api/events/{eventId}/dashboard/ticket-group-attendance · read · 행사 호스트 전용

티켓 그룹별 확정 신청 수와 출석/미출석 수.

경로 파라미터

응답 200

{
  "eventId": "82012",
  "totalGroups": 3,
  "totalRegistered": 940,
  "totalAttended": 712,
  "groups": [
    {
      "groupId": "grp-vip",
      "groupName": "VIP",
      "registeredCount": 120,
      "attendedCount": 98,
      "notAttendedCount": 22
    }
  ]
}

등록 경로별 신청 수

GET /api/events/{eventId}/dashboard/registration-methods · read · 행사 호스트 전용

엑셀 업로드·호스트 현장 추가·직접 신청 경로별 카운트.

경로 파라미터

응답 200

{
  "eventId": "82012",
  "totalCount": 1280,
  "excelCount": 340,
  "hostAddedCount": 215,
  "directCount": 725
}

전체 스키마·오류코드는 API 레퍼런스의 Dashboard 태그에서도 확인 가능.

통계 (Statistics)

행사 페이지 트래픽·참가자 데이터·설문·유입 경로를 기간별로 분석합니다. 모두 읽기 전용이며 행사 호스트 전용입니다. 리포트 계열은 start/end 쿼리(기본: 모집 시작~마감, 최대 730일)를 받습니다.

이벤트 페이지 최근 14일

GET /api/events/{eventId}/statistics/event-page/recent · read · 행사 호스트 전용

최근 14일 일별 조회·클릭·신청·취소.

경로 파라미터

응답 200

{
  "recentData": [
    {
      "date": "2026-06-23T00:00:00+09:00",
      "view": 312,
      "click": 87,
      "attend": 14,
      "cancel": 2
    }
  ]
}

이벤트 페이지 기간 리포트

GET /api/events/{eventId}/statistics/event-page/report · read · 행사 호스트 전용

기간의 조회·클릭·신청·취소 일별 추이, 유입 도메인·기기 분포.

경로 파라미터

쿼리 파라미터

응답 200

{
  "title": "2026 개발자 컨퍼런스",
  "viewCount": 5234,
  "clickCount": 1820,
  "attendCount": 430,
  "cancelCount": 18,
  "countData": [
    {
      "date": "2026-05-01T00:00:00+09:00",
      "view": 120,
      "click": 40,
      "attend": 12,
      "cancel": 1
    }
  ],
  "domains": {
    "items": [
      {
        "host": "instagram.com",
        "count": 540,
        "percent": 31.2
      }
    ],
    "othersCount": 73
  },
  "pc": 980,
  "mobile": 1640,
  "tablet": 55,
  "start": "2026-05-01T00:00:00+09:00",
  "end": "2026-06-20T00:00:00+09:00"
}

참가자 데이터 리포트

GET /api/events/{eventId}/statistics/attend-data/report · read · 행사 호스트 전용

확정 참가자의 티켓 그룹·성별·연령·지역 분포와 채널 충성도.

경로 파라미터

응답 200

{
  "ticketGroups": {
    "all": 430,
    "items": [
      {
        "groupName": "일반 참가",
        "count": 300,
        "percent": 69.8
      }
    ]
  },
  "gender": {
    "man": 250,
    "woman": 175,
    "anonymous": 5,
    "all": 430
  },
  "ages": {
    "20대": 22,
    "30대": 41,
    "40대": 25
  },
  "areas": {
    "items": [
      {
        "area": "서울",
        "count": 210,
        "percent": 48.8
      }
    ],
    "othersCount": 12
  },
  "loyalAttendees": {
    "onceCount": 60,
    "twiceCount": 18,
    "threePlusCount": 7
  }
}

신청 설문 응답 리포트

GET /api/events/{eventId}/statistics/attend-survey/report · read · 행사 호스트 전용

질문별 응답 현황(선택형 집계·단답형 최신 답변)과 응답자 수. 설문 종료 후 6개월 이내만 조회 가능.

경로 파라미터

응답 200

{
  "available": true,
  "applicantCount": 430,
  "respondentCount": 380,
  "questions": [
    {
      "id": 1001,
      "title": "관심 세션",
      "answerType": "Choice",
      "choiceType": "Single",
      "sort": 1,
      "choices": [
        {
          "item": "백엔드",
          "count": 142
        }
      ],
      "textAnswers": null
    },
    {
      "id": 1002,
      "title": "바라는 점",
      "answerType": "Short",
      "sort": 2,
      "choices": null,
      "textAnswers": [
        {
          "value": "네트워킹 시간 확대",
          "date": "2026-06-10T14:22:00+09:00"
        }
      ]
    }
  ]
}

URL 방문 로그 종합 리포트

GET /api/events/{eventId}/statistics/url-log/report · read · 행사 호스트 전용

총 방문수·고유 IP, 유입 도메인 Top, 시간대별(0~23시) 분포, 일별 추이.

경로 파라미터

쿼리 파라미터

응답 200

{
  "totalCount": 8420,
  "uniqueUserCount": 3105,
  "domains": {
    "items": [
      {
        "host": "instagram.com",
        "count": 2200,
        "percent": 26.1
      }
    ],
    "othersCount": 410
  },
  "hourlyCounts": [
    {
      "hour": 13,
      "count": 612
    }
  ],
  "trendData": [
    {
      "date": "2026-05-01T00:00:00+09:00",
      "count": 240
    }
  ]
}

URL 방문 상세

GET /api/events/{eventId}/statistics/url-log/detail · read · 행사 호스트 전용

지정 유입 도메인(host 쿼리)의 URL별 방문 횟수. direct/none은 직접 유입.

경로 파라미터

쿼리 파라미터

응답 200

{
  "host": "instagram.com",
  "urls": {
    "items": [
      {
        "absoluteUri": "https://event-us.kr/event/12345",
        "count": 1320
      }
    ],
    "othersCount": 88
  }
}

전체 스키마·오류코드는 API 레퍼런스의 Statistics 태그에서도 확인 가능.

채널 (Channel)

채널 상세·멤버·구독 목록을 조회합니다. 채널 상세는 인증 없이 호출 가능(비호스트는 민감 필드 마스킹), 멤버 목록 조회는 채널 호스트 권한이 필요합니다.

채널 상세 조회

GET /api/channels/{subdomain} · read · 인증 불필요

서브도메인으로 채널 정보를 조회합니다. 비공개/비호스트인 경우 담당자 정보·정보 탭 본문 등 민감 필드는 null로 마스킹됩니다.

경로 파라미터

응답 200

{
  "subdomain": "techconf",
  "title": "테크 컨퍼런스 2026",
  "description": "개발자를 위한 연례 행사",
  "logoUrl": "https://cdn.event-us.kr/logo.png",
  "themeColor": "#1a73e8",
  "textColor": "#ffffff",
  "isOpen": true,
  "channelUrl": "https://event-us.kr/techconf/event",
  "isSubscribed": true,
  "managerInfo": {
    "name": "홍길동",
    "email": "host@event-us.kr",
    "phone": "010-1234-5678"
  },
  "subscriberCount": 1024
}

채널 멤버 목록

GET /api/channels/{slug}/members · read · 채널 호스트

채널 호스트(App/App_Free) 등급 멤버 전체. 이메일·이름 등 PII는 호스트에게만 노출.

경로 파라미터

응답 200

{
  "items": [
    {
      "authId": 42,
      "userId": "a1b2c3d4-...",
      "email": "member@event-us.kr",
      "name": "김멤버",
      "role": "App",
      "isSelf": false,
      "addedDate": "2026-02-01T10:30:00+09:00"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 1
}

내 호스트 채널 목록

GET /api/me/channels · read · 로그인 사용자

호스트(App/App_Free)로 등록된 채널 목록. 보조 운영자 권한은 미포함.

응답 200

{
  "items": [
    {
      "slug": "techconf",
      "title": "테크 컨퍼런스 2026",
      "logoUrl": "https://cdn.event-us.kr/logo.png",
      "themeColor": "#1a73e8",
      "isSuper": false,
      "myRole": "App"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 1
}

내 채널 구독 목록

GET /api/me/subscriptions · read · 로그인 사용자

활성 채널 구독 목록(비공개 전환 채널 포함). 이메일 알림 설정 상태 포함.

응답 200

{
  "items": [
    {
      "subdomain": "techconf",
      "title": "테크 컨퍼런스 2026",
      "logoUrl": "https://cdn.event-us.kr/logo.png",
      "isOpen": true,
      "channelUrl": "https://event-us.kr/techconf/event",
      "isEmailAlert": true,
      "subscribedDate": "2026-03-10T14:00:00+09:00"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 1
}

전체 스키마·오류코드는 API 레퍼런스의 Channel 태그에서도 확인 가능.

검색 (Discovery)

행사·채널·기업·축제를 키워드/필터/지도/캘린더로 탐색합니다. 검색·추천·축제 계열은 대체로 인증이 필요 없고, 검색 히스토리는 로그인 사용자 전용입니다.

행사·채널 검색

행사 키워드 검색

GET /api/search/events · read · 인증 불필요

키워드·카테고리·지역·날짜·가격 등으로 공개 행사를 검색합니다. 비밀번호 보호 행사는 자동 제외되고, 기본적으로 접수 마감 전 행사만 반환합니다.

쿼리 파라미터

응답 200

{
  "items": [
    {
      "id": "12345",
      "title": "2026 개발자 컨퍼런스",
      "category": "컨퍼런스",
      "eventType": "seminar",
      "eventSystemType": "offline",
      "subdomain": "devcon",
      "themeColor": "#3B82F6",
      "coverImageUrl": "https://cdn.event-us.kr/cover/12345.jpg",
      "area": "서울",
      "startDate": "2026-07-01",
      "registerDueDate": "2026-06-30",
      "location": "코엑스",
      "tags": [
        "개발",
        "AI"
      ],
      "viewCount": 1200,
      "minPrice": 0,
      "isPaid": false,
      "eventUrl": "https://event-us.kr/devcon/event/12345"
    }
  ],
  "totalCount": 57,
  "page": 1,
  "pageSize": 20
}

행사 ID 목록으로 카드 조회

GET /api/search/events/by-ids · read · 인증 불필요

캘린더·지도 인덱스의 행사 ID 목록을 카드 데이터로 변환합니다.

쿼리 파라미터

응답 200 — /api/search/events와 동일한 카드 아이템 배열(PagedResult)

행사 검색어 자동완성

GET /api/search/suggest · read · 인증 불필요

입력 키워드와 일치하는 활성 행사 제목을 최대 10건(기본) 반환. 일치 부분은 <em> 태그로 강조.

쿼리 파라미터

응답 200

{
  "items": [
    {
      "id": "12345",
      "title": "2026 개발자 컨퍼런스",
      "highlightedTitle": "2026 <em>개발자</em> 컨퍼런스",
      "subdomain": "devcon",
      "eventUrl": "https://event-us.kr/devcon/event/12345"
    }
  ],
  "totalCount": 3,
  "page": 1,
  "pageSize": 10
}

채널 검색·자동완성

GET /api/search/suggest-channels · read · 인증 불필요

행사를 보유한 공개 채널을 검색. 내부(@event-us.kr)·비공개 채널은 제외.

쿼리 파라미터

응답 200

{
  "items": [
    {
      "subdomain": "devcon",
      "appTitle": "DevCon",
      "logoImageUrl": "https://cdn.event-us.kr/logo/devcon.png",
      "eventCount": 12,
      "exactMatch": true,
      "channelUrl": "https://event-us.kr/devcon"
    }
  ],
  "totalCount": 4,
  "page": 1,
  "pageSize": 8
}

검색 캘린더 인덱스

GET /api/search/calendar · read · 인증 불필요

특정 연·월(year/month 필수)의 일자별 공개 행사 개수와 ID 목록. 카드 상세는 /api/search/events/by-ids로 조회.

쿼리 파라미터

응답 200

{
  "year": 2026,
  "month": 7,
  "lastDayOfMonth": 31,
  "days": [
    {
      "date": "2026-07-01",
      "count": 3,
      "ids": [
        "12345",
        "12346",
        "12347"
      ]
    }
  ]
}

검색 지도 마커

GET /api/search/map/markers · read · 인증 불필요

특정 날짜(date 생략 시 오늘 KST) 진행 행사의 지도 좌표. 카드 상세는 by-ids로 조회.

쿼리 파라미터

응답 200

[
  {
    "id": "12345",
    "subdomain": "devcon",
    "title": "2026 개발자 컨퍼런스",
    "latitude": 37.5126,
    "longitude": 127.0589
  }
]

기업 검색

GET /api/search/companies · read · 인증 불필요

기업명·사업자번호로 기업 검색. 키워드 없으면 전체 목록(페이지 크기 최대 50).

쿼리 파라미터

응답 200

{
  "items": [
    {
      "companyName": "이벤터스",
      "companyAddress": "서울 강남구 테헤란로",
      "businessNo": "123-45-67890"
    }
  ],
  "totalCount": 2,
  "page": 1,
  "pageSize": 20
}

추천·탐색

추천 행사

GET /api/events/featured · read · 인증 불필요

function_score 상위 공개 행사. 카테고리·행사 유형 필터 지원.

쿼리 파라미터

응답 200

{
  "items": [
    {
      "id": "12345",
      "title": "2026 개발자 컨퍼런스",
      "subdomain": "devcon",
      "coverImageUrl": "https://cdn.event-us.kr/cover/12345.jpg",
      "startDate": "2026-07-01",
      "category": "컨퍼런스",
      "eventUrl": "https://event-us.kr/devcon/event/12345"
    }
  ],
  "totalCount": 12,
  "page": 1,
  "pageSize": 12
}

빈 검색 결과 추천

GET /api/search/empty-recommendations · read · 인증 불필요

검색 결과가 없을 때 표시할 추천 행사를 랜덤 반환(기본 8건, 최대 20건).

쿼리 파라미터

응답 200 — 추천 행사와 동일한 카드 아이템 배열

축제 (TourAPI)

축제 키워드 검색

GET /api/search/festivals · read · 인증 불필요

한국관광공사 TourAPI 기반 축제 검색(키워드·지역·날짜 범위).

쿼리 파라미터

응답 200

{
  "items": [
    {
      "contentId": "2733967",
      "title": "한강 여름 축제",
      "address": "서울 영등포구 여의동로 330",
      "tel": "02-1234-5678",
      "startDate": "20260701",
      "endDate": "20260710",
      "imageUrl": "https://tong.visitkorea.or.kr/cms/festival.jpg"
    }
  ],
  "totalCount": 5,
  "page": 1,
  "pageSize": 20
}

축제 상세

GET /api/search/festivals/{contentId} · read · 인증 불필요

contentId 축제 상세(TourAPI 프록시, 1시간 캐시).

경로 파라미터

응답 200

{
  "contentId": "2733967",
  "title": "한강 여름 축제",
  "address": "서울 영등포구 여의동로 330",
  "tel": "02-1234-5678",
  "overview": "한강에서 열리는 여름 축제입니다.",
  "homepage": "https://hangang.seoul.go.kr",
  "imageUrl": "https://tong.visitkorea.or.kr/cms/festival.jpg",
  "mapX": "126.9326",
  "mapY": "37.5283"
}

검색 히스토리·클릭

검색 히스토리 목록

GET /api/search-history · read · 로그인 사용자

최근 검색어 최대 50건(soft delete 제외).

응답 200

{
  "items": [
    {
      "id": "a1b2c3d4e5f6",
      "query": "개발자 컨퍼런스",
      "date": "2026-06-23T10:15:00+09:00"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 50
}

전체 스키마·오류코드는 API 레퍼런스의 Discovery 태그에서도 확인 가능.

부스 예약 (BoothWaiting)

부스 대기열 솔루션입니다. 세 역할이 서로 다른 인증으로 같은 대기열을 다룹니다. 전체 엔드포인트와 스키마는 API 레퍼런스의 솔루션 ▸ 부스예약에서 확인하세요.

• 참가자 — 부스 QR의 boothKey로 로그인 없이 사용합니다. 등록 시 발급되는 엔트리 토큰을 이후 요청의 X-Entry-Token 헤더로 보냅니다.
• 운영자 — 운영자 링크의 operatorKey + 비밀번호로 로그인해 운영자 토큰을 받고, 이후 요청의 X-Operator-Token 헤더로 보냅니다. 행사 호스트는 로그인 세션만으로 비밀번호 없이 접근할 수 있습니다.
• 호스트 — 호스트센터 경로(/hostcenter/channel/{subdomain}/{projectid}/boothwaiting/{componentsid}/...)에서 부스 생성·현황·참여자 데이터를 관리합니다. 행사 호스트 전용입니다.

상태는 wait → called → progress → done으로 흐르고, 노쇼(noshow)·취소(cancel)로 빠질 수 있습니다. 호출 유효시간이 지나면 자동 노쇼 처리되고, 부스 설정에 따라 다음 대기자가 자동 호출됩니다(별도 배치 없이 조회 시점에 평가).

참가자 API

/api/wait/{boothKey}/… · 익명 (로그인 불필요)

운영자 API

/api/wait/op/{operatorKey}/… · X-Operator-Token 헤더

호스트 API

/hostcenter/channel/{subdomain}/{projectid}/boothwaiting/{componentsid}/… · 행사 호스트 전용