API reference

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.

Base URLhttps://ludoapi.in

Quick start

  1. Create a free account. New accounts get trial credits so you can test right away.
  2. Open Dashboard → API key and copy your key.
  3. 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.

Header
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: 404 room not found and 402 room 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 502 upstream 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:

EndpointPathCost

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.

FieldTypeDescription
successbooleantrue when the call worked, false otherwise.
requestIdstringUnique ID for this call. It also appears in your dashboard request log. Quote it when you contact support.
creditsUsednumberCredits charged for this call (0 when refunded or on an unlimited plan).
creditsRemainingnumberYour balance after this call.
dataobjectThe result. Its shape is documented under each endpoint.
messagestringOnly 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.

StatusMeaningCharged?
401API key missing or invalid.No
402Insufficient credits. Message is Insufficient credits and the body includes creditsRequired. Top up or change plan.No
402Room requires coins. Message mentions coins, for example Room requires coins to join. The room has an entry fee, so we cannot read it.Yes
403Account disabled, plan expired, or the request came from an IP or domain that is not on your allowlist.No
404Room not found. The code is wrong or the room no longer exists.Yes
429Rate limit reached (60 requests per minute per key).No
502LudoKing did not answer or returned an error. Safe to retry after a few seconds.No, refunded
To handle 402 correctly, branch on the message: if it is 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.
Need a hand?

Send us the requestId and what you expected. We usually reply within one working day.

support@ludoapi.in