# Songsterr — 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 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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/get_full_tab \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/get_popular_songs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/get_song_meta \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/get_song_revisions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/get_songs_by_artist \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/get_tab_data \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-songsterr-com-api-70820305/search_songs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offset":"<integer>","query":"<string>","size":"<integer>"}'
```