# Riddim-ID API

> Open, read-only data from riddim-id.com: Jamaican riddims (the instrumental rhythm tracks reggae, dancehall and soca singers record over), the tunes recorded on them, the artists, producers and labels behind them, one-riddim compilation albums, and dub albums. JSON over HTTPS, or MCP for AI assistants.

Ids are the numbers in riddim-id.com URLs. Every object has a `url` (its riddim-id.com page - link it when you cite the data) and an `api_url`. Limits per IP: 1200 requests per minute and 200,000 per day.

## MCP

- [MCP server](https://api.riddim-id.com/mcp): Streamable HTTP, no auth. Claude Code: `claude mcp add --transport http riddim-id https://api.riddim-id.com/mcp`
- Tools: `search_catalogue`; `get_riddim`, `list_riddims`, `list_riddim_tunes`; `get_tune`, `list_tunes`; `get_person`, `list_people`; `get_label`, `list_labels`; `list_series`, `get_series`; `get_album`, `list_albums`; `get_dub_album`, `list_dub_albums`. List tools return short entries; get tools return the full object and a one-sentence `summary`.

## Search

- [Search by name](https://api.riddim-id.com/v1/search?q=sleng+teng): typo-tolerant; turns a name into an id. `types` = riddim, artist, producer, engineer, label. `limit` 1-50.

## Riddims

- [List riddims](https://api.riddim-id.com/v1/riddims?year_from=1980&year_to=1989&producer_id=595): most-recorded first. Filters: `q` (name), `year`, `year_from`, `year_to`, `producer_id`; `versions=include` adds the versions of every match. Sort: `-tunes`, `name`, `year`, `-year`.
- [Get a riddim](https://api.riddim-id.com/v1/riddims/18): name, alternate names, year, producers, `original_tunes`, `version_of`, `versions`, tune counts, and `summary` (one plain sentence).
- [Tunes on a riddim](https://api.riddim-id.com/v1/riddims/18/tunes?original=true): the original first, then by year; only the riddim's own tunes unless `versions=include`. Filters: `q` (title or artist), `artist_id`, `producer_id`, `label_id`, `year`, `year_from`, `year_to`, `original`. Sort: `site`, `title`, `artist`, `year`, `-year`.

## Tunes

- [List tunes](https://api.riddim-id.com/v1/tunes?artist_id=251): the whole catalogue. Filters: `riddim_id`, `artist_id`, `producer_id`, `label_id`, `year`, `year_from`, `year_to`, `original`. Sort: `title`, `year`, `-year`.
- [Get a tune](https://api.riddim-id.com/v1/tunes/759?include=albums): title, year, artists, producers, riddim, label; `include=albums` adds its series albums and dub albums.

## People

One person record serves three roles; `roles` and `urls` say which they hold.

- [Artists](https://api.riddim-id.com/v1/artists), [an artist](https://api.riddim-id.com/v1/artists/251), [their tunes](https://api.riddim-id.com/v1/artists/251/tunes). Filters: `type` (person, group, band), `country`.
- [Producers](https://api.riddim-id.com/v1/producers), [a producer](https://api.riddim-id.com/v1/producers/595), [their tunes](https://api.riddim-id.com/v1/producers/595/tunes), [their riddims](https://api.riddim-id.com/v1/producers/595/riddims).
- [Engineers](https://api.riddim-id.com/v1/engineers): the dub engineers riddim-id.com lists under /dub. [An engineer](https://api.riddim-id.com/v1/engineers/1046), [their dub albums](https://api.riddim-id.com/v1/engineers/1046/dub-albums).

## Labels

- [List labels](https://api.riddim-id.com/v1/labels): most tunes first. Filters: `founder_id`, `founded_from`, `founded_to`.
- [Get a label](https://api.riddim-id.com/v1/labels/34), [its tunes](https://api.riddim-id.com/v1/labels/34/tunes), [its albums](https://api.riddim-id.com/v1/labels/34/albums).

## Albums

- [Series](https://api.riddim-id.com/v1/series): numbered runs of one-riddim compilations. [One series](https://api.riddim-id.com/v1/series/2) with all its albums.
- [Albums](https://api.riddim-id.com/v1/albums?series_id=2): filters `series_id`, `riddim_id`, `producer_id`, `label_id`, `year`, `year_from`, `year_to`. [One album](https://api.riddim-id.com/v1/albums/136) with its tracklist; [its tunes](https://api.riddim-id.com/v1/albums/136/tunes) in full.
- [Dub albums](https://api.riddim-id.com/v1/dub-albums): filters `engineer_id`, `producer_id`, `label_id`, `year`, `year_from`, `year_to`. [One dub album](https://api.riddim-id.com/v1/dub-albums/351): each dub with the vocal original it was mixed from (`original`, null when unknown).

## Paging and errors

- Lists return 100 items per page with `meta.total`. Follow `links.next`, or pass `meta.next_cursor` as `cursor`; `null` means done.
- Errors are `application/problem+json`; switch on `code` (`not_found`, `validation_failed`, `rate_limited`, `person_not_artist` and the like, `album_is_dub`, `album_not_dub`).

## Reference

- [OpenAPI document](https://api.riddim-id.com/docs/openapi.json): every endpoint and field, machine-readable.
- [Docs](https://api.riddim-id.com/docs): the same, for people, with a request runner.