> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Web API 레퍼런스

> 웹 클라이언트와 서버 사이드 도구에서 HyperX 공개 API를 호출하는 방법을 확인합니다.

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

## 기본 URL

```text theme={null}
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, 서버 비밀값을 포함하지 마세요. 웹 클라이언트에는 프로젝트 코드와 플레이어 세션 토큰처럼 공개 클라이언트 흐름에 필요한 값만 보관합니다.

## 호출 예시

프로젝트 코드를 확인합니다.

```js theme={null}
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으로 현재 유저를 조회합니다.

```js theme={null}
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`를 함께 전달합니다.

```json theme={null}
{
  "error": "unauthorized",
  "code": "UNAUTHORIZED",
  "message": "unauthorized",
  "service": "core",
  "trace_id": "trace_123",
  "request_id": "request_123",
  "context": {}
}
```