# Minecraft Mp — 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.

> Search and discover Minecraft multiplayer servers with detailed information like player counts, statistics, and voting data. Ping servers, filter by specific criteria, and access comprehensive server lists and historical performance metrics all in one place.

**Category:** Entertainment | **Website:** [minecraft-mp.com/](https://minecraft-mp.com/) | **Docs:** [parse.bot/marketplace/51dc62a0-52d7-4eab-ae48-982d10de82f1/minecraft-mp-com-api](https://parse.bot/marketplace/51dc62a0-52d7-4eab-ae48-982d10de82f1/minecraft-mp-com-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-minecraft-mp-com-api-51dc62a0/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_filtered_list

Get servers filtered by a specific country, version, type, or theme. Use slugs from get_filters endpoint. Version slugs use underscores instead of dots (e.g. '1_21_1' for version 1.21.1).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filter_type` | string | Yes | Filter type. Accepted values: 'country', 'version', 'type', 'theme'. |
| `page` | integer | No | Page number for pagination. |
| `slug` | string | Yes | Filter slug value (e.g. 'united-states-of-america' for country, '1_21_1' for version, 'survival' for type, 'medieval' for theme). Obtainable from get_filters endpoint. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/get_filtered_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter_type":"<string>","page":"<integer>","slug":"<string>"}'
```

### get_filters

Get available filter values for countries, versions, types, or themes. Returns filter options with slugs for use with get_filtered_list.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filter_type` | string | Yes | Filter category. Accepted values: 'countries', 'versions', 'types', 'themes'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/get_filters \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter_type":"<string>"}'
```

### get_server_details

Get full details for a specific server by its numeric ID. Returns all available metadata including name, address, MOTD, players, location, version, uptime, votes, rank, and registration info.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `server_id` | string | Yes | The numeric server ID (e.g. '179012'). Obtainable from get_server_list results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/get_server_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"<string>"}'
```

### get_server_list

Get the main paginated list of Minecraft servers ranked by popularity. Returns 25 servers per page with basic info (rank, name, address, version, players, status).

**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-minecraft-mp-com-api-51dc62a0/get_server_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### get_server_ping

Get geo-latency information for a server from multiple worldwide locations. Returns ping measurements showing latency from various regions.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `server_id` | string | Yes | The numeric server ID (e.g. '179012'). Obtainable from get_server_list results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/get_server_ping \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"<string>"}'
```

### get_server_statistics

Get historical statistics (players, uptime, rank, votes) for a server over a specified time period. Returns arrays of date labels and corresponding data values for each metric.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `period` | string | No | Time period for statistics. Accepted values: 'daily', 'weekly', 'monthly'. |
| `server_id` | string | Yes | The numeric server ID (e.g. '179012'). Obtainable from get_server_list results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/get_server_statistics \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"<string>","server_id":"<string>"}'
```

### get_server_vote_page

Get the monthly vote leaderboard for a server. Returns top voters with their nicknames and vote counts for the current month.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `server_id` | string | Yes | The numeric server ID (e.g. '179012'). Obtainable from get_server_list results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/get_server_vote_page \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"<string>"}'
```

### get_special_list

Get special curated lists of servers sorted by the specified criteria. The 'random' list type redirects to a random server's detail page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `list_type` | string | Yes | List type. Accepted values: 'latest', 'updated', 'random', 'most-played'. |
| `page` | integer | No | Page number for pagination (not applicable when list_type is 'random'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/get_special_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_type":"<string>","page":"<integer>"}'
```

### search_servers

Search and filter servers by various criteria including keyword, version, country, theme, tags, and sort order. Returns matching servers via AJAX search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Country slug filter. |
| `keyword` | string | No | Search keyword to match against server names and descriptions. |
| `orderby` | string | No | Sort order field. Omitting defaults to 'rank'. |
| `tags` | string | No | Comma-separated tags to filter by (e.g. 'survival,pvp'). Tag names use lowercase with underscores. |
| `theme` | string | No | Theme filter slug. |
| `version` | string | No | Minecraft version filter (e.g. '1.21.1'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-minecraft-mp-com-api-51dc62a0/search_servers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","keyword":"<string>","orderby":"<string>","tags":"<string>","theme":"<string>","version":"<string>"}'
```