Web API 레퍼런스

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/json`	JSON 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": {}
}

시작하기

SDK 기본

Web API

데이터와 콘텐츠

운영과 연동

소셜과 실시간

기본 URL

API 문서

공통 헤더

호출 예시

주요 API 영역

오류 형식

​기본 URL

​API 문서

​공통 헤더

​호출 예시

​주요 API 영역

​오류 형식

기본 URL

API 문서

공통 헤더

호출 예시

주요 API 영역

오류 형식