# Darklyrics — 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 and album lyrics from metal music bands, browse newly added albums and complete band discographies, and access full lyrics organized by artist and release. Filter bands alphabetically and find specific songs to read their complete lyrical content.

**Category:** Music | **Website:** [darklyrics.com/](https://darklyrics.com/) | **Docs:** [parse.bot/marketplace/41263262-9cb7-4e58-b2e3-1cfb8e86dbbb/darklyrics-com-api](https://parse.bot/marketplace/41263262-9cb7-4e58-b2e3-1cfb8e86dbbb/darklyrics-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/darklyrics/`
**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 lyrics

Get the complete lyrics for all songs on an album. Returns album name, year, and an array of songs each with track number, title, and full lyrics text.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `album_slug` | string | Yes | Album URL slug (e.g. 'killemall', 'masterofpuppets'). |
| `band_slug` | string | Yes | Band URL slug (e.g. 'metallica'). |

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

### Get band page

Get a band's discography including albums, demos, and EPs with their tracklists. Each album entry contains its title, year, type, and list of songs with track numbers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_slug` | string | Yes | Band URL slug (e.g. 'metallica', 'ironmaiden'). |
| `letter` | string | Yes | First letter of the band name (a-z) or # for bands starting with numbers. |

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

### Get bands by letter

Get the list of all bands whose name starts with a given letter. Returns band names, URLs, and URL slugs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `letter` | string | Yes | Single letter to filter by (a-z) or # for bands starting with numbers. |

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

### Get homepage

Get newly added albums from the DarkLyrics homepage. Returns a list of recently added albums with band name, album title, and thumbnail image URL.

**Estimated cost:** Metered

_No parameters required._

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

### Get song lyrics

Get lyrics for a specific song on an album by its track number. Returns song title, lyrics text, album metadata, and identifiers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `album_slug` | string | Yes | Album URL slug (e.g. 'killemall'). |
| `band_slug` | string | Yes | Band URL slug (e.g. 'metallica'). |
| `track_number` | string | Yes | Track number on the album (starting from 1). |

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

### Search

Search for artists, albums, or songs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/darklyrics/search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<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.