Cache endpoints
Admin endpoints for inspecting and managing the cache.
All endpoints except /cache/help and /cache require the Authorization header
with the cache access token, sent as is with no Bearer prefix. A missing or wrong token returns
401 with the plain text body Unauthorized.
Authentication
curl -H "Authorization: your-cache-token" \
"https://api.betterlyrics.org/cache/keys"const res = await fetch("https://api.betterlyrics.org/cache/keys", {
headers: { "Authorization": "your-cache-token" },
});
const data = await res.json();import requests
res = requests.get(
"https://api.betterlyrics.org/cache/keys",
headers={"Authorization": "your-cache-token"},
)
data = res.json()package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://api.betterlyrics.org/cache/keys", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "your-cache-token")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}Endpoints overview
| Endpoint | Description | Auth required |
|---|---|---|
GET /cache/help | Documentation for cache endpoints | No |
GET /cache | Removed. Returns 410 Gone with a list of alternatives | No |
GET /cache/lookup | Check if a song is cached | Yes |
GET /cache/keys | List and search cache keys | Yes |
GET /cache/debug | Inspect a specific cache entry | Yes |
GET /cache/clear | Clear all cached lyrics and negative entries | Yes |
GET /cache/clear/{provider} | Clear cached lyrics and negative entries for one provider | Yes |
GET /cache/backup, /cache/backups, /cache/restore,
/cache/dump, /cache/migrate, /cache/migrate/status | Removed. Return 410 Gone. See Removed endpoints | Yes |
GET /cache/lookup
Check if lyrics are cached for a specific song. This checks the cache keys that /getLyrics uses,
with the exact duration (no duration tolerance).
Parameters
Name Type Required Description s, song, songNamestring Always send Song name. a, artist, artistNamestring Always send Artist name. al, album, albumNamestring Always send Album name. Improves matching. d, durationstring of digits Always send Track duration in whole seconds. Improves matching.
Send all four: the cache keys include album and duration, so a lookup without them checks a different key
than the one your lyrics requests use. The API rejects a request with 400 only when both song and
artist are missing:
{
"error": "Provide at least song (s) or artist (a) parameter"
}
Example
curl -H "Authorization: token" \
"https://api.betterlyrics.org/cache/lookup?s=E85&a=Don%20Toliver&al=OCTANE&d=154"
const res = await fetch("https://api.betterlyrics.org/cache/lookup?s=E85&a=Don%20Toliver&al=OCTANE&d=154", {
headers: { "Authorization": "token" },
});
const data = await res.json();
import requests
res = requests.get(
"https://api.betterlyrics.org/cache/lookup?s=E85&a=Don%20Toliver&al=OCTANE&d=154",
headers={"Authorization": "token"},
)
data = res.json()
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://api.betterlyrics.org/cache/lookup?s=E85&a=Don%20Toliver&al=OCTANE&d=154", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "token")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
{
"query": {
"song": "E85",
"artist": "Don Toliver",
"album": "OCTANE",
"duration": "154"
},
"normalized_key": "ttml_lyrics:e85 don toliver octane 154s",
"legacy_key": "ttml_lyrics:E85 Don Toliver OCTANE 154s",
"keys_differ": true,
"found": true,
"found_in": "normalized",
"track_duration_ms": 153181,
"score": 0.97,
"language": "en",
"isRTL": false,
"ttml_length": 17060,
"ttml_preview": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
}
Response fields
Field Type Always present Description queryobject Yes The song, artist, album and duration values as received. query.songstring Yes As received. query.artiststring Yes As received. query.albumstring Yes As received. query.durationstring Yes As received. normalized_keystring Yes Cache key in the current format (lowercase, trimmed). legacy_keystring Yes Cache key in the older format (original case, not trimmed). keys_differboolean Yes Whether the two keys are different. foundboolean Yes Whether lyrics are cached under either key. found_instring No Only when found is true. One of normalized, legacy. notestring No Set when the entry was found under the legacy key. track_duration_msinteger No Stored metadata of the entry. Only when found is true. scorenumber No Match confidence. languagestring No Stored metadata of the entry. Only when found is true. isRTLboolean No Stored metadata of the entry. Only when found is true. ttml_lengthinteger No Length of the stored lyrics. Only when found is true. ttml_previewstring No First 200 characters. negative_cacheboolean No Set when no lyrics are cached but a negative entry exists. negative_cache_instring No Set when the negative entry was found under the legacy key. One of legacy. negative_reasonstring No Set when no lyrics are cached but a negative entry exists.
GET /cache/keys
List and search cache keys.
Parameters
Name Type Required Description prefixstring No Only keys starting with this string. containsstring No Only keys containing this string. limitinteger No Maximum keys to return. Values above 1000 are capped at 1000.
Example
curl -H "Authorization: token" \
"https://api.betterlyrics.org/cache/keys?contains=taylor&limit=10"
const res = await fetch("https://api.betterlyrics.org/cache/keys?contains=taylor&limit=10", {
headers: { "Authorization": "token" },
});
const data = await res.json();
import requests
res = requests.get(
"https://api.betterlyrics.org/cache/keys?contains=taylor&limit=10",
headers={"Authorization": "token"},
)
data = res.json()
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://api.betterlyrics.org/cache/keys?contains=taylor&limit=10", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "token")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
{
"total_keys": 42,
"matched_keys": 10,
"limit": 10,
"keys": [
{
"key": "ttml_lyrics:love story taylor swift",
"size": 38211,
"provider": "ttml"
}
]
}
Response fields
Field Type Always present Description total_keysinteger Yes Number of cached lyrics keys that match the filters. matched_keysinteger Yes Number of keys in this response (at most limit). limitinteger Yes The limit that was applied. keysobject[] Yes Keys in alphabetical order. keys[].keystring Yes The cache key. keys[].sizeinteger Yes Size of the stored lyrics in bytes. keys[].providerstring Yes Provider of the entry.
Negative cache entries are not listed.
GET /cache/debug
Inspect a specific cache entry.
Parameters
Name Type Required Description keystring Yes Full cache key, for example ttml_lyrics:song artist.
Example
curl -H "Authorization: token" \
"https://api.betterlyrics.org/cache/debug?key=ttml_lyrics:e85%20don%20toliver%20octane%20154s"
const res = await fetch("https://api.betterlyrics.org/cache/debug?key=ttml_lyrics:e85%20don%20toliver%20octane%20154s", {
headers: { "Authorization": "token" },
});
const data = await res.json();
import requests
res = requests.get(
"https://api.betterlyrics.org/cache/debug?key=ttml_lyrics:e85%20don%20toliver%20octane%20154s",
headers={"Authorization": "token"},
)
data = res.json()
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://api.betterlyrics.org/cache/debug?key=ttml_lyrics:e85%20don%20toliver%20octane%20154s", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "token")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
{
"key": "ttml_lyrics:e85 don toliver octane 154s",
"found": true,
"type": "lyrics",
"track_duration_ms": 153181,
"score": 0.97,
"language": "en",
"isRTL": false,
"ttml_length": 17060,
"ttml_preview": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
}
Response fields
Field Type Always present Description keystring Yes The key that was inspected. foundboolean Yes Whether an entry exists for the key. typestring No no_lyrics_sentinel is a stored "no lyrics" marker. Only when found is true. One of lyrics, no_lyrics_sentinel, negative_cache. reasonstring No Present when type is negative_cache. track_duration_msinteger No Stored metadata. Only when type is lyrics. scorenumber No Match confidence. languagestring No Stored metadata. Only when type is lyrics. isRTLboolean No Stored metadata. Only when type is lyrics. ttml_lengthinteger No Length of the stored lyrics. Only when type is lyrics. ttml_previewstring No First 300 characters.
Without the key parameter, the response is 400 with {"error": "Provide 'key' parameter"}.
GET /cache/clear
Delete all cached lyrics and negative cache entries, for every provider. This cannot be undone through the API.
Example
curl -H "Authorization: token" \
"https://api.betterlyrics.org/cache/clear"
const res = await fetch("https://api.betterlyrics.org/cache/clear", {
headers: { "Authorization": "token" },
});
const data = await res.json();
import requests
res = requests.get(
"https://api.betterlyrics.org/cache/clear",
headers={"Authorization": "token"},
)
data = res.json()
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://api.betterlyrics.org/cache/clear", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "token")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
{
"message": "Cache cleared successfully"
}
GET /cache/clear/{provider}
Delete cached lyrics and negative cache entries for one provider. provider is one of
ttml, kugou, qq or legacy.
Example
curl -H "Authorization: token" \
"https://api.betterlyrics.org/cache/clear/kugou"
const res = await fetch("https://api.betterlyrics.org/cache/clear/kugou", {
headers: { "Authorization": "token" },
});
const data = await res.json();
import requests
res = requests.get(
"https://api.betterlyrics.org/cache/clear/kugou",
headers={"Authorization": "token"},
)
data = res.json()
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://api.betterlyrics.org/cache/clear/kugou", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "token")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
{
"message": "Cleared cache for provider: kugou",
"provider": "kugou",
"keys_deleted": 1234
}
keys_deleted counts the deleted lyrics entries. An unknown provider returns 400:
{
"error": "Unknown provider: foo",
"valid_providers": ["ttml", "kugou", "qq", "legacy"]
}
A database error on either clear endpoint returns 500 with an error field.
Removed endpoints
/cache/backup, /cache/backups, /cache/restore, /cache/dump,
/cache/migrate and /cache/migrate/status are removed. Backups are handled by the
database platform. With a valid token they return 410 Gone:
{
"error": "Endpoint removed",
"message": "This operation is not available on the managed Postgres backend. Backups and point-in-time recovery are handled by the platform."
}
/cache is also removed. It needs no token and returns 410 Gone with error,
message and an alternatives object.
Notes
- These endpoints are for administrative use only
- Lyrics cache entries do not expire. They stay until they are cleared.
- The cache access token is different from the API key