> ## 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 Reference

> Call the public HyperX APIs from web clients and server-side tools.

Use the Web API when you are not using the Unity SDK and need to call public HyperX Core endpoints from a web client, server-side tool, or operation automation.

## Base URL

```text theme={null}
https://core.hyperx.dev
```

## API Documentation

* ReDoc: `https://core.hyperx.dev/reference`
* Swagger UI: `https://core.hyperx.dev/swagger`
* OpenAPI JSON: `https://core.hyperx.dev/openapi.json`

Use the OpenAPI documentation for each endpoint's method, path, query parameters, request body, and response body. JSON property names use `snake_case`.

ReDoc and Swagger UI group endpoints by OpenAPI tags in this order: `Project and Utilities`, `Users and Sessions`, `Data`, `Content`, `LiveOps`, `Purchases`, `Social`, `Support`, `Realtime`.

## Common Headers

| Header                                 |                     Required | Description                                       |
| -------------------------------------- | ---------------------------: | ------------------------------------------------- |
| `x-project-code`                       |    Yes for most project APIs | Project code from Console.                        |
| `Authorization: Bearer <access_token>` |   Yes for authenticated APIs | Access token returned after login.                |
| `Content-Type: application/json`       | Yes when sending a JSON body | Marks the request body as JSON.                   |
| `x-trace-id`                           |                           No | ID used to trace a flow across multiple requests. |
| `x-request-id`                         |                           No | ID for one request.                               |

Do not put Console API keys, provider credentials, or server secrets in browser code. Web clients should only store values needed for public client flows, such as the project code and player session tokens.

## Call Examples

Check that a project code is available.

```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}`);
}
```

After login, use the returned access token to fetch the current user.

```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();
```

When the access token expires, send the refresh token to `/v1/users/session/refresh` to issue a new session.

## API Areas

| Area                  | Main Features                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| Project and Utilities | Project lookup, server time, supported countries, region detection                              |
| Users                 | Guest/custom/social login, refresh, logout, current user, characters, account deletion/recovery |
| Data                  | Shared data, user data, character data                                                          |
| Content               | Public Storage, game configs, probability tables                                                |
| LiveOps               | Rankings, coupons, game logs, operation content, push devices                                   |
| Purchases             | Store purchase validation, purchase history, refund/cancel webhooks                             |
| Social                | Search, random lookup, friends, mail, messages, guilds, guild invites/goods, notifications      |
| Support               | Ticket creation, current-user ticket list/detail, replies, attachment metadata                  |
| Realtime              | Notification stream, chat channels, messages, acknowledgements, reports                         |

## Error Shape

Errors return JSON. Branch on the HTTP status and `code`; include `trace_id` and `request_id` when contacting support or checking logs.

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