MusicAtlas API (1.1.1)

Returns up to 20 similar tracks for a given artist + track using MusicAtlas catalog-aware search and canonical track resolution.

Behavior:

• By default, the endpoint may auto-resolve the input to an in-catalog canonical artist/title (using internal reference data) to improve match accuracy.
• If the input is not confidently resolvable, the endpoint validates that the track corresponds to a known released recording (for non-embed flows) and may return a “Did you mean?” suggestion.
• If embed is set, validation and resolution steps are skipped for predictable embed behavior.

If the track is not in the MusicAtlas catalog, the response includes in_catalog: false, a message, and suggest_add: true and may include a suggestion.

Returns a ranked list of artists similar to a given seed artist.

This endpoint is useful for:

• artist adjacency and discovery experiences
• “more artists like this” product features
• editorial research and exploration workflows
• artist recommendation layers in consumer or enterprise music products

Behavior:

• The request accepts a single seed artist name.
• The response returns a ranked list of similar artists with similarity scores.
• Returned artist objects are intentionally lightweight and optimized for discovery workflows.
• The exact field set may evolve over time as the artist similarity layer expands.

This endpoint is best used when your product needs artist-level proximity, rather than track-level recommendation or full catalog search.

Submits a track to MusicAtlas for ingestion, audio analysis, embedding generation, and metadata enrichment.

This endpoint is useful for:

• adding new released tracks to the MusicAtlas catalog
• powering “search this track even if it is not yet indexed” workflows
• enabling delayed ingestion with frontend progress polling
• expanding catalog coverage from developer applications

Behavior:

• The caller submits an artist and title.
• If accepted, the endpoint returns a job_id for asynchronous processing.
• Clients should poll /add_track_progress using that job_id until the job reaches done or error.
• If the track is already present in the catalog, the endpoint returns a conflict response.
• This endpoint is intended for known released tracks rather than arbitrary local audio uploads.

This endpoint starts an asynchronous workflow and does not block until analysis is complete.

Returns the current status of a previously submitted /add_track job.

This endpoint is useful for:

• polling asynchronous ingestion jobs
• updating frontend progress bars
• showing users queue state and estimated wait time
• resuming workflows once track analysis is complete

Behavior:

• The caller provides a job_id returned by /add_track.
• The response reports the current job state, completion percentage, optional ETA, and a status message.
• Typical job states are queued, started, done, and error.
• Clients should poll this endpoint until the job reaches either done or error.

This endpoint is designed for real-time product workflows where track analysis is handled asynchronously rather than as a blocking request.

Returns a structured track summary for a known MusicAtlas catalog track.

The response includes:

• track identity and platform metadata
• music characteristics such as BPM, key, and mode
• audio characteristics such as loudness, perceived intensity, and frequency density
• genre classification
• possible influence signals

This endpoint is useful for enrichment, explainability, editorial tooling, recommendation tuning, and any workflow that needs more than simple similarity results.

Returns a best-effort listening URL for a given artist + track.

Behavior:

• If source is provided, the response is backward compatible and returns source + url, and also returns sources containing fallback URLs for all supported platforms.
• If source is omitted, the response returns only sources (all supported platforms).

Notes:

• Links returned by this endpoint are search-based fallback URLs, not guaranteed deep links.
• source supports aliases (e.g., "amazonMusic", "amazonmusic" → "amazon"; "appleMusic" → "apple"; "youtubeMusic" → "youtube").

Returns MusicAtlas universal playlists using one of two modes:

• Recommendation mode: provide tags and/or geo to get up to 3 relevant playlists
• Lookup mode: provide artist_name and/or track_name without tags or geo to return all exact playlist matches

This endpoint is useful for:

• playlist recommendation modules
• mood- or geography-based music discovery flows
• universal playlist search across MusicAtlas editorial collections

Behavior:

• At least one of tags, geo, artist_name, or track_name is required.
• If tags and/or geo are present, the endpoint runs in recommendation mode and returns up to 3 playlists.
• If only artist_name and/or track_name are present, the endpoint runs in exact lookup mode and returns all matching playlists.
• Matching is performed against playlist metadata such as title, description, and tags, and in lookup mode may also use exact track membership.
• artist_name and track_name are normalized for exact matching to avoid accidental partial collisions.

Notes:

• Lookup mode items include a type field such as Genre, Region, Mood, or Activity.
• Recommendation mode items omit type and are optimized for lightweight display.

Returns the currently featured MusicAtlas universal playlist, updated weekly. Ideal for highlighting editorial picks or homepage displays. Works on all major streaming platforms.

Returns one randomly selected MusicAtlas universal playlist. Useful for casual discovery or "I'm feeling lucky" experiences. Works on all major streaming platforms.

Returns ranked track recommendations based on a blended set of liked tracks, with optional disliked tracks used to steer results away from unwanted directions.

This endpoint is useful for:

• custom recommendation engines
• playlist continuation flows
• taste profiling from a small seed set
• “more like these, but not like those” product experiences

Behavior:

• All input tracks must already exist in the MusicAtlas catalog.
• liked_tracks is required and acts as the positive recommendation seed set.
• disliked_tracks is optional and acts as a negative signal to reduce unwanted matches.
• The response includes ranked matches plus contextual summaries of the liked seed tracks.
• Results may be returned from cache when an equivalent seed combination was recently computed.

This public-facing endpoint returns safe, non-sensitive recommendation data including platform links, genres, hashtags, and track-level context suitable for downstream product use.

Returns high-level statistics for a partner catalog.

This endpoint provides lightweight analytics about a catalog without loading track objects or performing per-track enrichment.

Requires enterprise partner API access and authorization for the requested catalog.

Returns catalog-level metadata and contact details for a partner catalog.

This endpoint provides partner-facing catalog metadata such as contact emails, phone number, notes, and last-updated timestamp.

Requires enterprise partner API access and authorization for the requested catalog.

Returns the tracks in a partner catalog, with optional pagination.

Track rows may be enriched with lyric availability and related metadata.

Requires enterprise partner API access and authorization for the requested catalog.

Finds one or more tracks within a partner catalog using a simple text query.

This endpoint performs a lightweight text lookup across the catalog's canonical track input file. Matching is case-insensitive and uses loose token matching: all query tokens must appear somewhere in the combined artist/title string.

This endpoint is intended for locating tracks within a catalog and is distinct from specialized partner search endpoints such as reference, lyric, or prompt search.

Requires enterprise partner API access and authorization for the requested catalog.

Searches a partner catalog for similar tracks using a reference track defined by artist and title.

This endpoint proxies to the MusicAtlas match engine using the requested catalog as the partner-specific match scope. Results are returned in a partner-safe response shape and limited to the top 20 matches.

Requires enterprise partner API access and authorization for the requested catalog.

Searches a partner catalog for tracks matching a lyric text query.

This endpoint proxies to the partner lyric search service, deduplicates results by artist/title, and returns up to 20 matching tracks.

Requires enterprise partner API access and authorization for the requested catalog.

Searches a partner catalog using a natural-language prompt.

This endpoint wraps the MusicAtlas prompt assist workflow and constrains the search scope to the authorized partner catalog. It supports prompt-based catalog discovery using natural language, optional image inputs, and prompt-assist controls such as mode, max_results, fallback behavior, and seed policy.

Notes:

• The caller must provide catalog_uuid.
• The auth guard validates that the API key is authorized for that catalog.
• The validated catalog UUID is then injected into the backend request.
• Client-supplied catalog identifiers are ignored.
• Experimental prompt-assist modes are not exposed in the partner API.
• Response card shapes may evolve as prompt assist expands, but common track result fields are documented below for integration guidance.
• Internal model-specific similarity fields are removed from the public response.