# Songsterr — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 and retrieve guitar tab notation, song metadata, and artist information from Songsterr. Access song popularity rankings, revision history, and complete tab data to power music education platforms, tab libraries, and music reference applications.

**Category:** Music | **Website:** [songsterr.com/](https://songsterr.com/) | **Docs:** [parse.bot/marketplace/70820305-8f34-40db-9fa2-7b732fa4e406/songsterr-com-api](https://parse.bot/marketplace/70820305-8f34-40db-9fa2-7b732fa4e406/songsterr-com-api)

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

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/songsterr/`
**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 full tab

Convenience method that fetches song metadata and tab notation in one call. First retrieves metadata via get_song_meta, then uses it to fetch the tab for the popular track (or specified track index). Returns both meta and tab data combined.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `song_id` | string | Yes | Numeric song ID. Obtainable from search_songs results via songId field. |
| `track_index` | integer | No | Zero-based track index. If omitted, uses the song's popularTrack value from metadata. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/songsterr/get-full-tab \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"song_id":"<string>","track_index":"<integer>"}'
```

### Get popular songs

Retrieve currently popular/trending songs on Songsterr. Returns a paginated object with a records array and a more boolean indicating whether additional pages exist. Results are ordered by current popularity.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `offset` | integer | No | Number of results to skip for pagination. |
| `size` | integer | No | Maximum number of results to return per page. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/songsterr/get-popular-songs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"offset":"<integer>","size":"<integer>"}'
```

### Get song meta

Retrieve full metadata for a single song by its ID. Includes detailed track listings, tags, view counts, favorites, revision info, video references, and audio hashes needed to fetch tab notation data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `song_id` | string | Yes | Numeric song ID. Obtainable from search_songs or get_popular_songs results via the songId field. |

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

### Get song revisions

Retrieve the revision history for a song. Returns an array of revision objects ordered newest-first, each with timestamp, author, description of changes, track count, and review status.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `song_id` | string | Yes | Numeric song ID. Obtainable from search_songs results via the songId field. |

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

### Get songs by artist

Retrieve all songs/tabs available for a specific artist. Returns an array of song summaries with track listings. The artist_id is obtainable from search_songs or get_song_meta results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_id` | string | Yes | Numeric artist ID. Obtainable from search_songs or get_song_meta results via the artistId field. |

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

### Get tab data

Fetch raw tab/notation data for a specific track of a song. Requires revisionId and image hash from get_song_meta response. Returns detailed notation with measures, beats, notes, tuning, capo, and tempo automations.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `image_hash` | string | Yes | Image hash from get_song_meta response (image field). |
| `revision_id` | string | Yes | Revision ID from get_song_meta response (revisionId field). |
| `song_id` | string | Yes | Numeric song ID. Obtainable from search_songs results via songId field. |
| `track_index` | string | Yes | Zero-based track index. Obtainable from get_song_meta response (popularTrack or defaultTrack field). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/songsterr/get-tab-data \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"image_hash":"<string>","revision_id":"<string>","song_id":"<string>","track_index":"<string>"}'
```

### Search songs

Full-text search over Songsterr's tab catalog. Matches against song title and artist name. Returns paginated results ordered by relevance. Each result includes track listings with instrument, difficulty, and view counts.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `offset` | integer | No | Number of results to skip for pagination. |
| `query` | string | Yes | Search query string matching song title or artist name. |
| `size` | integer | No | Maximum number of results to return per page. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/songsterr/search-songs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"offset":"<integer>","query":"<string>","size":"<integer>"}'
```

## Next steps

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