> ## 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.

# List songs

> Published songs, newest first by default. Supports the same filters as the site's browse page.



## OpenAPI

````yaml /openapi.json get /v1/songs
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/songs:
    get:
      tags:
        - Songs
      summary: List songs
      description: >-
        Published songs, newest first by default. Supports the same filters as
        the site's browse page.
      operationId: getV1Songs
      parameters:
        - name: q
          in: query
          schema:
            type: string
          description: Keyword search across title and credited artists.
        - name: genre
          in: query
          schema:
            type: string
          description: Genre slug. Repeat the parameter or comma-separate for several.
        - name: role
          in: query
          schema:
            type: string
          description: Role slug. Repeat the parameter or comma-separate for several.
        - name: artist_id
          in: query
          schema:
            type: integer
          description: Restrict to songs credited to this artist.
        - name: label_id
          in: query
          schema:
            type: integer
          description: Restrict to songs released on this label.
        - name: sort
          in: query
          schema:
            type: string
          description: Sort column.
        - name: order
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort direction.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 80
            default: 20
          description: Page size.
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Zero-based row offset.
      responses:
        '200':
          description: A page of songs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    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
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: >-
                          Total rows matching the query, ignoring limit and
                          offset.
                      limit:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: >-
                          Page size actually applied. Bounded by
                          apiConfig.maxLimit (80).
                      offset:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: Zero-based row offset of this page.
                    required:
                      - total
                      - limit
                      - offset
                required:
                  - data
                  - meta
        '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

````