LudoAPI documentation
LudoAPI gives you LudoKing room data over plain HTTPS: room type, results, token positions, cuts, progress, timeouts and new rooms. Every endpoint takes a small JSON body and returns JSON.
https://ludoapi.inQuick start
- Create a free account. New accounts get trial credits so you can test right away.
- Open Dashboard → API key and copy your key.
- Send your first request. Replace the room code with one from your game.
Authentication
Send your API key in the x-api-key header on every request. Keys start with la_live_ followed by 32 characters.
x-api-key: la_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- Keep the key on your server. Do not put it in a mobile app, browser JavaScript or a public repository.
- We only store a hash of your key. In the dashboard it stays masked until you confirm your password to reveal it.
- If a key leaks, rotate it from the dashboard. The old key stops working immediately.
- On plans with an IP or domain limit, requests are only accepted from the addresses in your allowlist.
Credits and refunds
Each endpoint has a credit cost. When a request comes in, we reserve its cost from your balance before calling LudoKing, then settle it once we have an answer.
- You are charged for successful responses (2xx) and for definitive answers about the room:
404room not found and402room requires coins. Those are real results, and the lookup still happened. - You are refunded automatically when the failure is on our side or upstream: any 5xx, a timeout or a
502upstream error. The reserved credits go straight back to your balance. - Unlimited plans are not charged per call, but the IP and domain allowlist on the plan is enforced.
- Requests rejected before the call (bad key, rate limit, insufficient credits) never cost anything.
Every response tells you what the call cost (creditsUsed) and what is left (creditsRemaining). Current costs per call:
| Endpoint | Path | Cost |
|---|
Rate limits
Each API key can make up to 60 requests per minute across all endpoints. Going over returns 429 Too Many Requests and is not charged.
If you poll a live game, once every few seconds per room is plenty. Back off and retry after a short wait when you see a 429.
Response format
All endpoints return the same envelope. The endpoint-specific payload is always inside data.
| Field | Type | Description |
|---|---|---|
success | boolean | true when the call worked, false otherwise. |
requestId | string | Unique ID for this call. It also appears in your dashboard request log. Quote it when you contact support. |
creditsUsed | number | Credits charged for this call (0 when refunded or on an unlimited plan). |
creditsRemaining | number | Your balance after this call. |
data | object | The result. Its shape is documented under each endpoint. |
message | string | Only on errors: a human-readable reason. |
Errors
Errors use standard HTTP status codes with success: false and a message. Two different situations share status 402, so check the message to tell them apart.
| Status | Meaning | Charged? |
|---|---|---|
| 401 | API key missing or invalid. | No |
| 402 | Insufficient credits. Message is Insufficient credits and the body includes creditsRequired. Top up or change plan. | No |
| 402 | Room requires coins. Message mentions coins, for example Room requires coins to join. The room has an entry fee, so we cannot read it. | Yes |
| 403 | Account disabled, plan expired, or the request came from an IP or domain that is not on your allowlist. | No |
| 404 | Room not found. The code is wrong or the room no longer exists. | Yes |
| 429 | Rate limit reached (60 requests per minute per key). | No |
| 502 | LudoKing did not answer or returned an error. Safe to retry after a few seconds. | No, refunded |
Insufficient credits, ask the account owner to recharge. Otherwise the room itself needs coins and you should tell your player to use a free room.Send us the requestId and what you expected. We usually reply within one working day.