> ## Documentation Index > Fetch the complete documentation index at: https://docs.rocketpunch.com/llms.txt > Use this file to discover all available pages before exploring further. # 이벤트 검색·목록 > 이벤트를 검색·필터링하여 페이지 단위로 조회한다. 키워드, 카테고리, 주제, 지역, 기간, 상태로 필터링하며, 시작일이 임박한 순(시작일 오름차순)으로 정렬한다. ## OpenAPI ````yaml /openapi/openapi.json get /api/v1/events openapi: 3.1.0 info: title: 로켓펀치 Open API description: >- 로켓펀치의 채용공고·이벤트·게시글 등 다양한 데이터를 조회·연동할 수 있는 REST API. ## 인증 공개 데이터 조회 API 는 `X-RP-API-Key` 헤더를 사용한다. 사용자 권한이 필요한 API 는 `Authorization: Bearer ` 헤더를 사용한다. 각 오퍼레이션의 `security` 항목에서 필요한 인증 방식을 확인할 수 있다. ## 앱 타입 선택 포털에서 App 을 만들 때는 사용하려는 API 성격에 맞춰 타입을 선택한다. | 타입 | 의미 | 주로 사용하는 API | |---|---|---| | App Key 전용 앱 | 공개 데이터를 가져오는 앱. 사용자 로그인이 필요 없는 조회 API 에 사용한다. | 채용공고·이벤트·게시글 조회 | | OAuth 클라이언트 앱 | 사용자가 로켓펀치 계정으로 로그인해 권한을 허용하는 앱. | 게시글 작성·수정·삭제처럼 사용자 권한이 필요한 API | 공개 데이터 조회 API 는 App Key(`X-RP-API-Key` 헤더)만으로 호출한다. 사용자 권한이 필요한 API 는 OAuth 클라이언트 앱으로 발급받은 access token 을 `Authorization: Bearer ` 헤더로 보낸다. ## OAuth 2.0 인증 본 서비스는 사용자 컨텍스트 API 호출을 위해 OAuth 2.0 Authorization Code + PKCE(S256) 인가 흐름을 자체 호스팅한다. - 인가 화면: `GET /oauth/authorize` - 토큰 발급/갱신: `POST /oauth/token` - 토큰 폐기: `POST /oauth/revoke` - 사용자 정보: `GET /oauth/userinfo` (`profile` scope 필수, `email` claim 은 `email` scope 필요) ## Rate Limit App Key 기준 **전역 분당 60회 / 일 5,000회**. 초과 시 `429` + `Retry-After`. 정상 응답에는 `X-RP-RateLimit-Remaining` 헤더 포함. 사용자 권한이 필요한 일부 변경 작업에는 작업별 세부 한도(분/시/일)가 함께 적용된다. 전역 한도 또는 작업별 세부 한도 중 하나라도 초과하면 `429` 가 응답된다. 작업별 세부 한도 초과 시 `X-RP-RateLimit-Scope` 헤더로 작업 구분이 제공된다. 정상 응답에는 `X-RP-RateLimit-Scope-Remaining` 헤더로 해당 작업의 이번 분 남은 호출 수가 제공된다. | 작업 구분 | 적용 작업 | 분당 | 시간당 | 일 | |---|---|---:|---:|---:| | `post.create` | 게시글 작성 | 2 | 10 | 50 | | `post.update` | 게시글 수정 | 5 | 40 | 300 | | `post.delete` | 게시글 삭제 | 2 | 10 | 30 | | `job.create` | 채용공고 생성 | 2 | 10 | 50 | | `job.update` | 채용공고 수정 | 5 | 40 | 300 | | `job.delete` | 채용공고 삭제 | 2 | 10 | 30 | | `job.publish` | 채용공고 게시 | 5 | 30 | 150 | | `job.disable` | 채용공고 비활성화 | 5 | 30 | 150 | | `event.create` | 이벤트 생성 | 2 | 10 | 50 | | `event.update` | 이벤트 수정 | 5 | 40 | 300 | | `event.delete` | 이벤트 삭제 | 2 | 10 | 30 | | `event.sub.create` | 이벤트 세션/FAQ/호스트/티켓 생성 | 10 | 100 | 500 | | `event.sub.update` | 이벤트 세션/FAQ/호스트/티켓 수정 | 15 | 150 | 800 | | `event.sub.delete` | 이벤트 세션/FAQ/호스트/티켓 삭제 | 10 | 100 | 400 | ## 다국어 (Accept-Language) `Accept-Language` 헤더로 응답 언어를 결정한다(미지정 시 `ko`). 코드 카탈로그(`/v1/codes/*`) 라벨이 지원하는 로케일: | 코드 | 언어 | 비고 | |---|---|---| | `ko` | 한국어 (Korean) | 기본값 | | `en` | 영어 (English) | | | `ja` | 일본어 (Japanese) | | | `zh-CN` | 중국어 간체 (Simplified Chinese) | 중국 본토 | | `zh-TW` | 중국어 번체 (Traditional Chinese) | 대만·홍콩 | | `es` | 스페인어 (Spanish) | | | `fr` | 프랑스어 (French) | | | `de` | 독일어 (German) | | | `pt` | 포르투갈어 (Portuguese) | | | `th` | 태국어 (Thai) | | | `vi` | 베트남어 (Vietnamese) | | 채용공고·이벤트·게시글 **본문 번역**은 `en`, `ja`, `zh-CN`, `zh-TW` 만 제공하며, 그 외 언어는 원문으로 반환한다. ## 페이지네이션 목록(검색) 응답은 페이지 기반 페이지네이션을 사용한다. - `page`: 조회할 페이지 번호. **1부터 시작**(기본 `1`). 1 미만 값은 `1` 로 보정된다. - `pageSize`: 페이지당 항목 수. 기본 `20`, **최대 `50`**. 범위를 벗어난 값은 1~50 으로 보정된다(50 초과 요청은 50 으로 처리). 응답은 공통 형식으로 다음 필드를 포함한다. - `totalItems`: 조건에 맞는 전체 항목 수 - `totalPages`: 전체 페이지 수(`ceil(totalItems / pageSize)`) - `page` / `pageSize`: 실제 적용된(보정된) 페이지 번호와 크기 - `items`: 현재 페이지의 항목 배열 `page` 가 `totalPages` 를 초과하면 오류 없이 `items` 가 빈 배열로 반환된다. ## 에러 정상 흐름(2xx)을 제외한 모든 4xx·5xx 응답은 동일한 에러 응답 형식(`ErrorResponse`)을 사용한다. ### 에러 응답 형식 ```json { "code": "C0005", "message": "요청 값이 올바르지 않습니다.", "timestamp": "2026-05-20T09:00:00", "details": "pageSize" } ``` | 필드 | 설명 | |---|---| | `code` | 에러 코드. 아래 표의 값 중 하나로, 클라이언트 분기에 사용한다 | | `message` | 사람이 읽을 수 있는 에러 메시지 | | `timestamp` | 에러 발생 시각 (UTC 기준) | | `details` | 문제가 된 필드 경로/파트명/사유. 해당 정보가 없으면 `null` | ### 에러 코드 | HTTP | code | 의미 | |---|---|---| | 401 | C0001 | API Key 누락/무효 | | 400 | C0002 | 입력 형식 오류 | | 400 | C0005 | 쿼리 파라미터 유효성 실패 | | 404 | C0008 / EV001 / R0001 / P0002 | 리소스 없음(공통/이벤트/공고/게시글) | | 429 | C0010 | Rate limit 초과 | | 500 | C9999 | 서버 오류 | version: 1.0 beta servers: - url: https://openapi.rocketpunch.com description: Production security: - apiKey: [] tags: - name: OAuth Authorization description: >- Authorization Code + PKCE 인가 흐름의 시작점. 사용자를 `GET /oauth/authorize` 로 보내 로그인한 뒤, 동의가 필요하면 동의 화면을 거쳐 등록된 redirect_uri 로 일회용 authorization code 를 전달한다. 유효한 기존 동의가 요청 scope를 포함하면 동의 화면은 생략한다. 이 code 를 OAuth Token 에서 access token 으로 교환한다. - name: Posts description: 게시글 조회·작성·수정·삭제 API - name: Codes description: >- 검색 필터에 사용하는 코드 목록. 응답의 `code` 를 검색 파라미터 값으로 그대로 전달한다. 표시명(`displayName`)은 Accept-Language 에 따라 번역된다. - name: OAuth UserInfo description: OAuth access token 으로 사용자 표준 claim 을 조회한다. - name: OAuth Token description: >- authorization code 나 refresh token 을 access token 으로 교환·갱신하고(`POST /oauth/token`), 더 이상 쓰지 않는 토큰을 폐기한다(`POST /oauth/revoke`). 발급된 access token 은 `Authorization: Bearer` 로 사용자 컨텍스트 API 호출에 사용한다. - name: Events description: 이벤트 조회·등록·수정·삭제 및 하위 리소스 API - name: Jobs description: 채용공고 조회·등록·수정·삭제 API - name: Me description: 내 정보/권한 API paths: /api/v1/events: get: tags: - Events summary: 이벤트 검색·목록 description: >- 이벤트를 검색·필터링하여 페이지 단위로 조회한다. 키워드, 카테고리, 주제, 지역, 기간, 상태로 필터링하며, 시작일이 임박한 순(시작일 오름차순)으로 정렬한다. operationId: searchEvents parameters: - name: keyword in: query description: 이벤트명/설명 검색어 required: false schema: type: string maxLength: 100 minLength: 0 - name: categories in: query description: 카테고리 코드. 값은 /v1/codes/event-categories 참조 required: false schema: type: array items: type: string - name: subjects in: query description: 주제 코드. /v1/codes/event-subjects 참조 required: false schema: type: array items: type: string - name: openTypes in: query description: '오픈 타입: OFFLINE(오프라인·현장)/ONLINE(온라인)/ON_OFFLINE(온·오프라인 병행)/TBD(미정)' required: false schema: type: array items: type: string - name: startDateFrom in: query description: 시작일 ≥ (YYYY-MM-DD) required: false schema: type: string example: '2026-06-01' - name: startDateTo in: query description: 시작일 ≤ (YYYY-MM-DD) required: false schema: type: string - name: status in: query description: >- 상태 필터(이벤트 기간 기준). UPCOMING(시작 전, startDate>현재)/ONGOING(진행 중)/CLOSED(종료, endDate<현재). required: false schema: type: string - name: page in: query description: 조회할 페이지 번호 (1부터 시작, 기본값 1) required: false schema: type: integer format: int32 minimum: 1 example: 1 - name: pageSize in: query description: 페이지 크기(1~50, 기본 20) required: false schema: type: integer format: int32 maximum: 50 minimum: 1 example: 20 - $ref: '#/components/parameters/AcceptLanguage' in: header responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/PageResponseEventSummaryResponse' '429': $ref: '#/components/responses/RateLimitExceeded' components: parameters: AcceptLanguage: name: Accept-Language in: header description: >- 응답 지원 로케일: ko, en, ja, zh-CN, zh-TW, es, fr, de, pt, th, vi. 미지정 시 ko 기본값 required: false schema: type: string example: ko schemas: PageResponseEventSummaryResponse: type: object description: 페이지네이션 응답. page 는 1부터 시작하며, page > totalPages 인 경우 items 는 빈 배열이다. properties: totalItems: type: integer format: int64 description: 전체 항목 수 totalPages: type: integer format: int32 description: 전체 페이지 수 page: type: integer format: int32 description: 현재 페이지 번호 (1부터 시작) pageSize: type: integer format: int32 description: 페이지 크기 items: type: array description: 현재 페이지 항목 items: $ref: '#/components/schemas/EventSummaryResponse' required: - items - page - pageSize - totalItems - totalPages EventSummaryResponse: type: object properties: eventId: type: string description: 이벤트 ID example: 8H2KQ9XJ4P eventName: type: string description: 이벤트명 example: 2026 AI 컨퍼런스 eventCategories: type: array description: 이벤트 카테고리 items: type: string eventSubjects: type: array description: 이벤트 주제 items: type: string startAt: type: string description: 시작 일시 example: 2026-09-01T10:00 endAt: type: string description: 종료 일시 example: 2026-09-01T18:00 eventOpenType: type: string description: '진행 방식: OFFLINE(오프라인)/ONLINE(온라인)/ON_OFFLINE(온·오프라인)/TBD(미정)' enum: - OFFLINE - ONLINE - ON_OFFLINE - TBD example: OFFLINE location: oneOf: - $ref: '#/components/schemas/LocationResponse' - type: 'null' bannerUrl: type: - string - 'null' description: 배너 이미지 URL hosts: type: array description: 호스트 목록 items: $ref: '#/components/schemas/EventHostResponse' stats: $ref: '#/components/schemas/EventStatsResponse' description: 누적 통계 webUrl: type: string description: 로켓펀치 페이지 URL required: - endAt - eventCategories - eventId - eventName - eventOpenType - eventSubjects - hosts - startAt - stats - webUrl ErrorResponse: description: 공통 에러 응답 properties: code: type: string description: 에러 코드 (문서 에러 코드 표 참조) example: C0005 message: type: string description: 사람이 읽을 수 있는 에러 메시지 example: 요청 값이 올바르지 않습니다. timestamp: type: string format: date-time example: '2026-05-20T09:00:00' details: oneOf: - type: string description: 문제가 된 입력 항목 example: startDate - type: 'null' required: - code - message - timestamp LocationResponse: type: object properties: country: type: - string - 'null' description: 국가 코드(ISO alpha-2) example: KR region: type: - string - 'null' description: 광역 행정구역 example: 서울특별시 locality: type: - string - 'null' description: 시/군/구 example: 강남구 placeName: type: - string - 'null' description: 장소명 example: 코엑스 그랜드볼룸 address: type: - string - 'null' description: 주소(도로명/지번) example: 서울특별시 강남구 영동대로 513 addressDetail: type: - string - 'null' description: 건물 내 상세 위치 example: B1 그랜드볼룸 directions: type: - string - 'null' description: 찾아오는 길/교통편 안내 example: 2호선 삼성역 5번출구 도보 5분 latitude: type: - number - 'null' description: 위도 longitude: type: - number - 'null' description: 경도 EventHostResponse: type: object properties: hostType: type: string description: 호스트 유형 enum: - COMPANY example: COMPANY name: type: string description: 호스트명 id: type: - string - 'null' description: 회사 식별자(handle) profileImageUrl: type: - string - 'null' description: 프로필 이미지 URL roles: type: array description: 역할 목록 enum: - ORGANIZER - SPONSOR - PARTNER items: type: string required: - hostType - name - roles EventStatsResponse: type: object properties: viewCount: type: - integer - 'null' format: int64 description: 조회수 guestCount: type: - integer - 'null' format: int64 description: 참여자 수(비공개면 null) responses: RateLimitExceeded: description: >- Rate limit 초과. App Key 기준 전역 한도(분당 60 / 일 5,000) 또는 작업별 세부 한도(분/시/일)를 초과하면 응답한다. 작업별 세부 한도 초과 시 `X-RP-RateLimit-Scope` 헤더로 작업 구분이 제공된다. 현재 기본 한도는 문서 상단 Rate Limit 표를 참조한다. headers: Retry-After: description: 재시도까지 대기 초 schema: type: integer format: int32 X-RP-RateLimit-Remaining: description: 현재 분 남은 호출 수 schema: type: integer format: int32 X-RP-RateLimit-Scope: description: 작업별 세부 한도를 초과한 경우의 작업 구분. 전역 한도만 초과한 경우 헤더 없음. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: apiKey: type: apiKey name: X-RP-API-Key in: header ````