# Musixmatch — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for song lyrics, metadata, and translations while discovering artist profiles, discographies, and album details all in one place. Build music apps that let you retrieve complete song information, explore artist catalogs, and discover new music through curated feeds.

**Category:** Music | **Website:** [musixmatch.com/](https://musixmatch.com/) | **Docs:** [parse.bot/marketplace/39dc7344-134b-41c0-bfc0-45b12ef7c5c9/musixmatch-com-api](https://parse.bot/marketplace/39dc7344-134b-41c0-bfc0-45b12ef7c5c9/musixmatch-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/musixmatch/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get album details

Get album metadata and tracklisting. The album_vanity is the slug portion after the artist in the vanity_id from get_artist_discography results. Requires solving a reCAPTCHA on first access.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `album_vanity` | string | Yes | Album vanity ID (slug portion after artist in vanity_id from get_artist_discography, e.g. 'x-Deluxe-Edition'). |
| `artist_vanity` | string | Yes | Artist vanity ID (slug from URL, e.g. 'Ed-Sheeran'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/musixmatch/get-album-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"album_vanity":"<string>","artist_vanity":"<string>"}'
```

### Get artist discography

Get full discography list for an artist. Returns an array of album/single items with title, ID, release type, release date (as Unix timestamp in milliseconds), track count, and vanity ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_vanity` | string | Yes | Artist vanity ID (slug from URL, e.g. 'ed-sheeran'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/musixmatch/get-artist-discography \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"artist_vanity":"<string>"}'
```

### Get artist profile

Get an artist's profile including name, genres, popular songs, and a discography summary with album/single counts. Requires solving a reCAPTCHA on first access to artist pages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_vanity` | string | Yes | Artist vanity ID (slug from URL, e.g. 'ed-sheeran'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/musixmatch/get-artist-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"artist_vanity":"<string>"}'
```

### Get discover feed

Get the Discover page content including community featured cards, top lyric videos, chart artists, and music genres. No parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/musixmatch/get-discover-feed \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get song details

Get detailed metadata for a song including title, artist, album, meaning, moods, themes, and contributing writers. Uses the lyrics page data which includes track info, album info, and credits.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_vanity` | string | Yes | Artist vanity ID (slug from URL, e.g. 'ed-sheeran'). |
| `track_vanity` | string | Yes | Track vanity ID (slug from URL, e.g. 'shape-of-you'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/musixmatch/get-song-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"artist_vanity":"<string>","track_vanity":"<string>"}'
```

### Get song lyrics

Retrieve full lyrics for a specific song in a specified language. Returns the complete lyrics text, language, and verification status. The lyrics page is fetched using the artist and track vanity slugs as they appear in Musixmatch URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_vanity` | string | Yes | Artist vanity ID (slug from URL, e.g. 'ed-sheeran'). |
| `language` | string | No | ISO 639-2 language code for the lyrics language (e.g. 'it', 'es', 'fr', 'en'). |
| `track_vanity` | string | Yes | Track vanity ID (slug from URL, e.g. 'shape-of-you'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/musixmatch/get-song-lyrics \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"artist_vanity":"<string>","language":"<string>","track_vanity":"<string>"}'
```

### Get song translations

Get available translations for a song's lyrics. Returns a mapping of ISO 639-2 language codes to integer completion percentages (0-100).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_vanity` | string | Yes | Artist vanity ID (slug from URL, e.g. 'ed-sheeran'). |
| `track_vanity` | string | Yes | Track vanity ID (slug from URL, e.g. 'shape-of-you'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/musixmatch/get-song-translations \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"artist_vanity":"<string>","track_vanity":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.