# Add GamesVS to your game

Track scores, show leaderboards, and display player achievements without building
those systems yourself. You can use your AI coding tool to connect your game.

**Start here:** [Download the API schema](https://gamesvs.com/api-guide/openapi)
and [the AI setup instructions](https://gamesvs.com/api-guide/ai-prompt).
Add both files to your game project or attach them to your coding assistant.
The schema describes every available request, field, and response.

## 1. Register your game

Visit [GamesVS Developers](https://gamesvs.com/developers/), create an account,
and choose **Register a game**.

You’ll receive:

- **Game slug:** your game’s unique ID, such as `space-racer`.
- **Server token:** your game’s secret API key. Copy it when it appears; you cannot view it again later.

Save the token in your hosting provider’s **server secrets** settings. Keep it out
of your game’s browser code, Git repository, and AI chat. If you lose it, create
another token in your developer dashboard and revoke the old one.

## 2. Tell your AI coding tool what to build

Download the schema and AI setup instructions above, then paste this into your
coding tool. Replace `YOUR_GAME_SLUG` with the slug from your dashboard.

```text
Connect my game to GamesVS using the attached API schema and setup instructions.

My game slug is YOUR_GAME_SLUG.
API base URL: https://api.gamesvs.com/v1
API schema: https://gamesvs.com/api-guide/openapi
Setup instructions: https://gamesvs.com/api-guide/ai-prompt

First inspect my project and explain what can work with its current hosting
and login setup. Add a leaderboard, player stats, achievement display, and
completed-game score submissions where supported.

Keep my server token in server-only secret configuration named
GAMESVS_SERVER_TOKEN. Tell me where to add it; do not ask me to paste it here.

Do not assume my game's user IDs are GamesVS player IDs. If we do not have a
secure account link, explain that gap before enabling official score submissions.
If the project has no backend, explain what is needed rather than exposing the token.

Follow the schema, preserve run IDs when retrying, and test the integration.
Do not invent login, account-linking, or achievement-creation endpoints.
```

Your assistant can use the downloadable schema in any language. It is an
**OpenAPI 3.1 JSON file**: upload it to your coding assistant, import it into an
API tool, or use it with an OpenAPI client generator. The schema supplies the
contract; your assistant still needs to connect it to your game’s code and hosting.

## 3. Choose how your game connects

| Where your game runs | How to connect |
| --- | --- |
| Your own website, with a backend or server functions | Your backend calls GamesVS. Keep the token there. Validate results and identify the player before sending official scores. |
| Your own website, with browser code only | Add a backend or server functions first. Do not put the server token in the browser. Direct calls from another website are not currently supported. |
| A game hosted on gamesvs.com | A signed-in player can send browser results using their GamesVS session. These results are personal, unverified scores. Official scores still need a trusted backend. |

**Player accounts need a separate link.** A server token identifies your game,
not the person playing it. Each player needs a GamesVS account and a public
GamesVS player ID. GamesVS can return that ID when the player is signed in on
GamesVS, but automatic account linking for games on other websites is not yet
available. Your backend must have a trustworthy link between its signed-in player
and their GamesVS ID before sending official results. A player typing an ID into
a form does not prove they own that account.

You can start with public game information and leaderboard reads through your
backend while player linking is being arranged. No token is needed for those reads.

## What your game can use

All paths below start with `https://api.gamesvs.com/v1`. Replace `{game}` with
your game slug and `{player}` with a real GamesVS player ID.

| Feature | Request | What you get |
| --- | --- | --- |
| Check the connection | `GET /` | API name and version |
| Find games | `GET /games` | Active games |
| Check your game | `GET /games/{game}` | Game ID and title |
| Identify a signed-in GamesVS player | `GET /players/me` | Their player ID and browser submission token; requires their GamesVS session |
| Save a completed game | `POST /games/{game}/runs` | Saved score and any achievements unlocked |
| Show a leaderboard | `GET /games/{game}/leaderboard` | Each player’s highest official score, ranked highest first |
| Show player stats | `GET /players/{player}/games/{game}/stats` | Best score, games played, and totals for your counters |
| Show achievements | `GET /players/{player}/games/{game}/achievements` | Available achievements and whether that player has unlocked them |

**Official results** come from your backend using a server token. GamesVS trusts
your backend to check the result; it does not provide automatic cheat detection.
Browser-only results do not appear on official leaderboards or unlock official
achievements. Ask GamesVS to set up your achievement rules; creating them through
the API is not currently supported.

## What to send when a game ends

Your backend sends `POST /games/{game}/runs` with these headers:

```http
Authorization: Bearer YOUR_SERVER_TOKEN
Content-Type: application/json
```

Example body — the player ID below is a placeholder, not a usable test account:

```json
{
  "player_id": "0123456789abcdef0123456789abcdef",
  "submission_id": "match-001-player-42",
  "score": 1250,
  "stats": {
    "coins_collected": 40,
    "enemies_defeated": 12
  }
}
```

- `player_id` is the linked player’s GamesVS ID, not their email or your game’s internal user ID.
- `submission_id` identifies this completed run. Save it before sending. If the request fails, retry the **same ID and same result** so the score is not counted twice.
- `score` is a whole number, zero or greater.
- `stats` is optional. Send counters for **this run**, such as coins collected. GamesVS adds them to the player’s totals. Do not send their lifetime totals each time.

Use simple counter names like `coins_collected` or `play_time_ms`. Scores and
counter values must be whole numbers from 0 to 1,000,000,000,000. You can send up
to 32 counters per run. The schema includes the complete validation rules.

A new result returns HTTP `201`. An identical retry returns `200` with
`replayed: true`. Changing a previously submitted result under the same ID returns
`409`; tell your assistant to investigate rather than create a duplicate score.

For games hosted on GamesVS, use the same-origin base URL
`https://gamesvs.com/api/v1` for browser calls so the player’s login session is
available. Browser submissions use the signed-in player’s
session and `X-SecurityID` from `/players/me`. They omit `player_id` and the server
token. The schema describes this alternative.

## Check it works before releasing

Ask your coding assistant to check these in your project:

1. Your game information and leaderboard load successfully.
2. Your token stays on the server and never appears in browser requests or built game files.
3. A linked test player can submit one result and see the correct stats and leaderboard entry.
4. Retrying that exact result does not add the score or counters twice.
5. Achievements display both locked and unlocked states correctly.
6. A temporary GamesVS outage shows a useful message and keeps pending results for retry.

Stats totals arrive as text so large numbers stay accurate. Leaderboards return
25 players by default; use `limit` and `offset` for more. Your assistant can read
these details and the response shapes directly from the schema.

## If something goes wrong

| What you see | What to check |
| --- | --- |
| `401` | Missing, incorrect, or revoked server token; or a player who needs to sign in |
| `403` | Token belongs to another game, or a browser session needs a fresh submission token |
| `404` | Wrong game slug, inactive game, or player profile that does not exist |
| `409` | A saved run ID was reused with different results |
| `422` | Missing fields or invalid values; give the error to your coding assistant |
| `429` | Too many requests; wait for the supplied retry delay |
| Connection error or `5xx` | Retry later using the original run ID and result |

Avoid polling on every frame. The API allows 600 requests per IP per minute.
Errors normally contain `error.code` and `error.message`; successful responses
contain `data`. Your assistant should also handle connection failures or responses
that are not JSON.

## Downloads for your project

- [API schema](https://gamesvs.com/api-guide/openapi) — the full OpenAPI contract to give your AI tool or import into an API client.
- [AI setup instructions](https://gamesvs.com/api-guide/ai-prompt) — a reusable integration brief to add to your project.
- [JavaScript helper](https://gamesvs.com/api-guide/client) — optional ready-made request functions for JavaScript projects.
- [This guide](https://gamesvs.com/api-guide/guide) — a copy you can attach to your coding assistant.