> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnific.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search and filter music

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

Use the Magnific Music API to search and filter music by genre, mood, artist, and more. See the [Music API overview](/api-reference/music/overview) for authentication and usage guidance.


## OpenAPI

````yaml get /v1/music
openapi: 3.0.0
info:
  description: >-
    The Magnific API is your gateway to a vast collection of high-quality
    digital resources for your applications and projects. As a leading platform,
    it offers a wide range of graphics, including vectors, photos,
    illustrations, icons, PSD templates, and more, all curated by talented
    designers from around the world.
  title: Magnific API
  version: 1.0.0
servers:
  - description: B2B API Production V1
    url: https://api.magnific.com
security:
  - magnificApiKey: []
paths:
  /v1/music:
    get:
      tags:
        - Music
      summary: Search and filter music
      description: >-
        Search the Magnific Music catalog. Filter by genre, mood, artist,
        premium status, and creation date range. Returns paginated results
        sorted by popularity by default.
      operationId: search_music
      parameters:
        - description: Full-text search query for music titles, artists, and tags
          example: summer vibes
          in: query
          name: q
          required: false
          schema:
            type: string
        - description: Filter by genre. Comma-separated for multiple values
          example: Electronic,Ambient
          explode: false
          in: query
          name: genre
          required: false
          schema:
            items:
              enum:
                - 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
              type: string
            type: array
          style: form
        - description: Filter by mood. Comma-separated for multiple values
          example: Happy,Energetic
          explode: false
          in: query
          name: mood
          required: false
          schema:
            items:
              enum:
                - Dark
                - Dramatic
                - Elegant
                - Energetic
                - Epic
                - Exciting
                - Groovy
                - Happy
                - Hopeful
                - Laid Back
                - Melancholic
                - Peaceful
                - Playful
                - Sad
                - Sentimental
                - Soulful
                - Tension
                - Upbeat
              type: string
            type: array
          style: form
        - description: >-
            Include premium music in search results. When false, only free music
            is returned
          in: query
          name: include-premium
          required: false
          schema:
            default: false
            type: boolean
        - description: Filter by creation date, relative to current date
          in: query
          name: time_range
          required: false
          schema:
            enum:
              - 7d
              - 30d
              - 90d
            type: string
        - description: >-
            Sort order for results. Prefix with "-" for descending. Defaults to
            "relevance" when a search query (q) is provided, otherwise defaults
            to "-popularity".
          in: query
          name: order_by
          required: false
          schema:
            enum:
              - relevance
              - popularity
              - '-popularity'
              - created_at
              - '-created_at'
              - title
              - '-title'
              - seconds
              - '-seconds'
              - bpm
              - '-bpm'
            type: string
        - description: Number of results to return per page
          in: query
          name: limit
          required: false
          schema:
            default: 10
            maximum: 1000
            minimum: 1
            type: integer
        - description: Number of results to skip for pagination
          in: query
          name: offset
          required: false
          schema:
            default: 0
            minimum: 0
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMusicListResponse'
          description: OK
        '400':
          content:
            application/json:
              examples:
                invalid_page:
                  summary: Parameter 'page' is not valid
                  value:
                    message: Parameter 'page' must be greater than 0
                invalid_query:
                  summary: Parameter 'query' is not valid
                  value:
                    message: Parameter 'query' must not be empty
                invalid_filter:
                  summary: Parameter 'filter' is not valid
                  value:
                    message: Parameter 'filter' is not valid
                generic_bad_request:
                  summary: Bad Request
                  value:
                    message: Parameter ':attribute' is not valid
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_400_response'
            application/problem+json:
              examples:
                invalid_page:
                  summary: Parameter 'page' is not valid
                  value:
                    message: Validation error
                    invalid_params:
                      - field: page
                        reason: Parameter 'page' must be greater than 0
                      - field: per_page
                        reason: Parameter 'per_page' must be greater than 0
              schema:
                $ref: >-
                  #/components/schemas/get_all_style_transfer_tasks_400_response_1
          description: >-
            Bad Request - The server could not understand the request due to
            invalid syntax.
        '401':
          content:
            application/json:
              examples:
                invalid_api_key:
                  summary: API key is not valid
                  value:
                    message: Invalid API key
                missing_api_key:
                  summary: API key is not provided
                  value:
                    message: Missing API key
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_400_response'
          description: >-
            Unauthorized - The client must authenticate itself to get the
            requested response.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_all_style_transfer_tasks_500_response'
          description: >-
            Internal Server Error - The server has encountered a situation it
            doesn't know how to handle.
components:
  schemas:
    PaginatedMusicListResponse:
      example:
        count: 150
        results:
          - favorites: 350
            file_url: file_url
            cover_url: cover_url
            is_active: true
            artist:
              name: John Doe
            moods:
              - name: Happy
              - name: Energetic
            created_at: '2000-01-23T04:56:07.000Z'
            in_playlists: 15
            title: Summer Vibes
            seconds: 225
            is_premium: true
            downloads: 1200
            genres:
              - name: Electronic
              - name: Ambient
            preview_url: preview_url
            popularity: 85
            download_url: download_url
            id: 1
            time: '3:45'
          - favorites: 350
            file_url: file_url
            cover_url: cover_url
            is_active: true
            artist:
              name: John Doe
            moods:
              - name: Happy
              - name: Energetic
            created_at: '2000-01-23T04:56:07.000Z'
            in_playlists: 15
            title: Summer Vibes
            seconds: 225
            is_premium: true
            downloads: 1200
            genres:
              - name: Electronic
              - name: Ambient
            preview_url: preview_url
            popularity: 85
            download_url: download_url
            id: 1
            time: '3:45'
      properties:
        count:
          description: Total number of results matching the query
          example: 150
          type: integer
        results:
          items:
            $ref: '#/components/schemas/MusicListItem'
          type: array
      required:
        - count
        - results
      type: object
    get_all_style_transfer_tasks_400_response:
      example:
        message: message
      properties:
        message:
          type: string
      type: object
    get_all_style_transfer_tasks_400_response_1:
      properties:
        problem:
          $ref: >-
            #/components/schemas/get_all_style_transfer_tasks_400_response_1_problem
      type: object
    get_all_style_transfer_tasks_500_response:
      example:
        message: Internal Server Error
      properties:
        message:
          example: Internal Server Error
          type: string
      type: object
    MusicListItem:
      description: >-
        Music item returned by search results (MeilisearchTrackSerializer).
        Fields are only included when non-null in the search index.
      example:
        favorites: 350
        file_url: file_url
        cover_url: cover_url
        is_active: true
        artist:
          name: John Doe
        moods:
          - name: Happy
          - name: Energetic
        created_at: '2000-01-23T04:56:07.000Z'
        in_playlists: 15
        title: Summer Vibes
        seconds: 225
        is_premium: true
        downloads: 1200
        genres:
          - name: Electronic
          - name: Ambient
        preview_url: preview_url
        popularity: 85
        download_url: download_url
        id: 1
        time: '3:45'
      properties:
        id:
          description: Unique identifier of the music item
          example: 1
          type: integer
        title:
          description: Music title
          example: Summer Vibes
          type: string
        artist:
          $ref: '#/components/schemas/MusicListArtist'
        genres:
          description: Genre tags from the search index
          example:
            - name: Electronic
            - name: Ambient
          items:
            $ref: '#/components/schemas/GenreSearchTag'
          type: array
        moods:
          description: Mood tags from the search index
          example:
            - name: Happy
            - name: Energetic
          items:
            $ref: '#/components/schemas/MoodSearchTag'
          type: array
        cover_url:
          description: URL to the music cover image
          nullable: true
          type: string
        file_url:
          description: Direct S3/CDN URL to the audio file
          nullable: true
          type: string
        preview_url:
          description: Preview URL for the audio file (same as file_url)
          nullable: true
          type: string
        download_url:
          description: URL to download the music
          nullable: true
          type: string
        seconds:
          description: Music duration in seconds
          example: 225
          type: integer
        time:
          description: Music duration formatted as minutes and seconds
          example: '3:45'
          type: string
        popularity:
          description: Popularity score
          example: 85
          type: integer
        is_premium:
          description: Whether the music is premium
          type: boolean
        is_active:
          description: Whether the music is active
          type: boolean
        created_at:
          description: Music creation timestamp
          format: date-time
          type: string
        downloads:
          description: Total number of downloads
          example: 1200
          type: integer
        favorites:
          description: Total number of favorites
          example: 350
          type: integer
        in_playlists:
          description: Number of playlists containing this music
          example: 15
          type: integer
      required:
        - id
        - title
      type: object
    get_all_style_transfer_tasks_400_response_1_problem:
      properties:
        message:
          example: Validation error
          type: string
        invalid_params:
          items:
            $ref: >-
              #/components/schemas/get_all_style_transfer_tasks_400_response_1_problem_invalid_params_inner
          type: array
      required:
        - invalid_params
        - message
      type: object
    MusicListArtist:
      description: >-
        Simplified artist object returned in search results
        (MeilisearchTrackSerializer). Contains only the artist name.
      example:
        name: John Doe
      nullable: true
      properties:
        name:
          description: Artist name
          example: John Doe
          type: string
      required:
        - name
      type: object
    GenreSearchTag:
      description: Genre tag object returned by the search index
      properties:
        id:
          description: Genre identifier (may not always be present)
          example: 1
          type: integer
        name:
          description: Genre name
          enum:
            - 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
          example: Electronic
          type: string
      required:
        - name
      type: object
    MoodSearchTag:
      description: Mood tag object returned by the search index
      properties:
        id:
          description: Mood identifier (may not always be present)
          example: 1
          type: integer
        name:
          description: Mood name
          enum:
            - Dark
            - Dramatic
            - Elegant
            - Energetic
            - Epic
            - Exciting
            - Groovy
            - Happy
            - Hopeful
            - Laid Back
            - Melancholic
            - Peaceful
            - Playful
            - Sad
            - Sentimental
            - Soulful
            - Tension
            - Upbeat
          example: Happy
          type: string
      required:
        - name
      type: object
    get_all_style_transfer_tasks_400_response_1_problem_invalid_params_inner:
      properties:
        name:
          description: Name of the invalid parameter.
          example: page
          type: string
        field:
          description: Field of the invalid parameter. Mirrors `name`.
          example: page
          type: string
        reason:
          example: Parameter 'page' must be greater than 0
          type: string
      required:
        - field
        - name
        - reason
      type: object
  securitySchemes:
    magnificApiKey:
      description: >
        Your Magnific API key. Required for authentication. [Learn how to obtain
        an API key](https://docs.magnific.com/quickstart)
      in: header
      name: x-magnific-api-key
      type: apiKey

````