Roblox API - rocks.rive.wtf API

Every API key is tied to one IP. To apply for a key, DM southctrl on Discord.

Use the endpoint path below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.

Most Used Endpoints

Player Info

Get the main Roblox profile summary

Avatar

Get a player’s avatar thumbnail

Groups

Fetch groups the player is in

Friends

Get a player’s friend list

Most apps only need player info plus one extra route like avatar, groups, or friends. Start there before using the larger data endpoints.

Get Player Info

Get a full profile summary for a Roblox player by username.

Endpoint

GET /api/roblox/{username}

Path Parameters

username

string

required

Roblox username.

Query Parameters

limit

integer

default:"1000"

Max collectible items to scan when calculating RAP and item count.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": 156,
  "name": "builderman",
  "displayName": "builderman",
  "description": "",
  "created": "2006-03-08T17:17:52.9Z",
  "hasVerifiedBadge": true,
  "avatar": "https://tr.rbxcdn.com/30DAY-Avatar-882C70E071E5997E51F8CB373002AFC3-Png/720/720/Avatar/Png/noFilter",
  "presence": "Offline",
  "friends": 0,
  "followers": 71244353,
  "following": 67857070,
  "items": 47,
  "rap": 15007649,
  "value": 20505647
}

Response Fields

number

Unique Roblox user ID

name

string

Roblox username

displayName

string

Display name shown on profile

description

string

Bio shown on profile. Empty string if not set.

created

string

Account creation date (ISO 8601 format)

hasVerifiedBadge

boolean

Whether the account has a verified badge

avatar

string

CDN URL for the player’s avatar thumbnail (720x720)

presence

string

Current online status — "Online", "Offline", "In Game", or "In Studio"

friends

number

Number of friends

followers

number

Number of followers

following

number

Number of accounts the player is following

items

number

Total number of collectible items owned. Omitted if zero.

rap

number

Recent Average Price (RAP) across the player’s collectibles. Falls back to Rolimons RAP when the inventory scrape returns zero. Omitted if zero.

value

number

Total estimated inventory value sourced from Rolimons. Omitted if zero.

Get Avatar Thumbnail

Fetch the avatar thumbnail URL for a player by their numeric user ID.

Endpoint

GET /api/roblox/avatar/{userId}

Path Parameters

userId

integer

required

Numeric Roblox user ID.

Query Parameters

size

string

default:"720x720"

Thumbnail dimensions. Common values: 48x48, 150x150, 420x420, 720x720.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/avatar/156?size=420x420" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "imageUrl": "https://tr.rbxcdn.com/30DAY-Avatar-882C70E071E5997E51F8CB373002AFC3-Png/420/420/Avatar/Png/noFilter"
}

Response Fields

imageUrl

string

CDN URL for the avatar thumbnail at the requested size

This endpoint takes a numeric user ID, not a username. Use /api/roblox/{username} first to resolve a username to its ID.

Get Asset Template

Fetch the raw image for a Roblox asset — shirt/pants templates, decals, and similar catalog items. Returns the image bytes directly with the appropriate Content-Type header (image/png, image/jpeg, etc.).

Endpoint

GET /api/roblox/template/{assetId}

Path Parameters

assetId

integer

required

Numeric Roblox asset ID. Works for shirts, pants, decals, and other catalog items that have an underlying texture.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/template/6055891536" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output template.png

Response

This endpoint returns raw image bytes, not JSON. The Content-Type header will be image/png or image/jpeg depending on the asset.

Status	Meaning
`200`	Image bytes returned successfully
`400`	`assetId` is not a valid integer
`404`	No template image could be resolved for this asset

The endpoint tries multiple resolution strategies in order: assetdelivery v2 CDN redirect → assetdelivery v1 direct → XML/RBXM texture ID extraction → economy API → catalog thumbnails. If all fail, a 404 is returned.

Do not call response.json() on this endpoint — the body is raw image data, not JSON. Write response.content directly to a file or pass it to an image library.

Get Avatar Details

Get full avatar details for a player including worn assets, body colors, scales, and avatar type.

Endpoint

GET /api/roblox/{username}/avatar

Path Parameters

username

string

required

Roblox username.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman/avatar" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "playerAvatarType": "R15",
  "scales": {
    "height": 1.0,
    "width": 1.0,
    "head": 1.0,
    "depth": 1.0,
    "proportion": 0.0,
    "bodyType": 0.0
  },
  "bodyColors": {
    "headColorId": 125,
    "torsoColorId": 125,
    "rightArmColorId": 125,
    "leftArmColorId": 125,
    "rightLegColorId": 125,
    "leftLegColorId": 125
  },
  "assets": [
    {
      "id": 11844853,
      "name": "Turbo Builders Club Hard Hat",
      "currentVersionId": 883360292,
      "assetType": {
        "id": 8,
        "name": "Hat"
      }
    }
  ],
  "defaultShirtApplied": false,
  "defaultPantsApplied": false,
  "emotes": []
}

Response Fields

playerAvatarType

string

Avatar rig type — "R6" or "R15"

scales

object

Body scale sliders (height, width, head, depth, proportion, bodyType) — all floats between 0 and 1

bodyColors

object

Roblox color IDs for each body part (head, torso, rightArm, leftArm, rightLeg, leftLeg)

assets

array

Currently worn asset objects, each with id, name, currentVersionId, and assetType (id + name)

defaultShirtApplied

boolean

Whether the default Roblox shirt is applied

defaultPantsApplied

boolean

Whether the default Roblox pants are applied

emotes

array

Equipped emotes

Get Player Outfits

Get a player’s saved outfits (up to 100).

Endpoint

GET /api/roblox/{username}/outfits

Path Parameters

username

string

required

Roblox username.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman/outfits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "outfits": [
    {
      "id": 555869704325162,
      "name": "adidas Ice Angels",
      "isEditable": false,
      "outfitType": null
    },
    {
      "id": 24477562,
      "name": "builderman1",
      "isEditable": true,
      "outfitType": null
    }
  ]
}

Response Fields

outfits

array

Array of outfit objects

Show Outfit object fields

number

Unique outfit ID

name

string

Outfit name

isEditable

boolean

Whether the outfit can be edited by the owner

outfitType

string | null

Outfit type if applicable, otherwise null

Get Player Groups

Get all groups a player belongs to, along with their role and group metadata.

Endpoint

GET /api/roblox/{username}/groups

Path Parameters

username

string

required

Roblox username.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman/groups" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "groups": [
    {
      "id": 9,
      "name": "Turbo Builders Club",
      "description": null,
      "memberCount": 510675,
      "hasVerifiedBadge": false,
      "role": "Owner",
      "rank": 255
    },
    {
      "id": 3829,
      "name": "Staff",
      "description": null,
      "memberCount": 281839,
      "hasVerifiedBadge": false,
      "role": "ROBLOX Staff",
      "rank": 250
    }
  ]
}

Response Fields

groups

array

Array of group membership objects

Show Group object fields

number

Unique group ID

name

string

Group name

description

string | null

Group description

memberCount

number

Total number of members in the group

hasVerifiedBadge

boolean

Whether the group has a verified badge

role

string

Player’s role name within the group (e.g. "Owner", "Admin", "Member")

rank

number

Numeric rank value (1–255). 255 is typically Owner.

Get Player Badges

Get the first 25 badges earned by a player, sorted oldest first, with full statistics.

Endpoint

GET /api/roblox/{username}/badges

Path Parameters

username

string

required

Roblox username.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman/badges" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "badges": [
    {
      "id": 14468729,
      "name": "5 Kills at Sword Fight on the Heights",
      "description": "Score 5 kills at Sword Fight on the Heights to win this badge.",
      "displayIconImageUrl": null,
      "enabled": true,
      "statistics": {
        "pastDayAwardedCount": 541,
        "awardedCount": 2293402,
        "winRatePercentage": 0.211
      },
      "awardingUniverse": {
        "id": null,
        "name": null,
        "rootPlaceId": null
      }
    }
  ]
}

Response Fields

badges

array

Array of badge objects (up to 25, sorted ascending by award date)

Show Badge object fields

number

Unique badge ID

name

string

Badge name

description

string

Badge description

displayIconImageUrl

string | null

URL to the badge icon image. May be null for older badges.

enabled

boolean

Whether the badge is currently active and obtainable

statistics

object

Award statistics — pastDayAwardedCount, awardedCount, and winRatePercentage

awardingUniverse

object

Game that awards this badge — id, name, and rootPlaceId. Fields may be null for legacy badges.

Get Player Friends

Get a player’s full friends list with display names and verified badge status.

Endpoint

GET /api/roblox/{username}/friends

Path Parameters

username

string

required

Roblox username.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman/friends" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "count": 2,
  "friends": [
    {
      "id": 1,
      "name": "Roblox",
      "displayName": "Roblox",
      "hasVerifiedBadge": true
    },
    {
      "id": 261,
      "name": "Telamon",
      "displayName": "Telamon",
      "hasVerifiedBadge": false
    }
  ]
}

Response Fields

count

number

Total number of friends returned

friends

array

Array of friend objects

Show Friend object fields

number

Roblox user ID

name

string

Roblox username

displayName

string

Display name

hasVerifiedBadge

boolean

Whether the friend has a verified badge

Get Player Games

Get games created by a player (up to 50, sorted by most recent).

Endpoint

GET /api/roblox/{username}/games

Path Parameters

username

string

required

Roblox username.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman/games" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "count": 1,
  "games": [
    {
      "id": 920587237,
      "name": "Classic: Crossroads",
      "description": "classic Roblox map.",
      "rootPlaceId": 1818,
      "created": "2020-05-13T19:47:55.223Z",
      "updated": "2024-01-10T12:00:00Z",
      "isPublic": true,
      "maxPlayers": 30,
      "genre": "All",
      "stats": {
        "totalVisits": 4200000,
        "playing": 312,
        "favoritedCount": 87000
      }
    }
  ]
}

Response Fields

count

number

Total number of games returned

games

array

Array of game objects

Show Game object fields

number

Universe ID

name

string

Game name

description

string | null

Game description

rootPlaceId

number

Root place ID (used to build the game URL)

created

string

Creation date (ISO 8601)

updated

string

Last updated date (ISO 8601)

isPublic

boolean

Whether the game is publicly accessible

maxPlayers

number

Maximum concurrent players per server

genre

string

Game genre

stats

object

Play stats — totalVisits, playing (current players), and favoritedCount

Get Rolimons Data

Fetch raw Rolimons player-asset data for a player, including full inventory asset map, value, RAP, and account flags.

Endpoint

GET /api/roblox/{username}/rolimons

Path Parameters

username

string

required

Roblox username.

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/builderman/rolimons" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "playerId": 156,
  "isOnline": false,
  "lastLocation": "Website",
  "lastOnline": null,
  "premium": true,
  "playerVerified": false,
  "playerTerminated": false,
  "playerPrivacyEnabled": false,
  "playerAssets": {
    "11844853": [542539481],
    "1193534": [314736]
  }
}

Response Fields

success

boolean

Whether Rolimons returned a valid result for this player

playerId

number

Roblox user ID as indexed by Rolimons

isOnline

boolean

Whether the player is currently online according to Rolimons

lastLocation

string | null

Last seen location (e.g. "Website", "Playing [game name]")

lastOnline

string | null

Timestamp of last online activity. May be null.

premium

boolean

Whether the player has Roblox Premium

playerVerified

boolean

Whether the player is verified on Rolimons

playerTerminated

boolean

Whether the account has been terminated

playerPrivacyEnabled

boolean

Whether the player has privacy mode enabled on Rolimons

playerAssets

object

Map of assetId → [serialNumber, ...]. Keys are asset IDs as strings; values are arrays of serial numbers owned.

Rolimons data is only available for players with public inventories who have been indexed by Rolimons. Returns 500 if the upstream request fails.

Get Username History

Get a list of previous usernames for a player.

Endpoint

GET /api/roblox/{username}/username/history

Path Parameters

username

string

required

Roblox username.

Query Parameters

limit

integer

default:"10"

Max previous usernames (max 100).

sortOrder

string

default:"Asc"

Sort order — "Asc" (oldest first) or "Desc" (newest first).

Example Request

curl -X GET "https://rocks.rive.wtf/api/roblox/r88ot/username/history?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "userId": 567346857,
  "username": "r88ot",
  "history": ["ANTIAT666", "offbra_nd"],
  "count": 2
}

Response Fields

userId

number

Roblox user ID

username

string

Current Roblox username

history

array

Ordered list of previous usernames. Empty array if the player has never changed their username.

count

number

Total number of previous usernames returned

Pass the player’s current username — the API resolves it to a user ID internally. Username history is sourced via roproxy for reliability.

Render Avatar to PNG

Render a player’s avatar locally using Pillow and aggdraw — no Cairo required.

Install dependencies

pip install pillow aggdraw requests

Example

"""
Fetch a Roblox avatar via /api/roblox/avatar/{userId} and render it as a PNG.
Optionally overlays the verified-badge SVG path using aggdraw.Path.
"""
import re
import requests
from PIL import Image
from io import BytesIO
import aggdraw

API_KEY = "YOUR_API_KEY"
USER_ID = 156
SIZE    = 400
OUTPUT  = "avatar.png"

VERIFIED_PATH = (
    "M19.998 3.094 14.638 0l-2.972 5.15H5.432v6.354L0 14.64 3.094 20 0 25.359"
    "l5.432 3.137v5.905h5.975L14.638 40l5.36-3.094L25.358 40l3.232-5.6h6.162"
    "v-6.01L40 25.359 36.905 20 40 14.641l-5.248-3.03v-6.46h-6.419L25.358 0"
    "l-5.36 3.094Zm7.415 11.225 2.254 2.287-11.43 11.5-6.835-6.93 2.244-2.258"
    "4.587 4.581 9.18-9.18Z"
)


def parse_svg_path(d):
    tokens = re.findall(
        r'[MmZzLlHhVvCcSsQqTtAa]|[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?', d
    )
    commands, cmd, args = [], None, []
    for t in tokens:
        if t.isalpha():
            if cmd:
                commands.append((cmd, args))
            cmd, args = t, []
        else:
            args.append(float(t))
    if cmd:
        commands.append((cmd, args))
    return commands


def build_aggdraw_path(d, scale):
    path = aggdraw.Path()
    cx = cy = sx = sy = 0.0

    def s(v):
        return v * scale

    for cmd, args in parse_svg_path(d):
        if cmd == 'M':
            pairs = list(zip(args[0::2], args[1::2]))
            cx, cy = pairs[0]
            path.moveto(s(cx), s(cy))
            sx, sy = cx, cy
            for x, y in pairs[1:]:
                cx, cy = x, y
                path.lineto(s(cx), s(cy))
        elif cmd == 'm':
            pairs = list(zip(args[0::2], args[1::2]))
            cx += pairs[0][0]; cy += pairs[0][1]
            path.moveto(s(cx), s(cy))
            sx, sy = cx, cy
            for dx, dy in pairs[1:]:
                cx += dx; cy += dy
                path.lineto(s(cx), s(cy))
        elif cmd == 'L':
            for x, y in zip(args[0::2], args[1::2]):
                cx, cy = x, y
                path.lineto(s(cx), s(cy))
        elif cmd == 'l':
            for dx, dy in zip(args[0::2], args[1::2]):
                cx += dx; cy += dy
                path.lineto(s(cx), s(cy))
        elif cmd == 'H':
            for x in args:
                cx = x
                path.lineto(s(cx), s(cy))
        elif cmd == 'h':
            for dx in args:
                cx += dx
                path.lineto(s(cx), s(cy))
        elif cmd == 'V':
            for y in args:
                cy = y
                path.lineto(s(cx), s(cy))
        elif cmd == 'v':
            for dy in args:
                cy += dy
                path.lineto(s(cx), s(cy))
        elif cmd == 'C':
            it = iter(args)
            for x1, y1, x2, y2, x, y in zip(it, it, it, it, it, it):
                path.curveto(s(x1), s(y1), s(x2), s(y2), s(x), s(y))
                cx, cy = x, y
        elif cmd == 'c':
            it = iter(args)
            for dx1, dy1, dx2, dy2, dx, dy in zip(it, it, it, it, it, it):
                path.curveto(
                    s(cx + dx1), s(cy + dy1),
                    s(cx + dx2), s(cy + dy2),
                    s(cx + dx),  s(cy + dy),
                )
                cx += dx; cy += dy
        elif cmd in ('Z', 'z'):
            path.close()
            cx, cy = sx, sy

    return path


def fetch_avatar_url(user_id, size="720x720"):
    resp = requests.get(
        f"https://rocks.rive.wtf/api/roblox/avatar/{user_id}",
        params={"size": size},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()["imageUrl"]


def download_image(url):
    resp = requests.get(url, timeout=15)
    resp.raise_for_status()
    return Image.open(BytesIO(resp.content)).convert("RGBA").resize((SIZE, SIZE))


def overlay_verified_badge(img, badge_size=60, margin=8):
    scale = badge_size / 40
    badge = Image.new("RGBA", (badge_size, badge_size), (0, 0, 0, 0))
    draw  = aggdraw.Draw(badge)
    brush = aggdraw.Brush("#0095F6", opacity=255)
    path  = build_aggdraw_path(VERIFIED_PATH, scale)
    draw.path(path, brush)
    draw.flush()
    x = SIZE - badge_size - margin
    y = SIZE - badge_size - margin
    img.paste(badge, (x, y), badge)
    return img


image_url = fetch_avatar_url(USER_ID)
img = download_image(image_url)
img = overlay_verified_badge(img)
img.save(OUTPUT)
print(f"Saved {OUTPUT} ({SIZE}x{SIZE}px)")

SVG → aggdraw command map

SVG command	aggdraw method
`M` / `m`	`path.moveto()`
`L` / `l`	`path.lineto()`
`H` / `h` / `V` / `v`	`path.lineto()` (one axis fixed)
`C` / `c`	`path.curveto()`
`Z` / `z`	`path.close()`

aggdraw.Path(string) does not parse SVG path strings. Always construct an empty aggdraw.Path() and build it with method calls as shown above.

Use Cases

Profile Lookup

Display player statistics, bio, and online status

Trading Tools

Track item values and RAP via Rolimons

Outfit Browser

Browse and display player outfits

Asset Templates

Fetch raw shirt, pants, and decal textures by asset ID

Group Directory

List a player’s group memberships, roles, and member counts

Badge Showcase

Display earned badges with statistics and win rates

Game Portfolio

Browse games created by a player with visit and player counts

Friends List

Display a player’s friends with verified badge indicators

Username History

Look up all previous usernames for any Roblox account

Additional Notes

Account age calculation

created field is in ISO 8601 format:

const created = new Date(data.created);
const ageInDays = Math.floor((Date.now() - created) / (1000 * 60 * 60 * 24));
const ageInYears = (ageInDays / 365).toFixed(1);

Value vs RAP

RAP (Recent Average Price): Rolling average of recent sales for each collectible the player owns. Profile endpoint falls back to Rolimons RAP when the direct inventory scrape returns zero.
Value: Projected total worth of the inventory sourced from Rolimons.

Presence status

Value	Meaning
`"Online"`	Currently online on Roblox
`"Offline"`	Not online
`"In Game"`	Actively playing a game
`"In Studio"`	Using Roblox Studio

Profile visibility

Player profiles must be public for inventory, group, badge, friends, games, and Rolimons data to be available. Private profiles will return limited data or errors.

Game URL construction

Use rootPlaceId from the games endpoint to build a direct link:

const gameUrl = `https://www.roblox.com/games/${game.rootPlaceId}`;

Template vs thumbnail

The /template/{assetId} endpoint returns the raw texture file — the actual shirt/pants template PNG that developers use for designing clothing. This is different from the catalog thumbnail, which is a rendered preview image. Use the template endpoint when you need the source texture for image editing or display.

Getting Started

Social Media

Developer

Gaming

Sports

Entertainment

Profiles & Lookup

Crypto & Finance

Utilities

Documentation Index

​Most Used Endpoints

Player Info

Avatar

Groups

Friends

​Get Player Info

​Endpoint

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Get Avatar Thumbnail

​Endpoint

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Get Asset Template

​Endpoint

​Path Parameters

​Example Request

​Response

​Get Avatar Details

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Get Player Outfits

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Get Player Groups

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Get Player Badges

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Get Player Friends

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Get Player Games

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Get Rolimons Data

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Get Username History

​Endpoint

​Path Parameters

​Query Parameters

Most Used Endpoints

Get Player Info

Endpoint

Path Parameters

Query Parameters

Example Request

Example Response

Response Fields

Get Avatar Thumbnail

Endpoint

Path Parameters

Query Parameters

Example Request

Example Response

Response Fields

Get Asset Template

Endpoint

Path Parameters

Example Request

Response

Get Avatar Details

Endpoint

Path Parameters

Example Request

Example Response

Response Fields

Get Player Outfits

Endpoint

Path Parameters

Example Request

Example Response

Response Fields

Get Player Groups

Endpoint

Path Parameters

Example Request

Example Response

Response Fields

Get Player Badges

Endpoint

Path Parameters

Example Request

Example Response

Response Fields

Get Player Friends

Endpoint

Path Parameters

Example Request

Example Response

Response Fields

Get Player Games

Endpoint

Path Parameters

Example Request

Example Response

Response Fields

Get Rolimons Data

Endpoint

Path Parameters

Example Request

Example Response

Response Fields

Get Username History

Endpoint

Path Parameters

Query Parameters

Example Request

Example Response

Response Fields

Render Avatar to PNG

Install dependencies

Example

SVG → aggdraw command map

Use Cases

Additional Notes

Account age calculation

Value vs RAP

Presence status

Profile visibility

Game URL construction