Developer API
A read-only HTTP API for Harptabs harmonica tabs, charts, artists, and players. Base URL https://harptabs.com/api/v1.
Getting a key
API keys are issued by request. Tell us what you're building via the contact form and we'll grant a key at our discretion. Each key has a per-minute and per-day limit; access can be revoked at any time.
Authentication
Send your key in the Authorization header on every request. Keys look like htk_…. They are secrets — use them server-to-server, never from browser JavaScript (there is no CORS support, by design).
curl -H "Authorization: Bearer htk_your_key_here" \
"https://harptabs.com/api/v1/ping"
# → {"data":{"ok":true,"key":{"label":"Your app"}}}A missing or invalid key returns 401. Use /ping to check a key without spending daily quota.
Rate limits
Every response includes these headers:
X-RateLimit-Limit— your per-minute allowance.X-RateLimit-Remaining— requests left in the current minute.X-RateLimit-Reset— Unix time when the window resets.
Exceeding the per-minute burst or the daily quota returns 429 with a Retry-After header (seconds). Successful reads are cacheable — respect the Cache-Control header if you proxy them.
Errors
Errors use a consistent envelope:
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key." } }| Status | code | When |
|---|---|---|
| 400 | bad_request | Invalid or missing parameter. |
| 401 | unauthorized | Missing/invalid/revoked key. |
| 404 | not_found | No such tab. |
| 429 | rate_limited | Per-minute limit exceeded. |
| 429 | daily_quota | Daily quota exceeded. |
| 500 | internal | Unexpected server error. |
Endpoints
All endpoints are GET and require a key. List endpoints return { data: [...], paging: { limit, offset } }; limit is 1–60 (default 30), offset ≥ 0. Machine-readable schema: openapi.json.
GET /tabs
Search or browse tabs (metadata only — no body).
Params: q (text), author, user, harp, key, difficulty, genre (numeric codes below), sort (views | daily | newest | rating), limit, offset. With no filters/sort, returns newest.
curl -H "Authorization: Bearer htk_…" \
"https://harptabs.com/api/v1/tabs?sort=views&limit=2"
{
"data": [
{ "id": 55, "name": "Hey Jude", "artistName": "Beatles",
"harpType": 1, "difficulty": 1, "musicalKey": 5, "genre": 5,
"view": 1666149, "avgRate": 4, "hasAudio": true, "created": "2004-07-21T12:07:15.000Z" }
],
"paging": { "limit": 2, "offset": 0 }
}GET /tabs/{id}
A single tab including the full tablature body.
curl -H "Authorization: Bearer htk_…" "https://harptabs.com/api/v1/tabs/55"
{ "data": { "id": 55, "name": "Hey Jude", "artist": "Beatles",
"musicalKey": 5, "harpType": 1, "audioUrl": null,
"tab": "6 -6 6 ..." } }GET /charts
Leaderboards. Required metric: views | daily | rated. Plus limit/offset.
GET /artists/{id}/tabs
An artist's tabs (metadata). Returns a total in paging.
GET /players
Top contributors. ?sort=points (default) or ?sort=followed; every row carries a followers count. limit/offset.
GET /ping
Verify a key. Counts toward the per-minute limit but not the daily quota.
Response fields
List/card objects (returned by /tabs, /charts, /artists/{id}/tabs):
| Field | Type | Description |
|---|---|---|
| id | integer | Tab id. Use with /tabs/{id}. |
| name | string | Song title. |
| author | string | Free-text author (legacy). |
| artistName | string|null | Normalized artist name; null when unknown. |
| username | string | Uploader. |
| harpType | integer | Harp type code (see field codes). |
| difficulty | integer | Difficulty code (see field codes). |
| musicalKey | integer | Musical key code (see field codes). |
| genre | integer | Genre code (see field codes). |
| view | integer | All-time view count. |
| dailyView | integer | Today's view count (reset nightly). |
| avgRate | number | Average rating, 0–5. |
| favCount | integer | Number of favorites. |
| created | string(date-time) | Upload timestamp (UTC ISO 8601). |
| uploaderPoints | integer | Uploader's contributor points. |
| hasAudio | boolean | Whether an audio/MIDI URL exists. |
The single-tab object (/tabs/{id}) adds:
| Field | Type | Description |
|---|---|---|
| artist | string | Resolved artist name ("Unknown" fallback). |
| audioUrl | string|null | Audio/MIDI URL, if any. |
| modified | string|null | Last-edited timestamp (UTC). |
| tab | string|null | The full tablature body text. |
Field codes
Several fields are numeric codes. 0 means “Any/unspecified” and is also the value to omit when filtering.
harpType / harp
difficulty
musicalKey / key
genre
Embed a tab
No key needed for this one. Drop a chrome-less, read-only tab into your own page with an <iframe> pointing at /embed/tab/<id>. It carries no site nav, ads, or scripts — just the title, artist, and body — and links back to the full tab.
<iframe src="https://harptabs.com/embed/tab/123"
width="100%" height="480" style="border:0"
title="Harmonica tab" loading="lazy"></iframe>Feeds
Public RSS feeds, no API key needed. The two .php paths are the classic site's original feed URLs, kept working forever so existing readers and aggregators don't break.
- /feed.xml — tab of the day.
- /feed/new.xml — the newest tabs as they're posted.
- /rssfeed.php and /rssfeed2.php — the legacy equivalents of the two above.
Terms of use
- Attribute Harptabs as the source (e.g. “Data from Harptabs — harptabs.com”) and link back where practical.
- Do not bulk-mirror, resell, or redistribute the tab corpus. The API is for building experiences, not cloning the catalog.
- Respect the rate limits and quota on your key.
- Tabs are user-submitted; you are responsible for your own use of the content. We may restrict content or revoke any key at any time, especially for abuse. See the site Terms of use.