Documentation Index
Fetch the complete documentation index at: https://rocks.docs.rive.wtf/llms.txt
Use this file to discover all available pages before exploring further.
Every API key is tied to one IP. To apply for a key, DM southctrl on Discord.
Use the endpoint paths below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.
Quick Start
Find a category ID
Use /api/medal/categories to get a full list of games and their category IDs.
Call a clip route
Send a request to /api/medal/trending, /api/medal/latest, or /api/medal/search.
Use the clip data
Read the title, views, likes, thumbnail, and embed code from the response.
Good for gaming dashboards, clip feeds, Discord bots, and tournament highlight reels.
Trending Clips
Get the top trending clips, optionally filtered by game.
Endpoint
Query Parameters
Filter by game category ID. Leave blank for trending across all games.
Number of clips to return. Max 1000.
Number of clips to skip. limit + offset cannot exceed 1000.
Example Request
curl -X GET "https://rocks.rive.wtf/api/medal/trending?categoryId=62&limit=1" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/medal/trending?categoryId=62&limit=1', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'categoryId': 62, 'limit': 1}
response = requests.get(
'https://rocks.rive.wtf/api/medal/trending',
headers=headers,
params=params
)
print(response.json())
Example Response
{
"contentObjects": [
{
"contentId": "cidmrFZ4vTNgDZCGiV7l",
"contentTitle": "Woah",
"contentViews": 14873,
"contentLikes": 95,
"contentThumbnail": "https://cdn.medal.tv/...",
"categoryId": "10cJzcPADb",
"videoLengthSeconds": 7.4,
"createdTimestamp": 1775348224801,
"directClipUrl": "https://medal.tv/clip/mrFZ4vTNgDZCGiV7l/...",
"embedIframeCode": "<iframe width='640' height='360' src='https://medal.tv/clip/...'></iframe>",
"credits": "Credits to apeks (https://medal.tv/users/208597837)"
}
]
}
Latest Clips
Get the most recent clips from a specific user or game.
Endpoint
Query Parameters
Filter by user ID. Find a user ID at medal.tv/users/{userId}.
Filter by game category ID.
Number of clips to return. Max 1000.
Number of clips to skip. limit + offset cannot exceed 1000.
Example Request
curl -X GET "https://rocks.rive.wtf/api/medal/latest?userId=12597&categoryId=10&limit=2" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/medal/latest?userId=12597&categoryId=10&limit=2', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'userId': 12597, 'categoryId': 10, 'limit': 2}
response = requests.get(
'https://rocks.rive.wtf/api/medal/latest',
headers=headers,
params=params
)
print(response.json())
Example Response
{
"contentObjects": [
{
"contentId": "cid5042841",
"contentTitle": "that winning team name...",
"contentViews": 47,
"contentLikes": 1,
"categoryId": "10",
"videoLengthSeconds": 15,
"createdTimestamp": 1563692235000,
"directClipUrl": "https://medal.tv/clip/5042841/...",
"embedIframeCode": "<iframe width='640' height='360' src='https://medal.tv/clip/...'></iframe>",
"credits": "Credits to Galkon (https://medal.tv/users/12597)"
}
]
}
Search Clips
Search for clips by keyword or hashtag.
Endpoint
Query Parameters
Search query. Supports hashtags and spaces. URI-encode special characters (%20 for spaces, %23 for #).
Number of clips to return. Max 1000.
Number of clips to skip. limit + offset cannot exceed 1000.
Example Request
curl -X GET "https://rocks.rive.wtf/api/medal/search?text=%23flamingo&limit=1" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/medal/search?text=%23flamingo&limit=1', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'text': '#flamingo', 'limit': 1}
response = requests.get(
'https://rocks.rive.wtf/api/medal/search',
headers=headers,
params=params
)
print(response.json())
Example Response
{
"contentObjects": [
{
"contentId": "cid4706138",
"contentTitle": "#Flamingo what the",
"contentViews": 367,
"contentLikes": 6,
"categoryId": "76",
"videoLengthSeconds": 15,
"createdTimestamp": 1561834937000,
"directClipUrl": "https://medal.tv/clip/5223338/...",
"embedIframeCode": "<iframe width='640' height='360' src='https://medal.tv/clip/...'></iframe>",
"credits": "Credits to laikrai (https://medal.tv/users/1908292)"
}
]
}
Categories
Get a full list of all games and their category IDs on Medal.
Endpoint
GET /api/medal/categories
Example Request
curl -X GET "https://rocks.rive.wtf/api/medal/categories" \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://rocks.rive.wtf/api/medal/categories', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
console.log(data);
import requests
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
response = requests.get(
'https://rocks.rive.wtf/api/medal/categories',
headers=headers
)
print(response.json())
Response Fields
| Field | Type | Description |
|---|
contentId | string | Unique clip ID |
contentTitle | string | Title of the clip |
contentViews | integer | Total view count |
contentLikes | integer | Total like count |
contentThumbnail | string | URL of the clip thumbnail |
categoryId | string | Game category ID |
videoLengthSeconds | float | Duration of the clip in seconds |
createdTimestamp | integer | Unix timestamp (ms) of when the clip was created |
directClipUrl | string | Direct link to the clip on Medal.tv |
embedIframeCode | string | Ready-to-use HTML iframe embed code |
credits | string | Attribution string linking to the clip creator |
rawFileUrl | string | Raw video file URL (not_authorized without special access) |
rawFileUrl, rawFileUrlLowRes, and unbrandedFileUrl return not_authorized by default. Special API access is required to unlock raw file URLs.
