revlist API

Overview

The revlist API is a JSON API served from https://revlist.lol/api/v1. Public reads need no authentication. Voting, claiming prizes and managing a revival use an API key created from your API keys page.

Base URL

https://revlist.lol/api/v1

Authentication

Create a key on API keys. It looks like rvl_... and is shown exactly once. Send it as a bearer token:

Authorization: Bearer rvl_your_key_here
# or
X-API-Key: rvl_your_key_here

Scopes: read, vote, claim, and owner. A key may be pinned to a single revival; if it is, owner endpoints for any other revival return 403. Browser sessions are also accepted by every endpoint (with CSRF origin checks on writes).

Response envelope

{
  "data": { ... },
  "meta": { "page": 1, "pages": 3, "total": 44 }
}

Errors always use the same shape. Messages are written for humans: they say what went wrong and, when we can, what to do next. hint is optional but usually tells you the next step, and validation errors also list every bad field.

{
  "error": {
    "code": "validation_error",
    "message": "The headline needs at least 3 characters.",
    "hint": "Fix the fields listed in details.fields, then send the request again. Nothing was saved.",
    "details": {
      "fields": { "headline": "The headline needs at least 3 characters." }
    }
  }
}

Validation errors are 422. Permission problems are 403, missing things are 404, and rate limits are 429.

Rate limits

• Voting: 20 requests per minute per account and IP.
• Prize claims: 30 per minute per account.
• API key creation: 10 per hour per account.
• Ad orders: 5 per hour per account.

A limited response is 429 with a Retry-After header. Daily voting itself is one vote per revival per UTC day; retrying does not add votes.

Public endpoints

Voting

curl -X POST https://revlist.lol/api/v1/revivals/classic-2016/vote \
  -H "Authorization: Bearer rvl_your_key"

{
  "data": {
    "counted": true,
    "votes_total": 1731,
    "next_vote_at": "2026-10-23T00:00:00.000Z"
  }
}

Prizes and claims

A revival owner publishes prizes with one of three requirements: vote (any voter), top_voter (current first place), or manual (the team chooses winners; members cannot claim it themselves). A member claim is created with their Roblox username and starts as pending.

Owners then mark a claim fulfilled after delivering the currency or item. The delivery_ref is any identifier the revival wants to keep (transaction id, asset id, ticket number).

Owner endpoints

All owner endpoints require the owner scope and ?slug=your-revival. They work for the revival's owner and for site admins.

{
  "title": "Voter stipend",
  "description": "250 Tix for every voter, once.",
  "kind": "tix",
  "amount": 250,
  "requirement": "vote",
  "stock": 5000
}

End-to-end prize flow

# 1. A member votes, then claims 250 Tix from the revival page.
# 2. Your backend polls pending claims:
curl "https://revlist.lol/api/v1/owner/claims?slug=classic-2016&status=pending" \
  -H "Authorization: Bearer rvl_owner_key"

# 3. Grant the Tix in-game/on your site, then close the claim:
curl -X POST "https://revlist.lol/api/v1/owner/claims/42/fulfill?slug=classic-2016" \
  -H "Authorization: Bearer rvl_owner_key" \
  -H "Content-Type: application/json" \
  -d '{"deliveryRef":"tix-grant-9001"}'

# 4. The member sees "fulfilled" and the delivery reference on /prizes.

JavaScript example

const API = "https://revlist.lol/api/v1";
const headers = { Authorization: `Bearer ${process.env.REVLIST_KEY}` };

const claims = await fetch(`${API}/owner/claims?slug=classic-2016&status=pending`, {
  headers,
}).then((response) => response.json());

for (const claim of claims.data) {
  await deliverPrize(claim.roblox_username, claim.reward.title);
  await fetch(`${API}/owner/claims/${claim.id}/fulfill?slug=classic-2016`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ deliveryRef: `job-${claim.id}` }),
  });
}

Account endpoints

Ads

Ad placements are sold from the Advertise tab of your dashboard. Orders are paid once, approved by staff, and then rotate in their slot. Impressions and clicks are counted server-side; GET /api/v1/ads is the public read endpoint.

Every slot also has a capacity. The left and right rails show up to three rotating creatives at once; the sitewide banner and in-feed promo hold one and three respectively. Three plans are available:

• Standard - normal rotation, the slot price.
• Featured - picked twice as often in the rotation, 175% of the slot price.
• Takeover - fills the whole slot by itself, 250% of the slot price. Other creatives in that slot wait until the takeover ends.

Plans live in the ad_plans table and can be changed without a code deploy. The public response includes the plan so clients can label a takeover.

Verify a revival

Verified owners have proved they control the website listed on the revival. The badge is public on the revival page. Start with POST, publish the DNS record or text file, then PUT to check it.

Members and social

Every member has a profile page at /u/username. Follows are one-way; friendships need both people. Profiles are public, but only signed-in members can follow or add friends.

Terms

Be reasonable: no vote bots, no scraping at abusive rates, and no reselling API access. Prizes are the responsibility of the revival that publishes them. revlist records claims and provides the settlement API; it does not mint Robux or Tix. Breaking these rules can get a key revoked and a listing removed.