canonical: https://jentic.com/apis/beamable.com/beamable # Beamable Jentic publishes the only available OpenAPI specification for Beamable, keeping it validated and agent-ready. Beamable is a live game services platform that provides ready-to-use backend systems for player accounts, leaderboards, tournaments, in-game mail, virtual economies, cloud saves, and content management. The API exposes 325 operations across resources like Account, Leaderboard, Tournament, Payment, Group, Mail, Cloudsaving, and Content, letting studios add LiveOps features without standing up custom microservices. Authentication uses Beamable's signed-request scheme with X-DE-SIGNATURE, X-DE-SCOPE, and X-DE-GAMERTAG headers, plus bearer player access tokens for user-context calls. ## For AI agents Manage live game backend operations including player accounts, leaderboards, tournaments, in-game mail, virtual currencies, and cloud saves through Beamable's 325 endpoints. ## Scope Does not handle game client rendering, matchmaking netcode, or anti-cheat enforcement - use for live game backend services like accounts, leaderboards, tournaments, mail, and IAP fulfilment only. ## Capabilities - Create and update player accounts with device tokens, social links, and gamer tag identifiers - Submit scores to leaderboards and fetch ranked player rows around a target gamer tag - Run tournament cycles with stage progression, rewards distribution, and player entries - Send in-game mail with attachments to individual players or broadcast to cohorts - Persist and retrieve player cloud-save data across sessions and devices - Process in-app purchase receipts and grant inventory or virtual currency rewards - Schedule announcements, events, and content overrides without redeploying the game client ## Use cases ### Live leaderboards for competitive games Power weekly and seasonal leaderboards with score submission, ranked queries, and friend-filtered views. Beamable handles persistence, ranking, and reset cycles so studios do not need to operate a sorted-set service. Endpoints under `/basic/leaderboards` cover create, submit, and ranged queries with cursor pagination, and reset jobs run server-side on configured cycles. Example prompt: Submit a score of 12500 for gamer tag 9876543 to the leaderboard board.weekly.competitive and fetch the top 50 ranked players around that tag ### In-game economy and IAP fulfilment Validate Apple App Store and Google Play purchase receipts, grant virtual currency or inventory items, and reconcile transaction history. Beamable's payment endpoints verify receipts against store servers, prevent duplicate fulfilment, and write idempotent transactions to player wallets, removing the need for a custom fulfilment service. Example prompt: Verify an iOS receipt for product sku coin_pack_500 for gamer tag 555111 and grant 500 coins to the player's wallet ### Player mail and announcements Deliver targeted messages, reward attachments, and event announcements to player segments without a client patch. Mail endpoints support per-player and broadcast sends with claimable attachments and read state, while announcements drive in-game banners and pop-ups that can be activated, paused, or scoped to cohorts on demand. Example prompt: Send an in-game mail with subject Welcome Back and an attached 100-coin reward to gamer tag 4422199 ### AI agent integration for LiveOps automation Operations and community managers use AI agents through Jentic to automate routine LiveOps tasks: spinning up tournaments, posting announcements, granting compensation mail after incidents, and pulling leaderboard reports. The agent searches Jentic for the right Beamable operation, loads its schema, and executes with scoped credentials drawn from the vault, so studios automate without exposing the project signature key in agent context. Example prompt: Through Jentic, find the Beamable operation to send broadcast mail with attachments and send a 250-coin compensation message to all players who logged in during the past 24 hours ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/basic/accounts/me` | Get the authenticated player's account profile | | POST | `/object/leaderboards/{objectId}/entry` | Submit a score to a leaderboard | | GET | `/object/leaderboards/{objectId}/ranks` | Fetch ranked rows from a leaderboard | | POST | `/basic/payments/ios/purchase` | Verify an iOS in-app purchase receipt | | POST | `/object/mail/{objectId}/bulk` | Send mail to many recipients | | GET | `/basic/announcements` | List announcements visible to the player | | POST | `/basic/cloudsaving` | Persist a cloud-save manifest entry | ## Key resources - **Account** — Player accounts, device registrations, social links, and gamer tag profiles - **Leaderboard** — Score submission, ranked queries, friend filters, and cycle resets - **Tournament** — Tournament cycles, stages, entries, and reward distribution - **Mail** — In-game mail send, claim attachments, and broadcast messages - **Payment** — App Store and Google Play receipt validation and fulfilment - **Cloudsaving** — Player cloud-save manifests and per-slot blob storage - **Content** — Server-driven content overrides and live configuration - **Group** — Player groups, membership, invites, and roles ## Why Jentic - **Setup:** Wiring Beamable by hand means carrying the project signature key (X-DE-SIGNATURE) and customer.project scope, and choosing between the apiKey and bearer schemes across the account, leaderboard, and mail endpoints yourself. Through Jentic you install once, import Beamable from the API Directory, store the signing key once, and your agent calls it. - **Permission scoping:** Beamable puts the object id in the URL path (`/object/leaderboards/{objectId}/entry` and `/object/mail/{objectId}/bulk`), so a rule can pin your agent to one leaderboard or mail object: it operates on that object and nothing else. You choose the operations it may call, so IAP purchase fulfilment is not included unless you add it. - **Credential handling:** Your Beamable project signature key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'submit a score to a leaderboard' or 'send in-game mail', and Jentic returns the matching Beamable operation with its input schema so the agent calls `/object/leaderboards/{objectId}/entry` or `/object/mail/{objectId}/bulk` without browsing the reference docs. ## Related APIs - **Habitica** — Gamification API for habits and tasks; complements game backends with player engagement primitives outside Beamable's LiveOps scope. - **Discord** — Community and chat platform commonly paired with game backends for player communities and announcements. - **Stripe** — General payments processor; alternative for web-store payments where mobile IAP receipt validation is not the fit. ## FAQ ### Why is there no official OpenAPI spec for Beamable? Beamable does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Beamable via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Beamable API use? Beamable uses a signed-request scheme combining three header credentials: X-DE-SCOPE for the customer.project pair, X-DE-SIGNATURE for the project secret signature, and X-DE-GAMERTAG for the player identifier on user-context calls. Player tokens are passed as bearer tokens in the Authorization header. Jentic's vault stores the project signature key and emits scoped tokens to agents, so the raw secret never enters agent context. ### Can I submit scores and read leaderboards with the Beamable API? Yes. Use POST `/object/leaderboards/{objectId}/entry` to submit a score for a gamer tag, and GET `/object/leaderboards/{objectId}/ranks` to read ranked rows with cursor pagination. The board ID is the leaderboard configured in your Beamable realm. ### How do I send in-game mail with Beamable through Jentic? Search Jentic for send in-game mail to a player to find Beamable's mail operations under `/object/mail/{objectId}/bulk` and `/object/mail/{objectId}`, load the schema, then execute with the gamer tag, subject, body, and any reward attachments. Jentic injects the X-DE-SIGNATURE header at execution time. ### Does the Beamable API validate iOS and Android in-app purchases? Yes. POST `/basic/payments/ios/purchase` verifies an Apple receipt and POST `/basic/payments/google/purchase` verifies a Google Play receipt. Both endpoints fulfil the linked product and write an idempotent transaction record so the same receipt cannot grant rewards twice. ### What are the rate limits for the Beamable API? Beamable does not document a public per-tenant rate limit in the spec. Rate budgets are set per realm in your Beamable plan. If you receive HTTP 429 responses, back off and retry with exponential delay; for production LiveOps automations, contact support@beamable.com to confirm headroom for your scope. ### Can the Beamable API drive cloud saves across devices? Yes. The Cloudsaving resource exposes endpoints to write a manifest and per-slot blobs against a gamer tag, so a player can resume progress on a different device. Manifests are returned with version stamps to support last-writer-wins or client-side merge. ### Can I limit what my agent is allowed to do with the Beamable API? Yes. Because you run Jentic One yourself, your own rules decide which Beamable operations and credentials the agent may use. Since Beamable puts the object id in the URL path, such as `/object/leaderboards/{objectId}/entry` and `/object/mail/{objectId}/bulk`, you can pin the agent to a single leaderboard or mail object so it touches nothing else. You also choose the exact operations it can call, so IAP receipt fulfilment under `/basic/payments/ios/purchase` stays off unless you explicitly allow it.