Web API 레퍼런스 - HyperX Docs

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, 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
소셜	검색, 랜덤 조회, 친구, 우편, 쪽지, 길드, 알림
실시간	알림 스트림, 채팅 채널, 메시지, 읽음 위치, 신고

오류 형식

오류 응답은 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": {}
}

Documentation Index

​기본 URL

​API 문서

​공통 헤더

​호출 예시

​주요 API 영역

​오류 형식