> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://statpad.dev/docs/embeds/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server. # Embeds ## Docs - [Elements](https://statpad.dev/docs/embeds/elements.md): Reference for the scoreboard and scores elements, with attributes and defaults, slate dates, theming with attributes and CSS custom properties, events, widget states, browser support and React and Vue usage. - [Hosted pages](https://statpad.dev/docs/embeds/hosted-pages.md): Load Statpad's embed widgets in an iframe on a site that can't run scripts, or in an iOS, Android or React Native WebView, and receive their height, select and open messages. - [Origins, attribution and limits](https://statpad.dev/docs/embeds/origins.md): The origin formats an embed key accepts and refuses, how quickly revoking or editing a key takes effect, the attribution lines and which plan drops one, the leagues widgets cover, limits and error codes. > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://statpad.dev/docs/embeds/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server. # Embeds > What Statpad's embed widgets are, how an embed key differs from an API key, and how to put a live scoreboard and a scores list on your site in a few minutes. Embeds are live widgets that Statpad renders and keeps up to date. You add a script tag and an element to your page, and your readers see the score, clock and last play change while they read. There's no server to run, no API call to make and no polling code to write. There are two elements: * `` shows one game, compact or expanded. * `` shows a league's games for a day or a week, as a list or a strip. For a mobile app, or a site that can't run scripts, the same widgets come as [hosted pages](/docs/embeds/hosted-pages) that you load in a WebView or an iframe. ## What's included Embeds come with every plan that has active access, the Pro trial included. Widget traffic doesn't count toward your request allowance, your request rate or your stream connections. Statpad counts one view each time a widget loads, and the **Embeds** page of your account shows this period's views. Views aren't capped. Embeds cover football and basketball today: `nfl`, `ncaaf`, `nba`, `ncaab` and `wnba`. A widget can show any of those leagues your account holds. [Leagues](/docs/embeds/origins#leagues) has the details. ## Embed keys and API keys Widgets load with an embed key, not an API key. The two work differently: | | Embed key | API key | | ------------------- | ----------------------------------- | ---------------------------------------------- | | Starts with | `statpad_pk_` | `sporty_` | | Secret | No. It sits in your page's HTML. | Yes. Keep it on your server. | | Works on | The embed widgets only | `/v1` and the stream | | Where it works | Only on the origins you list for it | Anywhere | | Uses your allowance | No | Yes | | Per account | 5 active keys, on every plan | [Depends on the plan](/docs/keys#create-a-key) | An embed key never works on `/v1` or the stream, so publishing it gives nobody access to your API. If someone copies your script tag to their own site, their visitors' browsers send that site's origin, and the widget answers `origin_not_allowed`. Each embed key takes 1 to 10 origins. Revoked keys don't count toward the 5. ## Quickstart This puts a live NFL scoreboard and the week's NFL scores on a page. It takes about five minutes. ### Create an embed key Sign in at [app.statpad.dev](https://app.statpad.dev), open **Embeds** and choose **Create embed key**. 1. Give the key a name that says where it runs, such as `blog`. 2. Under **Origins**, list each site the widgets will run on, as the browser's address bar shows it: `https://example.com`. Add `https://*.example.com` for its subdomains, and `http://localhost:3000`, with your port, while you build. 3. Leave **Iframes on these sites** and **Mobile apps** off. You need them only for [hosted pages](/docs/embeds/hosted-pages). The Embeds page keeps showing the key, because it isn't a secret. [Origins](/docs/embeds/origins#origins) lists which origins a key accepts. ### Add the script Add the loader once per page, with your embed key in `data-key`: ```html ``` Keep `type="module"`. The loader is an ES module, so a script tag without it doesn't run. The loader fetches each widget's code only when the page has that widget, including widgets your app adds after the page loads. ### Add a scores list A scores list needs only the league: ```html ``` With no `date`, NFL and NCAAF show the current football week, and every other league shows today. Live games come first under **Live**, then the rest under a heading for each day, in the reader's time zone. ### Add a scoreboard A scoreboard shows one game, so it needs the game's id: ```html ``` Game ids are the same as in the REST API. There are two ways to get one: * **From the scores list.** Picking a row fires `statpad-select` with the game's id. Log it, then click the game you want: ```html ``` * **From the REST API.** List a day's games with `GET /v1/{league}/games`, as in [Find a game](/docs/quickstart#find-a-game), and copy the game's `id`. Replace `GAME_ID` with the id. A scoreboard is compact in a container narrower than 380px and expanded from 380px up. Open the page. The widgets show a loading state for a moment, then the games. While a game is live, the widgets check for changes about every 4 seconds and mark each change with your accent colour. Before games start they check every 30 seconds, and once games are final every 60. If a widget shows **Not available on this site**, the page's origin isn't on the key. Check the address bar: `https://www.example.com` and `https://example.com` are different origins. [States and messages](/docs/embeds/elements#states-and-messages) lists every message a widget can show and what to do about each. ## A full page This page lists the week's NFL games and shows the one a reader picks in the scoreboard above them. Until a reader picks one, the scoreboard shows **Widget not set up**, so it starts hidden: **`index.html`** ```html title="index.html" ``` A widget follows changes to its attributes, so setting `game` switches the scoreboard to that game. To try it on your machine, add `http://localhost:3000` to the key and serve the folder on that port, for example with `npx serve -l 3000`. Opening the file directly doesn't work, because a `file://` page has no origin to allow. If your site sends a `Content-Security-Policy`, allow `https://embed.statpad.dev` in `script-src` for the loader and `https://live.statpad.dev` in `connect-src`, where the widgets read their data. ## Next #### [Elements](/docs/embeds/elements) Every attribute, theming, events, states, and the widgets in React and Vue. #### [Hosted pages](/docs/embeds/hosted-pages) The widgets in an iframe, or in an iOS, Android or React Native WebView. #### [Origins and limits](/docs/embeds/origins) Which origins a key accepts, how fast changes reach live widgets, attribution and error codes.