# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/minecraft-mp/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/minecraft-mp/get-filtered-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/get-filters \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/get-server-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/get-server-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/get-server-ping \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/get-server-statistics \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/get-server-vote-page \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/get-special-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/minecraft-mp/search-servers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","keyword":"<string>","orderby":"<string>","tags":"<string>","theme":"<string>","version":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.