---
title: "Search and filter music"
method: GET
path: "/v1/music"
tags: ["Music"]
---

# Search and filter music

`GET /v1/music`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/music`
- Auth: API key in header `x-magnific-api-key`

Search the Magnific Music catalog. Filter by genre, mood, artist, premium status, and creation date range. Returns paginated results sorted by popularity by default.

## Query parameters

- `q` string
- `genre` string[]
- `mood` string[]
- `include-premium` boolean
- `time_range` '7d' | '30d' | '90d'
- `order_by` 'relevance' | 'popularity' | '-popularity' | 'created_at' | '-created_at' | 'title' | '-title' | 'seconds' | '-seconds' | 'bpm' | '-bpm'
- `limit` integer
- `offset` integer

## Response `200`

OK

- PaginatedMusicListResponse
  - `count` integer, required: Total number of results matching the query
  - `results` MusicListItem[], required
    - `id` integer, required: Unique identifier of the music item
    - `title` string, required: Music title
    - `artist` MusicListArtist, nullable: Simplified artist object returned in search results (MeilisearchTrackSerializer). Contains only the artist name.
      - `name` string, required: Artist name
    - `genres` GenreSearchTag[]: Genre tags from the search index
      - `id` integer: Genre identifier (may not always be present)
      - `name` 'Acoustic' | 'Afrobeat' | 'Ambient' | 'Blues' | 'Children' | 'Cinematic' | 'Classical' | 'Corporate' | 'Country' | 'Disco' | 'Electronic' | 'Funk' | 'Hip Hop' | 'Jazz' | 'Latin' | 'Lofi' | 'Lounge' | 'Pop' | 'Reggae' | 'RnB' | 'Rock' | 'Soul' | 'Synthwave' | 'World', required: Genre name
    - `moods` MoodSearchTag[]: Mood tags from the search index
      - `id` integer: Mood identifier (may not always be present)
      - `name` 'Dark' | 'Dramatic' | 'Elegant' | 'Energetic' | 'Epic' | 'Exciting' | 'Groovy' | 'Happy' | 'Hopeful' | 'Laid Back' | 'Melancholic' | 'Peaceful' | 'Playful' | 'Sad' | 'Sentimental' | 'Soulful' | 'Tension' | 'Upbeat', required: Mood name
    - `cover_url` string, nullable: URL to the music cover image
    - `file_url` string, nullable: Direct S3/CDN URL to the audio file
    - `preview_url` string, nullable: Preview URL for the audio file (same as file_url)
    - `download_url` string, nullable: URL to download the music
    - `seconds` integer: Music duration in seconds
    - `time` string: Music duration formatted as minutes and seconds
    - `popularity` integer: Popularity score
    - `is_premium` boolean: Whether the music is premium
    - `is_active` boolean: Whether the music is active
    - `created_at` string, date-time: Music creation timestamp
    - `downloads` integer: Total number of downloads
    - `favorites` integer: Total number of favorites
    - `in_playlists` integer: Number of playlists containing this music

## Other responses

- `400`: Bad Request - The server could not understand the request due to invalid syntax.
- `401`: Unauthorized - The client must authenticate itself to get the requested response.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)