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

# Search the catalogue

> Cross-category keyword search over songs, artists and labels. The same search that backs the site header.



## OpenAPI

````yaml /openapi.json get /v1/search
openapi: 3.1.0
info:
  title: Diskograf API
  description: >-
    A public, read-only REST API over the Diskograf catalogue of Malaysian
    music.


    No authentication is required and no endpoint writes. Requests are rate
    limited

    to 60 per 60 seconds per IP address.


    Every successful response is wrapped in an envelope. List endpoints return

    `{ "data": [...], "meta": { "total", "limit", "offset" } }`; detail
    endpoints

    return `{ "data": {...} }`. Errors return `{ "error": { "code", "message" }
    }`.
  version: 1.0.0
servers:
  - url: https://api.diskograf.com
    description: Production
security: []
tags:
  - name: Songs
    description: The catalogue of published songs and their credits.
  - name: Artists
    description: Performers, writers and producers, and their discographies.
  - name: Genres
    description: The genre taxonomy and the songs in each genre.
  - name: Labels
    description: Record labels and their releases.
  - name: Users
    description: Public contributor profiles. Private account fields are never returned.
  - name: Search
    description: Cross-category keyword search.
  - name: Meta
    description: Service index, statistics and health.
paths:
  /v1/search:
    get:
      tags:
        - Search
      summary: Search the catalogue
      description: >-
        Cross-category keyword search over songs, artists and labels. The same
        search that backs the site header.
      operationId: getV1Search
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: The keyword. Required, and capped in length.
      responses:
        '200':
          description: Matches grouped by category.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      songs:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            title:
                              type: string
                            slug:
                              type: string
                              description: >-
                                URL-safe form of the title. Not unique — pair it
                                with the id.
                            released_at:
                              type: string
                            artwork_url:
                              type: string
                              description: >-
                                Absolute CDN URL. Resolved server-side; never a
                                bare storage key.
                            artwork_source:
                              anyOf:
                                - type: string
                                  enum:
                                    - Custom
                                    - Apple Music
                                    - Spotify
                                    - YouTube
                                - type: 'null'
                            youtube_video_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                            youtube_video_url:
                              anyOf:
                                - type: string
                                - type: 'null'
                            artists:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                    minimum: -9007199254740991
                                    maximum: 9007199254740991
                                  name:
                                    type: string
                                required:
                                  - id
                                  - name
                              description: >-
                                Primary performing credits only, in credit
                                order.
                          required:
                            - id
                            - title
                            - slug
                            - released_at
                            - artwork_url
                            - artwork_source
                            - youtube_video_id
                            - youtube_video_url
                            - artists
                      artists:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            name:
                              type: string
                            slug:
                              type: string
                            prefix_title:
                              anyOf:
                                - type: string
                                - type: 'null'
                            is_group:
                              anyOf:
                                - type: boolean
                                - type: 'null'
                            total_songs:
                              anyOf:
                                - type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                                - type: 'null'
                            total_credits:
                              anyOf:
                                - type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                                - type: 'null'
                            disambiguator:
                              anyOf:
                                - type: string
                                - type: 'null'
                            avatar_url:
                              anyOf:
                                - type: string
                                - type: 'null'
                          required:
                            - id
                            - name
                            - slug
                            - prefix_title
                            - is_group
                            - total_songs
                            - total_credits
                            - disambiguator
                            - avatar_url
                      labels:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            name:
                              type: string
                            slug:
                              type: string
                          required:
                            - id
                            - name
                            - slug
                    required:
                      - songs
                      - artists
                      - labels
                required:
                  - data
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  responses:
    BadRequest:
      description: >-
        A query or path parameter failed validation. The message names the
        offending field.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - not_found
                      - bad_request
                      - internal_error
                  message:
                    type: string
                required:
                  - code
                  - message
            required:
              - error

````