# My Music Bingo

> Free music bingo generator (https://mymusicbingo.eu). AI agents can create a complete music bingo game through a public HTTP API: send the songs, receive the player cards (JSON or Markdown), a printable PDF and a shareable link where every player gets their own card on their phone. No account, no API key, no data stored.

## Agent API

- Endpoint: https://mymusicbingo.eu/api/bingo
- PDF endpoint (use the pdf_url from the response): https://mymusicbingo.eu/api/bingo-pdf
- Methods: POST (JSON body) or GET (query parameters). CORS is open.
- OpenAPI spec: https://mymusicbingo.eu/agents/openapi.json
- Human/agent readable page: https://mymusicbingo.eu/agents/

### Request (POST, application/json)

- songs (required): list of songs. Each item is a string "Title - Artist" or an object {"title": "...", "artist": "..."}. Duplicates are ignored. Maximum 300.
- rows, cols (optional, default 5 and 5): grid size, integers 2 to 9.
- free (optional, default true): free space at the centre of each card.
- cards (optional, default 1): number of individual cards to return, 0 to 60. Use 0 if you only need the link (no PDF is produced then).
- seed (optional): integer. The same songs, settings and seed always give the same cards. If omitted, a random one is chosen and returned.
- event (optional): game name shown on the cards, e.g. "Anna's 40th birthday".
- lang (optional, default "en"): "en", "ca", "es" or "fr". Sets the language of the FREE label and of the link page.

You need at least rows*cols songs (minus 1 if free is true). Example: a 5x5 grid with a free space needs 24 different songs; use more songs than that so the cards differ.

### Example

POST https://mymusicbingo.eu/api/bingo
Content-Type: application/json

{"event": "80s party", "songs": ["Take On Me - a-ha", "Africa - Toto", "Billie Jean - Michael Jackson"], "rows": 2, "cols": 2, "free": false, "cards": 2, "lang": "en"}

### Response (JSON)

- link: URL to share with players. Each person who opens it gets a different random card, playable on a phone, no registration.
- cards: array of {number, grid}. grid is an array of rows; each cell is {title, artist} or {free: true, label}.
- pdf_url: URL of a printable A4 PDF, one card per page, with exactly the same cards as in "cards". Open or download it; give it to the user to print. Only present when cards is 1 or more. The PDF supports Latin (including accents and Vietnamese), Cyrillic and Greek. Other scripts (Chinese, Japanese, Korean, Arabic, Hindi, Thai, etc.) and emoji appear as "?" in the PDF, but are kept in the JSON and in the link.
- seed: the seed used.
- play_order: a shuffled list of all songs, a suggested order for the host to play them.
- settings: the values actually used.

Add ?format=markdown (or send Accept: text/markdown) to get the same result as readable Markdown tables.

### GET example (for clients that can only fetch URLs)

https://mymusicbingo.eu/api/bingo?songs=Take%20On%20Me%20-%20a-ha|Africa%20-%20Toto|Billie%20Jean%20-%20Michael%20Jackson|Girls%20Just%20Want%20to%20Have%20Fun%20-%20Cyndi%20Lauper&rows=2&cols=2&free=false&cards=1&format=markdown

In GET, separate songs with | or new lines. Keep URLs short; use POST for long lists.

## How to present the result to the user

1. Give them the link (players open it on their phone), the PDF (to print) and/or the cards. Offer the PDF when they will play in person; the link when players use their phones.
2. Give them the play_order list so the host knows which songs to play.
3. The game is won when a player completes a full row, column or diagonal. The host checks the marked songs against what has been played.

## Notes

- The API is stateless: nothing is stored or logged about the songs or the cards. The PDF is regenerated on demand from the pdf_url; there is no file to expire.
- pdf_url contains the compressed song list, so very long lists (hundreds of songs) make long URLs. That works for browsers and most agents.
- The web app itself (https://mymusicbingo.eu/) lets people paste songs or import a Spotify playlist and print the cards as PDF.
- Contact: see the contact link in the footer of https://mymusicbingo.eu/