# Minecraft Java Server API — Guide for AI Agents

> Everything an AI agent needs to deploy and manage a Minecraft Java dedicated server on [supercraft.host](https://supercraft.host/minecraft-java-server-hosting/).

**Base API URL:** `https://claws.supercraft.host`

---

## Minecraft Java Plans & Pricing


### Plan L — Up to 30 players, Maximum CPU

| Period | Price | Product ID |
|--------|-------|------------|
| 1 month | $16 | `31319` |
| 3 months | $43 | `31323` |
| 6 months | $82 | `31327` |
| 12 months | $150 | `31331` |


### Plan M — Up to 10 players, Enhanced CPU

| Period | Price | Product ID |
|--------|-------|------------|
| 1 month | $9.99 | `31318` |
| 3 months | $27 | `31322` |
| 6 months | $51 | `31326` |
| 12 months | $94 | `31330` |


### Plan S — Up to 5 players, Standard CPU

| Period | Price | Product ID |
|--------|-------|------------|
| 1 month | $5.99 | `31317` |
| 3 months | $16 | `31321` |
| 6 months | $31 | `31325` |
| 12 months | $56 | `31329` |



### Which billing period should you choose?

- **1 month** -- Perfect for trying out the game or short-term events. No commitment, full flexibility.
- **3 months** -- Great value for committed players. You save about 10% compared to monthly billing.
- **6 months** -- For dedicated communities. Save about 14% and enjoy half a year of uninterrupted gameplay.
- **12 months** -- Best value! Save about 21%. Ideal for established clans and long-running worlds.

> For full feature comparison and marketing details, see the [Minecraft Java offer page](/dedicated-servers/minecraft-java-server-hosting-offer.md).

---

## Quick Reference: Key Endpoints

| Action | Endpoint | Auth |
|--------|----------|------|
| Minecraft Java plans & pricing | `GET /catalog/games/mnj` | No |
| All available games | `GET /catalog/games` | No |
| Server regions | `GET /catalog/regions` | No |
| Purchase Minecraft Java server | `POST /orders/purchase` | No |
| Login (existing user) | `POST /auth/login-link` | No |
| Claim API token | `GET /auth/claim?magic={token}` | No |
| List user's servers | `GET /servers` | Bearer |
| Server status | `GET /servers/{id}` | Bearer |
| Start/stop/restart | `POST /servers/{id}/start\|stop\|restart` | Bearer |
| Connection details | `GET /servers/{id}/connection` | Bearer |
| Read/update config | `GET/PUT /servers/{id}/config` | Bearer |
| Config options | `GET /servers/{id}/config/schema` | Bearer |
| Console command | `POST /servers/{id}/console` | Bearer |
| Server logs | `GET /servers/{id}/logs` | Bearer |
| Available games for plan | `GET /servers/{id}/available-games` | Bearer |
| Switch game (destructive) | `POST /servers/{id}/switch-game` | Bearer |

All authenticated endpoints require: `Authorization: Bearer {jwt_token}`

Trusted agent integrations should also send: `X-Agent-Key: sk_agent_...`
If no agent key is sent, the request is tracked as `unknown`.

**Cache busting:** Some agent platforms cache HTTP responses. For non-catalog endpoints (auth, servers, config), append `&_t=<unix_timestamp>` to avoid stale data. Example: `GET /auth/claim?magic=TOKEN&_t=1709912345`

---

## Workflow: New user wants a Minecraft Java server

### Step 1: Choose a plan

```
GET /catalog/games/mnj
```

This returns 3 plans (L, M, S) with pricing for 1, 3, 6, and 12 month periods. Recommend based on player count and budget:

- **Plan L** — Up to 30 players, Maximum CPU

- **Plan M** — Up to 10 players, Enhanced CPU

- **Plan S** — Up to 5 players, Standard CPU


Longer billing periods save money — suggest 3 months for committed players.

### Step 2: Purchase

Pick the `product_id` from the plan/period combination above.

```
POST /orders/purchase
Body: { "product_id": 31319 }

Response: {
  "magic": "a8f3k9x2m5p7...",
  "checkout_url": "https://supercraft.host/?add-to-cart=31319&magic=a8f3k9x2m5p7...",
  "product_name": "Minecraft Java Plan L - 1 Month",
  "price": "16",
  "currency": "USD",
  "expires_in_seconds": 3600
}
```

Give the user the `checkout_url`. It's a secure Stripe checkout — they create an account and pay.

### Step 3: Get API token

⚠️ **STOP — Send the checkout link to the user NOW.** Your response must contain the `checkout_url`. Do not call any tools or start polling before the message is delivered. If you run a curl/exec/cron command before replying, the user will never see the link.

**After** the user receives the link, set up a cron job to poll every 30 seconds:
```
curl -sL "https://claws.supercraft.host/auth/claim?magic=TOKEN"
```
If cron is not available, poll when the user sends their next message. Do NOT use `while/sleep` loops.

```
GET /auth/claim?magic=a8f3k9x2m5p7...

Response (paid): { "status": "ready", "token": "eyJhbG...", "user": { ... } }
Response (waiting): { "status": "pending" }
```

Token is valid for 1 hour. **Save the token** securely — environment variables, a secret manager, or agent-private memory. Never commit tokens to version control. Losing the token means re-authentication.

### Step 4: Install Minecraft Java

```
GET /catalog/regions
→ ne, w, ew, as

GET /servers
Authorization: Bearer {token}
→ find the server in PENDING status

POST /servers/{id}/install
Authorization: Bearer {token}
Body: { "game": "mnj", "region": "ew", "branch": "stable" }
```

Pick the closest region to the user. Installation takes 1-3 minutes.

### Step 5: Wait and deliver connection details

Poll every 8-10 seconds until status is `STARTED`:

```
GET /servers/{id}
Authorization: Bearer {token}
```

Then get connection details:

```
GET /servers/{id}/connection
Authorization: Bearer {token}

Response: {
  "server_data": {
    "address": "eu1.supercraft.host",
    "game_port": 10342,
    "connection_string": "eu1.supercraft.host:10342",
    "password": "k7m2x9",
    ...
  }
}
```

Give the user game-specific connection instructions for Minecraft Java.

### Step 6: Customize

```
GET /servers/{id}/config/schema    ← available Minecraft Java settings
GET /servers/{id}/config           ← current values
PUT /servers/{id}/config           ← update
POST /servers/{id}/restart         ← apply changes
```

Always restart after config changes.

---

## Existing user — authenticate and manage

```
POST /auth/login-link
Body: { "email": "user@example.com" }

Response: {
  "login_url": "https://supercraft.host/my-account/?magic=b7k2m9x5p3...",
  "claim_endpoint": "/auth/claim?magic=b7k2m9x5p3..."
}
```

⚠️ **Send the `login_url` to the user NOW — before calling any tools.** Do not start polling before the message is delivered. After the user receives it, set up a cron job to poll `/auth/claim` every 30 seconds, or poll on their next message. Do NOT use `while/sleep` loops. Once they log in, you get the API token.

**Common operations:**
- `POST /servers/{id}/start` / `stop` / `restart`
- `GET /servers/{id}/logs?lines=100`
- `POST /servers/{id}/console` with `{ "command": "..." }`
- `GET /servers/{id}/connection` for IP/port/password

---

## Server States

| Status | Meaning | Action |
|--------|---------|--------|
| `PENDING` | No game installed | Install |
| `INSTALLING` | Installing Minecraft Java | Wait |
| `STARTED` | Running, players can connect | Stop, restart, configure |
| `STOPPED` | Not running | Start, configure |
| `BROKEN_INSTALL` | Installation failed | Check logs, retry |
| `BROKEN_START` | Failed to start | Check logs, fix config |

On `BROKEN_*`: read logs with `GET /servers/{id}/logs` and look for errors.

---

## Error Handling

- `401/403` — re-authenticate via `POST /auth/login-link`
- `409` — server already in requested state (e.g., already running)
- `429` — rate limited, wait and retry
- If nothing works — contact support at support@supercraft.host or [Discord](https://discord.gg/WVhwGu6RCJ)

---

## More Resources

- [Full API Guide](/documentation-for-agents/getting-started.md) — complete reference with all workflows
- [Minecraft Java Plans & Pricing](/dedicated-servers/minecraft-java-server-hosting-offer.md) — detailed feature comparison
- [Minecraft Java on supercraft.host](https://supercraft.host/minecraft-java-server-hosting/) — human-readable landing page
- [OpenAPI Spec](/openapi.json) — machine-readable API schema
- [Interactive Docs](/docs) — Swagger UI

## Other Games

Supercraft.host offers hosting for 24 games.

| Game | Code | API Guide |
|------|------|-----------|
| Valheim | `vlh` | [Valheim Server API](/valheim-server-api) |
| Satisfactory | `stf` | [Satisfactory Server API](/satisfactory-server-api) |
| Palworld | `pal` | [Palworld Server API](/palworld-server-api) |
| Enshrouded | `ens` | [Enshrouded Server API](/enshrouded-server-api) |
| Project Zomboid | `prz` | [Project Zomboid Server API](/project-zomboid-server-api) |
| Factorio | `fac` | [Factorio Server API](/factorio-server-api) |
| V-Rising | `vrs` | [V-Rising Server API](/v-rising-server-api) |
| Vintage Story | `vst` | [Vintage Story Server API](/vintage-story-server-api) |
| Necesse | `nec` | [Necesse Server API](/necesse-server-api) |
| Terraria | `ter` | [Terraria Server API](/terraria-server-api) |
| Unturned | `unt` | [Unturned Server API](/unturned-server-api) |
| Hytale | `hyt` | [Hytale Server API](/hytale-server-api) |
| Counter-Strike 2 | `cs2` | [Counter-Strike 2 Server API](/counter-strike-2-server-api) |
| Rust | `rst` | [Rust Server API](/rust-server-api) |
| Humanitz | `hmz` | [Humanitz Server API](/humanitz-server-api) |
| Sons of the Forest | `sof` | [Sons of the Forest Server API](/sons-of-the-forest-server-api) |
| ARK: Survival Ascended | `arksa` | [ARK: Survival Ascended Server API](/ark-survival-ascended-server-api) |
| FiveM | `fiv` | [FiveM Server API](/fivem-server-api) |
| Minecraft Bedrock | `mcb` | [Minecraft Bedrock Server API](/minecraft-bedrock-server-api) |
| Icarus | `ics` | [Icarus Server API](/icarus-server-api) |
| Farming Simulator 25 | `fs25` | [Farming Simulator 25 Server API](/farming-simulator-25-server-api) |
| The Forest | `tfo` | [The Forest Server API](/the-forest-server-api) |
| Echoes of Elysium | `eoe` | [Echoes of Elysium Server API](/echoes-of-elysium-server-api) |

---
*[supercraft.host](https://supercraft.host) — Game Server Hosting Platform*