canonical: https://jentic.com/apis/asuarez.dev/searchly

# Asuarez SearchLy API v1

SearchLy is a similarity search API over song lyrics, built on a 100k-song corpus scraped from AZLyrics and indexed with word2vec embeddings and NMSLIB k-nearest-neighbour retrieval. It exposes three operations: similarity by song identifier, similarity by free-text content, and a song search by query string. The service runs on a small DigitalOcean instance, so it is best suited to research, prototyping, and lyric-driven recommendation experiments rather than high-traffic production use.

## For AI agents

Find songs whose lyrics are semantically similar to a given song or free-text passage by querying SearchLy's word2vec-indexed catalogue.

## Scope

Does not handle audio fingerprinting, streaming, or licensed lyric retrieval - use for open lyric similarity search and song catalogue lookup only.

## Capabilities

- Find songs whose lyrics are semantically similar to a known song via GET `/similarity/by_song`
- Find songs similar to an arbitrary block of free text using POST `/similarity/by_content`
- Search the underlying song catalogue by title or artist with GET `/song/search`
- Power lyric-based music recommendations using k-nearest-neighbour retrieval over word2vec embeddings
- Prototype thematic music discovery without training a custom embedding model

## Use cases

### Lyric-Based Music Recommendation

Music discovery apps want to suggest songs that share the meaning of a track the user just played, not just the genre. SearchLy's `/similarity/by_song` endpoint returns the nearest neighbours of a given song in lyric-embedding space, so a recommender can surface thematically related tracks even across genres. Indexing is precomputed so latency is bounded by the small hosting instance.

Example prompt: Call GET `/similarity/by_song` with the song id for 'Hallelujah' and return the top 10 most lyric-similar songs

### Free-Text Lyric Match

Writers, journalists, and creative tools sometimes want a song that fits a passage of text - a poem, a paragraph, or a news quote. The POST `/similarity/by_content` endpoint accepts free text in the request body and returns the songs whose lyrics are closest in word2vec space. This makes 'soundtrack this paragraph' style features straightforward.

Example prompt: POST a paragraph of text to `/similarity/by_content` and return the top 5 songs with the closest lyric embeddings

### Song Catalogue Lookup

Before running a similarity query you often need to resolve a song title or artist into the SearchLy id. The GET `/song/search` endpoint accepts a query string and returns matching catalogue entries with their internal ids. An agent can chain a `/song/search` call into a `/similarity/by_song` call to deliver title-based similarity in a single user turn.

Example prompt: Call GET `/song/search` with q='hallelujah leonard cohen', take the first id from the response, and pass it to GET `/similarity/by_song`

### Lyric Similarity Through a Jentic Agent

Through Jentic, an AI agent fielding a lyric-similarity question searches by intent and Jentic returns the matching SearchLy operation with its input schema. Because SearchLy is open and unauthenticated, Jentic's value is discovery and request validation - turning a vague request like 'songs that feel like this poem' into a correct POST `/similarity/by_content` call against searchly.asuarez.dev.

Example prompt: Use Jentic to search 'find songs similar to a passage of text', load POST `/similarity/by_content`, and execute with the user's input string

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/similarity/by_song` | Find songs similar to a given song id |
| POST | `/similarity/by_content` | Find songs similar to a free-text passage |
| GET | `/song/search` | Search the song catalogue by query string |

## Key resources

- **Similarity** — Lyric similarity search by song identifier or free-text content
- **Song** — Search the underlying catalogue of indexed songs

## Why Jentic

- **Setup:** Wiring SearchLy by hand means resolving its host and shaping the right request body for similarity and song-search calls, even though there is no credential to manage. Through Jentic you install once, import SearchLy from the API Directory, and your agent calls it with no key to configure.
- **Permission scoping:** SearchLy's similarity and search operations carry their target in the query or request body rather than a resource id in the URL path, so limit the agent to the operations it needs, such as similarity by content or song search. You choose the operations it may call, and all exposed operations are read-only lookups.
- **Credential handling:** SearchLy is unauthenticated, so there is no credential to store. Jentic still routes the call through your own Jentic One instance at execution time for consistent handling alongside authenticated APIs.
- **Discovery method:** Agents search Jentic by intent such as 'find songs similar to a passage of text', and Jentic returns the matching SearchLy operation with its body schema so the agent posts the right shape without inspecting the spec.

## Related APIs

- **Musixmatch** — Licensed lyrics catalogue with track metadata and matching
- **Spotify** — Streaming catalogue and audio-feature based recommendations
- **Open similarity search example** — Different open API illustrating how Jentic handles unauthenticated public services

## FAQ

### What authentication does the SearchLy API use?

SearchLy is open and does not require authentication - the spec defines no security schemes. Through Jentic, the call is still validated against the schema and routed without exposing the upstream URL pattern to the agent.

### Can I search for songs by free text with the SearchLy API?

Yes. POST `/similarity/by_content` accepts a JSON body containing a free-text passage and returns the songs in the catalogue whose lyrics are nearest in word2vec embedding space. This is the recommended path when the user does not have a specific song in mind.

### What are the rate limits for the SearchLy API?

The spec does not declare a rate limit. The maintainer notes the API is hosted on a small DigitalOcean instance, so callers should expect best-effort latency and avoid tight loops - batch and cache results where possible.

### How do I find songs similar to a specific track through Jentic?

First search Jentic for 'find a song by title', load GET `/song/search`, and resolve the song id. Then search Jentic for 'find similar songs by lyrics', load GET `/similarity/by_song`, and call it with the resolved id. Jentic chains the two calls without the agent having to handle either URL.

### Is the SearchLy API free?

Yes - the API is open source, hosted by the maintainer, and free to use within the implicit fair-use limits of a small single-instance deployment.

### What corpus does SearchLy index?

SearchLy indexes around 100,000 songs scraped from AZLyrics, embedded with word2vec, and served through an NMSLIB k-nearest-neighbour index. The catalogue is updated periodically by the maintainer's scraper.

### Can I limit what my agent is allowed to do with the SearchLy API?

Yes. Because you run Jentic One yourself, your own rules decide which SearchLy operations the agent may call, so you can allow only similarity by content or song search and withhold the rest. Each operation carries its target in the query string or request body rather than a resource id in the URL, and every exposed operation is a read-only lookup, so a scoped agent can retrieve lyric matches without modifying any data.