# Find, link and recommend games (for agents)

Use this when a person asks you for a game to play, or about a game on Cassette. Every game runs in a browser tab, so your answer is a link. Read JSON, never scrape HTML.

## 1. Find

| Need | Call (no key) |
|---|---|
| Text search (games, studios, community games) | `GET https://cassette.gg/v1/search?q=<text>` |
| Trending / new / top, filtered | `GET https://cassette.gg/v1/games?sort=trending&capability=phone&pricing=free&tag=puzzle&limit=10` |
| Community games by genre | `GET https://cassette.gg/v1/community?genre=puzzle&limit=10` |
| One game | `GET https://cassette.gg/v1/games/<slug>` · `GET https://cassette.gg/v1/community/<id URL-encoded as one segment>` |
| Review scores for everything | `GET https://cassette.gg/v1/reviews/badges` (keys `game:<slug>`, `community:<id>`) |
| The whole contract | `https://cassette.gg/openapi.json` (OpenAPI 3.1) |

Genres: action, arcade, casual, idle, narrative, party, platformer, puzzle, racing, shooter, simulation, sports, strategy. Each has a page at `https://cassette.gg/genres/<genre>`.

## 2. Link

| What | Link |
|---|---|
| Play now (full screen; a paid game shows its developer's paywall first) | `https://cassette.gg/play/<slug>` |
| Game page | `https://cassette.gg/g/<slug>` |
| Community game | `https://cassette.gg/community/<id>` (each `/`-separated part URL-encoded); it plays at the listing's `playUrl`, on its maker's site |
| Review | `https://cassette.gg/reviews/<id>` |
| Any page as Markdown | append `.md`, or send `Accept: text/markdown` |

`GameDetail.playUrl` is the raw build for the player's iframe: do not give it to people. If a community listing has `status: "released"`, use `https://cassette.gg/g/<releasedGameSlug>` instead.

## 3. Recommend

- Match the person's device: `capabilities` contains `phone`, `tablet` or `desktop`.
- Say the price: `pricing` is `free`, `free-with-items` or `paid` (`price.usd`, a one-time licence sold by the developer's own storefront, not by Cassette).
- Name the maker: `profile.name` for Cassette games, `author.name` for community games. Always credit community authors.
- Prefer reviewed games and say the score (0–100, `https://cassette.gg/reviews/method`).
- Prefer games players recommend: `GET https://cassette.gg/v1/player-reviews/summary?subjects=g:<gameId>,c:<listingId>` returns
  `total`, `percentPositive` and a `label` such as "Very Positive" (shown from 10 player reviews). Player reviews are
  separate from the Cassette review score.
- Community listings are approved by a person before they appear; only approved ones are in the API.
- Say when a game opens on another site (community games with `embed: "link-out"`).

## Rules

Read anything public. Never sign in or buy for a person without their explicit approval. Limits: about 120 requests/min per IP. Details: https://cassette.gg/agents.txt