메인 콘텐츠로 건너뛰기
Web API는 Unity SDK를 사용하지 않는 웹 클라이언트, 서버 사이드 도구, 운영 자동화에서 HyperX Core 공개 엔드포인트를 직접 호출할 때 사용합니다.

​
기본 URL

https://core.hyperx.dev

​
API 문서

  • ReDoc: https://core.hyperx.dev/reference
  • Swagger UI: https://core.hyperx.dev/swagger
  • OpenAPI JSON: https://core.hyperx.dev/openapi.json
OpenAPI 문서에서 각 엔드포인트의 method, path, query parameter, request body, response body를 확인합니다. JSON 프로퍼티명은 snake_case를 사용합니다. ReDoc와 Swagger UI는 OpenAPI 태그 기준으로 Project and Utilities, Users and Sessions, Data, Content, LiveOps, Purchases, Social, Support, Realtime 순서로 엔드포인트를 묶어 보여줍니다.

​
공통 헤더

헤더필수설명
x-project-code대부분의 프로젝트 API에서 예Console에서 확인한 프로젝트 코드입니다.
Authorization: Bearer <access_token>인증 API에서 예로그인 후 받은 access token입니다.
Content-Type: application/jsonJSON body 전송 시 예요청 body가 JSON임을 나타냅니다.
x-trace-id아니오여러 요청을 하나의 흐름으로 추적할 때 사용할 ID입니다.
x-request-id아니오요청 한 건을 구분하는 ID입니다.
브라우저에 Console API key, provider credential, 서버 비밀값을 포함하지 마세요. 웹 클라이언트에는 프로젝트 코드와 플레이어 세션 토큰처럼 공개 클라이언트 흐름에 필요한 값만 보관합니다.

​
호출 예시

프로젝트 코드를 확인합니다. 
const baseUrl = "https://core.hyperx.dev";
const projectCode = "PROJECT_CODE";

const response = await fetch(`${baseUrl}/v1/project/${projectCode}`);

if (!response.ok) {
  throw new Error(`HyperX project lookup failed: ${response.status}`);
}
로그인 이후 받은 access token으로 현재 유저를 조회합니다. 
const meResponse = await fetch(`${baseUrl}/v1/users/me`, {
  headers: {
    "x-project-code": projectCode,
    Authorization: `Bearer ${accessToken}`,
    "x-request-id": crypto.randomUUID(),
  },
});

const me = await meResponse.json();
access token이 만료되면 /v1/users/session/refresh에 refresh token을 보내 새 세션 토큰을 발급받습니다.

​
주요 API 영역

영역대표 기능
프로젝트/유틸리티프로젝트 조회, 서버 시간, 지원 국가, 지역 감지
유저게스트/커스텀/소셜 로그인, 세션 갱신, 로그아웃, 현재 유저, 캐릭터, 계정 탈퇴/복구
데이터공유 데이터, 유저 데이터, 캐릭터 데이터
콘텐츠Public Storage, 게임 설정, 확률표
LiveOps랭킹, 쿠폰, 게임 로그, 운영 콘텐츠, 푸시 디바이스
결제스토어 구매 검증, 구매 이력, 환불/취소 webhook
소셜검색, 랜덤 조회, 친구, 우편, 쪽지, 길드, 길드 초대/goods, 알림
Support문의 생성, 내 문의 목록/상세, 답변, 첨부 metadata
실시간알림 스트림, 채팅 채널, 메시지, 읽음 위치, 신고

​
오류 형식

오류 응답은 JSON으로 반환됩니다. 클라이언트에서는 HTTP status와 code를 기준으로 분기하고, 지원 문의나 로그 확인이 필요하면 trace_id와 request_id를 함께 전달합니다. 
{
  "error": "unauthorized",
  "code": "UNAUTHORIZED",
  "message": "unauthorized",
  "service": "core",
  "trace_id": "trace_123",
  "request_id": "request_123",
  "context": {}
}