Developers
Last updated November 14, 2026
Three ways to work with VibePlay from your own tools: connect your coding agent through MCP, pull analytics through the REST API, and let the studio AI use your own MCP servers. Keys are created in the studio: Developer → API & agents.
Keys and permissions
A key looks like vp_live_xxxxxxxx_… and is shown once. Send it as Authorization: Bearer <key>. Give each tool its own key with only what it needs:
| Permission | Allows |
|---|---|
stats:read | Analytics, reviews, errors |
games:read | Read studio projects, run checks |
games:write | Create and update studio projects |
publish | Publish projects to the arcade |
Keys look like vp_live_<8 characters>_<38 characters>; the last six characters are a checksum, so a mistyped key is refused at once. Keys can expire after 30, 90 or 365 days, or never. Revoking a key takes effect immediately in most places and everywhere within 30 seconds. Keep keys out of code repositories and browsers: if one leaks, revoke it and create a new one.
| Limits and headers | |
|---|---|
| Rate limit | 120 requests a minute per key; then 429 with Retry-After. Repeated wrong keys from one address are also slowed down. |
| Caching | Stats answers are cached for 60 seconds per key and query (X-Cache: HIT or MISS). Polling more often than once a minute returns the same numbers. |
| Paging | /stats/visits returns next (CSV: X-Next-Cursor). |
| Timing | Server-Timing shows how long the request took on our side. |
| Errors | JSON {"error": "…"} with 400, 401, 403, 404, 429 or 500. |
Request counts per key for the last 7 days are shown next to each key in the studio.
Your coding agent (MCP)
The MCP server lives at https://api.vibeplay.gg/mcp (Streamable HTTP). Your agent gets tools to read the game rules, save games into your studio, run the five automatic checks in a real browser, publish, and read analytics.
Claude Code
claude mcp add --transport http vibeplay https://api.vibeplay.gg/mcp --header "Authorization: Bearer vp_live_YOUR_KEY"Cursor, Windsurf and other clients (mcp.json)
{ "mcpServers": { "vibeplay": { "url": "https://api.vibeplay.gg/mcp",
"headers": { "Authorization": "Bearer vp_live_YOUR_KEY" } } } }| Tool | What it does |
|---|---|
get_game_rules | The format and rules a game must follow, and the SDK (ads, leaderboard, screen states). Call it first. |
list_projects, get_project | Your studio projects and the full HTML of one. |
save_project | Create or update a project with a complete HTML file. It appears in the studio right away. |
check_project | Loads without errors, draws, responds to taps and keys, runs 6 s of play, survives a screen turn. About 20 seconds. |
publish_project | Publishes; runs the checks first if this version has not passed them. New games are reviewed by a person before they show in listings. |
list_games, get_stats_overview, get_daily_stats, get_traffic_sources, get_retention, get_reviews, get_errors | The analytics below. |
A good first prompt: “Make a VibePlay game where a paper boat dodges rocks. Follow get_game_rules, save it, run check_project and fix what fails, then show me the studio link.”
Analytics API
Base address https://api.vibeplay.gg/v1. JSON by default; add format=csv for spreadsheets. Every stats endpoint takes from and to (YYYY-MM-DD, UTC days; default the last 28 days) and game (a slug; leave out for all your games).
curl -H "Authorization: Bearer vp_live_YOUR_KEY" \
"https://api.vibeplay.gg/v1/stats/overview?from=2026-11-01&to=2026-11-30"| Endpoint | Returns |
|---|---|
GET /games | Your games with lifetime views, plays, players and hours played. |
GET /stats/overview | Reach, plays, players, play time, retention signals, community, errors, and change against the previous period of the same length. |
GET /stats/daily | The same metrics per day; per_game=1 splits each day by game. |
GET /stats/breakdown?by=… | Metrics per value of: surface, source, medium, campaign, content, term, click_type, sub1…sub5, referrer, country, device, game. |
GET /stats/retention | Share of plays still going at 5 s, 10 s, 30 s, 1, 2, 5, 10 and 20 min, and day 1 / 7 / 30 return rates by the day players first played. |
GET /stats/visits | One row per visit: time, game, surface, UTM tags, click ID and its network, sub1–sub5, referrer, country, device, anonymous player, returning, played, seconds, rounds, best score. Up to 5000 per page; pass the returned next as cursor (in CSV it is in the X-Next-Cursor header). |
GET /reviews, GET /errors | Ratings with the latest reviews; script errors grouped by message. |
What the numbers mean
| Metric | Definition |
|---|---|
| views | The game was shown: its page in the arcade, a card in the swipe feed, or your ad link. |
| viewers, players | Unique people who saw it, and who pressed Play. One anonymous ID per browser, or the account when signed in. |
| plays, play_rate | Pressed Play; plays divided by views. |
| play_seconds, avg_play_seconds, play_hours | Time with the game open and in front of the player, counted in 5-second steps. |
| engaged_plays, engaged_rate | Plays that lasted 30 seconds or more. |
| rounds, rounds_finished | Rounds started and finished, reported by the game with VP.state('playing') and VP.state('gameover', {score}). Zero if the game does not report them. |
| returning_players | Players who had played the same game on an earlier day. |
| d1, d7, d30 | Of the players who first played on a day, the share who played again exactly 1, 7 or 30 days later. |
Tagging ad links
Every game has a full-screen link for ads and blogs: https://apps.vibeplay.gg/p/<slug>. Add utm_source, utm_medium, utm_campaign, utm_content, utm_term and up to five sub1…sub5. Click IDs are recognized by themselves: fbclid, gclid, ttclid, yclid, msclkid.
Your MCP servers in the studio
In Developer → API & agents you can add up to five of your own MCP servers (https only, with an optional bearer token). When you build or change a game in the studio, the Claude model can call their tools, for example to read your brand rules, level data or asset list. Tokens are stored encrypted and sent only to that server. Turn a server off to build without it.
Privacy
We never return IP addresses. Player IDs in exports are anonymous and different for every developer, so they cannot be joined across accounts. See the privacy policy and the developer terms.
VibePlay is operated by Cleanor Research Labs L.L.C-FZ, Dubai, United Arab Emirates. Questions: hello@vibeplay.gg.