Code examples

Copy, paste, ship.

Working examples for every endpoint in cURL, JavaScript, Python and PHP, with real paths, parameters and response fields. Replace the placeholder key with your own from the panel.

Base URL
https://api.ugilabs.com
Authentication
Bearer <key>
Key format
UGI-xxxx-…
Success response
{ status, data }

Pick a language once: every example on this page switches with it.

01

Authentication

Every endpoint except /v1/status/{region} needs an API key. The examples below reuse the small ugi() helper defined here.

  • Prefer Authorization: Bearer <key>. X-API-Key works as well; ?api_key= leaks the key into logs.
  • CORS is open, but a key in browser code is public. Call the API from your server, or restrict the key to your origins in the panel.
  • A missing key returns 401 api_key_missing; a wrong or disabled one returns 401 api_key_invalid.
Reference in the docs

The key travels in the Authorization header; the outcome is one of three cases. · Sample view; names and numbers are fictional.

02

Discord bot

A complete discord.js v14 bot with a /rank slash command that replies with an embed.

  • Uses deferReply() so slow lookups do not hit Discord's 3-second limit.
  • Handles 404 and 429 with friendly messages instead of crashing.
  • Keep both tokens in environment variables, never in the code.
Reference in the docs

The embed the bot above sends for /rank: rank, RR, wins/games and the rank icon. · Sample view; names and numbers are fictional.

03

Player lookup

Find a player by Riot ID or PUUID. Names can contain spaces and non-Latin characters, so always URL-encode the name and tag.

  • ?region= (default eu) selects the region; level, card and title come from the player's latest match there.
  • ?enrich=false skips level, card and title and returns only puuid, name and tag; it is faster.
  • ?lang=tr returns card and title names in Turkish.
Reference in the docs

A profile card built from the card_details, title_details and account_level fields of /v1/account. · Sample view; names and numbers are fictional.

04

Rank and RR history

current_data holds the tier (0 = Unranked, 27 = Radiant), the RR within the tier and the wins and games of the current act. as_of is the time of the last competitive game.

  • Rank history takes ?size= from 1 to 10 (default 5).
  • ranked_rating_earned is the RR change of that game; won can be null when the result is unknown. tier_before, ranked_rating_before_update, refunded_rr and was_derank_protected explain promotions, demotions and refunds.
  • Both endpoints have PUUID versions: /v1/by-puuid/rank/… and /v1/by-puuid/rank-history/….
Reference in the docs

Current rank and RR come from /v1/rank; the RR change over the last games comes from /v1/rank-history. · Sample view; names and numbers are fictional.

05

Matches and scoreboards

Match history returns one summary per match from the requested player's point of view; match details return every player, team and round.

  • ?size= is capped by your plan: 5 (Basic), 10 (Advanced), 20 (Premium). ?mode= is applied before size; ?start= with pagination.next_start pages back.
  • In the summary, teams is an object keyed by team id (Blue, Red); in match details it is a list with team_id.
  • ?region= on /v1/match/{matchId} is optional; without it every region is tried.
  • /v1/stored-matches reads only from our match store (no Riot query cost) and adds a summary. The store fills up as matches are fetched, so it can have gaps.
Reference in the docs

Map, agent, K/D/A, ACS, score and result from /v1/matches; the score is read from the teams field. · Sample view; names and numbers are fictional.

06

Leaderboard

The ranked leaderboard of the active act. Pass actId (from /v1/content) for a past act.

  • size is 1–200 (default 50); start is an offset rounded down to a multiple of size, up to 10,000.
  • search filters the returned page by name; it does not search the whole leaderboard.
  • Anonymous players appear as Secret Agent with an empty tag_line and puuid: null.
Reference in the docs

The top 10 players from /v1/leaderboard. Players who hide their profile come back as Secret Agent with an empty tag and puuid: null. · Sample view; names and numbers are fictional.

07

Game content and status

Content lists agents, maps, weapon skins, game modes, seasons, player cards and titles. Use it to map ids to names and to find the active act.

  • locale accepts en-US and tr-TR; anything else returns 400 invalid_locale.
  • /v1/status/{region} needs no key and is limited to 60 requests per minute per IP. The status page has the full picture.
Reference in the docs

/v1/content gives agents, maps and the active act; /v1/status gives region health. · Sample view; names and numbers are fictional.

08

Error handling

Errors always have the shape {status, error, code, request_id}, sometimes with details. Branch on code, not on the message text.

  • Retry only rate_limited (429) and 503, and wait Retry-After seconds first.
  • Keep the request_id (also in the X-Request-Id header) when you report a problem.
Reference in the docs

Every error carries a code; the retryable ones are marked green. · Sample view; names and numbers are fictional.

09

Caching with ETag

Every 200 response carries an ETag. Send it back in If-None-Match: if the data has not changed you get 304 Not Modified with an empty body.

  • A 304 still counts toward your quota, but saves bandwidth and parsing.
  • X-Cache: HIT means the response came from the shared server cache; Age is how many seconds ago it was stored and X-Cache-TTL how many more seconds it counts as fresh for your plan (current values per plan are in the docs).
  • These snippets reuse BASE, API_KEY and session from the Authentication section.
Reference in the docs

The second request sends the same ETag; if nothing changed the body comes back empty. · Sample view; names and numbers are fictional.

10

Webhooks

When a player you track plays a new match, ugiAPI sends a signed POST to your server. These receivers verify X-UGI-Signature, drop duplicates and act on the event type.

  • The signature is sha256= + HMAC-SHA256(secret, timestamp + "." + raw_body); use the raw body and reject X-UGI-Timestamp values older than 5 minutes.
  • Return a 2xx within 5 seconds; otherwise the delivery is retried after 1, 5 and 30 minutes with the same X-UGI-Delivery.
  • One match can produce several events: each is a separate POST with the same changes object. The panel's "Send test" button sends webhook.test.
Reference in the docs

When a match ends a signed POST reaches your server, with the changed fields and fresh data. · Sample view; names and numbers are fictional.

Ready to try it?

Get a key, paste it into an example and you have data in a minute. The docs list every parameter and include an interactive playground.