# Topg — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Discover and compare Minecraft servers by version, type, location, and player count, plus track voting scores and historical player data to find the best server for your gameplay. Search across multiple game categories, view newly launched servers, and submit your own server votes to help others discover quality gaming communities.

**Category:** Entertainment | **Website:** [topg.org/](https://topg.org/) | **Docs:** [parse.bot/marketplace/5cccb92a-feb5-403e-a3e3-0818838e8100/topg-org-api](https://parse.bot/marketplace/5cccb92a-feb5-403e-a3e3-0818838e8100/topg-org-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_game_categories

Retrieve all game categories listed on the site, including their URL slugs. Use the slug with get_servers_by_game to fetch servers for non-Minecraft games.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_game_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_minecraft_server_countries

Retrieve all countries available for server filtering on the site. Useful for discovering valid inputs for get_minecraft_servers_by_country.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_server_countries \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_minecraft_server_details

Retrieve full details for a specific Minecraft server by its numeric ID, including player history (last 24h), supported versions, server types, description, website, and discord link.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `server_id` | string | Yes | Numeric server ID (e.g. '675337'). Obtainable from get_minecraft_server_list or search_servers results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_server_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"<string>"}'
```

### get_minecraft_server_list

Retrieve the ranked list of Minecraft servers, 20 per page. Servers are ordered by their TopG rank (vote-based). Pagination via integer page number.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_server_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### get_minecraft_server_types

Retrieve all available server type/mod filter tags listed on the site. Useful for discovering valid inputs for get_minecraft_servers_by_type.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_server_types \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_minecraft_server_versions

Retrieve all available Minecraft version filter options listed on the site. Useful for discovering valid inputs for get_minecraft_servers_by_version.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_server_versions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_minecraft_servers_by_country

List Minecraft servers filtered by hosting country. Returns up to 20 servers. Use get_minecraft_server_countries to discover valid country names.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | Yes | Country name (e.g. 'Germany', 'France', 'United States'). Use get_minecraft_server_countries to discover available values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_servers_by_country \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>"}'
```

### get_minecraft_servers_by_type

List Minecraft servers filtered by type or mod tag. Returns up to 20 servers. Use get_minecraft_server_types to discover valid type strings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | Server type/mod tag (e.g. 'Survival', 'PVP', 'Skyblock', 'Factions'). Use get_minecraft_server_types to discover available values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_servers_by_type \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"<string>"}'
```

### get_minecraft_servers_by_version

List Minecraft servers filtered by game version. Returns up to 20 servers matching the specified version. Use get_minecraft_server_versions to discover valid version strings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `version` | string | Yes | Minecraft version string (e.g. '1.21.4', '1.19.x', 'Latest'). Use get_minecraft_server_versions to discover available values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_minecraft_servers_by_version \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version":"<string>"}'
```

### get_new_minecraft_servers

Retrieve the most recently added Minecraft servers. Returns up to 20 servers ordered by addition date (newest first).

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_new_minecraft_servers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_server_player_history

Retrieve the online player count history (last 24 hours) for a specific server. Each entry is a [timestamp_ms_string, player_count_integer] pair extracted from the server's chart data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `server_id` | string | Yes | Numeric server ID (e.g. '675337'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_server_player_history \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"<string>"}'
```

### get_server_vote_score

Extract the vote score and rank for a specific Minecraft server from the server detail page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `server_id` | string | Yes | Numeric server ID (e.g. '675337'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_server_vote_score \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"<string>"}'
```

### get_servers_by_game

Retrieve the ranked server list for a non-Minecraft game category. Returns up to 20 servers. Use get_game_categories to discover valid game slugs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `game_slug` | string | Yes | Game category slug from get_game_categories (e.g. 'runescape-private-servers', 'wow-private-servers', 'terraria-servers'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/get_servers_by_game \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"game_slug":"<string>"}'
```

### search_servers

Search for servers across all game categories by keyword. Returns matching servers from all games listed on TopG, not just Minecraft.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g. 'survival', 'PVP', 'skyblock'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/search_servers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### submit_server_vote

Submit a vote for a specific Minecraft server. Requires an in-game username. Returns 'voted' on success, 'already_voted' if the IP has already voted today, or 'submitted' if the form was accepted but final status is ambiguous.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `server_id` | string | Yes | Numeric server ID (e.g. '675337'). |
| `username` | string | Yes | In-game Minecraft username to vote with. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-topg-org-api-5cccb92a/submit_server_vote \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"<string>","username":"<string>"}'
```