# CrewPlay Public/Internal API Reference

Stand: 2026-07-06

Diese API ist read-only und fuer externe Dashboards, Servermanager-Views, Backup-Uebersichten, Plugin-/Eventdaten, Loids-Pluginstatus und Bingo-Leaderboards gedacht. Sie ist in Cache-Klassen getrennt, damit Live-Daten schnell bleiben und schwere Inventare nicht bei jedem Request neu gescannt werden.

## Base URLs

- Primary: `https://mc-api.crewplay.de`
- Fallback: `https://pack.crewplay.de/api`
- OpenAPI: `/openapi.json`
- HTML-Doku/Testkonsole: `/docs`
- Markdown-Doku: `/docs/PUBLIC_API_REFERENCE_2026-07-06.md`

## Auth

Jeder `/v1/*` Endpoint braucht einen API-Token.

```bash
curl -H "X-API-Token: crewplay2026" https://mc-api.crewplay.de/v1/servers
curl -H "Authorization: Bearer crewplay2026" https://mc-api.crewplay.de/v1/servermanager
curl "https://mc-api.crewplay.de/v1/loids/block-of-the-day?token=crewplay2026"
```

Token-Tiers:

- `crewplay-test`: Demo, 20 Requests pro Minute
- `crewplay2026`: Full-read, 600 Requests pro Minute

Rate-Limit Header:

- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-API-Tier`

## Cache-Klassen

| Klasse | TTL | Inhalt |
| --- | ---: | --- |
| `dynamic` | 60s | Containerstatus, Minecraft-Ping, Spielerzahlen, Memory, Netzwerk |
| `servermanager` | 300s | Maintenance-Modi, Start-History, Join/Quit-Aktivitaet, LSB-Systemsnapshot |
| `events` | 300s | MythicMobs Boss-Spawner und AxEnvoy Airdrops |
| `loids` | 300s | LoidsDailyBlockRewards und LoidsBlessings |
| `leaderboards` | 600s | Survival, Skyblock und Bingo Leaderboards |
| `plugins` | 1800s | Plugin-JAR-Inventar, notable Plugins, MythicMobs-Zusammenfassung |
| `backups` | 3600s | Backup-Kategorien, aktuelle Dateien, Server-Gruppierung, bounded Size Samples |
| `members` | 43200s | Memberindex mit Live-Online-Overlay |
| `static` | 43200s | Welten, Storage, Dimensionen |
| `ops` | 60s | Full-read Ops-Uebersichten |

## Wichtige Endpoints

### Status und Spieler

```bash
GET /v1/servers
GET /v1/dynamic
GET /v1/status
```

`/v1/servers` liefert pro Server `online`, `state`, `players.online`, `players.max`, Spieler-Sample, Minecraft-Version, Memory und Netzwerkbytes.

### Servermanager

```bash
GET /v1/servermanager
```

Liefert Maintenance, Start-History, Join/Quit-Aktivitaet, recent Sessions und LSB-Systemsnapshot.

### Backups

```bash
GET /v1/backups
```

Liefert Summary, Kategorien, aktuelle Backup-Dateien und Gruppierung nach Server. Grosse Bereiche werden bounded gescannt, damit der Call dashboard-tauglich bleibt.

### Plugins und MysticMobs

```bash
GET /v1/plugins
GET /v1/plugins/summary
GET /v1/plugins/mythicmobs
```

### Loids Plugins

```bash
GET /v1/loids
GET /v1/loids/block-of-the-day
GET /v1/loids/loidsblockoftheday
GET /v1/loids/blessings
GET /v1/loids/loidsblessings
```

`/v1/loids/block-of-the-day` liefert pro Server:

- `current_date`
- `current_block`
- `scheduled_blocks`
- `pool.mode`
- `pool.entries`
- Streak-Einstellungen wie Freeze, Buyback und Milestones

`/v1/loids/blessings` liefert pro Server:

- `active_count`
- `active[].id`
- `active[].end_at`
- `active[].remaining_seconds`
- `expired`
- Hinweise, ob Statistics/Records-Dateien vorhanden sind

### Events

```bash
GET /v1/bosses
GET /v1/bosses?server=skyblock
GET /v1/bosses?server=survival&q=warden
GET /v1/airdrops
```

### Members

```bash
GET /v1/members?limit=50
GET /v1/members?status=online&sort=online
GET /v1/members?server=survival&q=WatcherLoid
GET /v1/members/profile?q=WatcherLoid
```

### Bingo Leaderboards

Alle Bingo-Boards akzeptieren `limit`, maximal 100.

```bash
GET /v1/leaderboards/bingo/summary?limit=5
GET /v1/leaderboards/bingo/ratings?limit=10
GET /v1/leaderboards/bingo/score?limit=10
GET /v1/leaderboards/bingo/points?limit=10
GET /v1/leaderboards/bingo/xp?limit=10
GET /v1/leaderboards/bingo/wins?limit=10
GET /v1/leaderboards/bingo/fastest?limit=10
GET /v1/leaderboards/bingo/fastest-wins?limit=10
GET /v1/leaderboards/bingo/achievements?limit=10
GET /v1/leaderboards/bingo/weekly-quests?limit=10
GET /v1/leaderboards/bingo/recent?limit=10
```

### Ops

```bash
GET /v1/ops
GET /v1/ops/overview
GET /v1/ops/performance
GET /v1/ops/activity
GET /v1/ops/capacity
GET /v1/ops/health
```

Ops-Endpoints brauchen Full-read Token.

## Docker-Mounts

Der API-Container liest nur read-only:

- `./servers:/data/servers:ro`
- `./backups:/data/backups:ro`
- `./data/controller:/data/controller:ro`
- `./data/lsb-external:/data/lsb-external:ro`

## Performance-Regeln

- Keine Write-/RCON-Kommandos ueber diese API.
- Minecraft-Spielerzahlen kommen aus dem read-only Status-Ping.
- Loids wird mit 300s gecached.
- Bingo-Leaderboards werden aus SQLite gelesen und mit 600s gecached.
- Backups und Plugins haben lange TTLs.
- Grosse Verzeichnisse werden bounded gescannt.
- Clients sollten die empfohlenen Poll-Intervalle aus `refresh_policy.recommended_poll_seconds` respektieren.