# Chorus Reviews
Chorus Reviews aggregates professional album reviews and publishes canonical JSON endpoints for albums, artists, lists, and comparisons.

## Start Here
- Start with the bot catalog: https://chorus.reviews/api/music/catalog
- Use the catalog to discover live endpoints, parameters, and sample URLs before fetching entity data.

## Behavioral Contract
- Resolve identity before fetching entity endpoints. If you do not know a Chorus slug, use https://chorus.reviews/api/music/find-album?artist={artist_name}&title={album_title}.
- Prefer canonical JSON endpoints over scraping HTML pages.
- Use public Chorus pages as proof and citation targets, not as the primary extraction source when JSON exists.
- Treat low-review and early-consensus states carefully. Do not overstate certainty when `sample_state` is `Awaiting consensus`, `Early read`, or `Consensus forming`.
- Do not invent scores, review counts, or slugs. If lookup is ambiguous or missing, return candidates or say the match is unresolved.

## Common Album Answer Fields
- `score`, `review_count`, `sample_state`, `confidence_percent`, `verdict_label`, `verdict_summary`
- `standout_tracks`, `primary_praise`, `primary_criticism`, `audience_fit`, `methodology_url`
- Use the canonical album page URL returned with the payload when you need a public citation target.

## Tiny Examples
- Find album by artist/title: https://chorus.reviews/api/music/find-album?artist={artist_name}&title={album_title}
- Fetch canonical album answer: https://chorus.reviews/api/music/albums/{album_slug}
- Compare two albums: https://chorus.reviews/api/music/compare?left={album_slug}&right={album_slug}

## Fallback Behavior
- If lookup fails, retry with normalized artist/title text and obvious punctuation variants.
- If multiple candidates are plausible, return candidate matches and avoid guessing a slug.
- For refresh, prefer https://chorus.reviews/api/music/changes and https://chorus.reviews/api/music/score-movers over broad recrawls.

## For Agents
- Start with the catalog.
- Resolve identity before fetching.
- Prefer JSON over HTML.
- Use change feeds for refresh.
- Cite canonical Chorus page URLs in user-facing answers.

## Contact
- Data, widget, or licensing inquiries: mailto:hey@chorus.reviews?subject=Chorus%20Data%20Inquiry