Public API - Diskograf

Diskograf provides a read-only REST API for the public catalogue. You can use it to search songs and artists, browse genres and labels, and build contributor-facing experiences around published Malaysian music data.

Quick start

The production base URL is:

https://api.diskograf.com

All catalogue routes are under /v1. Every catalogue request uses GET and is available without an API key.

curl "https://api.diskograf.com/v1/songs?q=hujan&limit=5"

The API also supports browser requests through CORS. Use GET /v1 to retrieve the current route index, or GET /health to check whether the service can reach its database.

The API is for reading public data. Use Diskograf’s web app to sign in, contribute catalogue data, or manage an account.

Access, visibility, and limits

Access

No authentication or API key is required.
The API accepts GET and CORS preflight OPTIONS requests.
The API is read-only. It does not expose write, account, or administrative operations.

Public data rules

The API applies the same public visibility rules as the web app:

Song endpoints return published, non-deleted songs only.
User endpoints return public, claimed, non-banned member profiles.
Loved-song endpoints return only published, non-deleted songs.
A public user profile may link to a claimed artist profile. Private account fields are never returned.
Labels are included when they are associated with at least one published song.

Rate limits

Production traffic is limited to 60 requests per 60 seconds per IP address. When the limit is reached, the API returns 429 Too Many Requests with a Retry-After: 60 header.

Caching

Catalogue responses include these cache directives:

Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=3600

Treat responses as changeable. Cache them according to the response header rather than assuming that a record is immutable.

Response format

Most endpoints use one of these envelopes:

Response type	Shape	Used by
List	`{ "data": [], "meta": { "total": 0, "limit": 20, "offset": 0 } }`	Paginated collections and full taxonomy lists
Item	`{ "data": {} }`	Single songs, artists, genres, labels, users, overviews, search, and stats
Error	`{ "error": { "code": "...", "message": "..." } }`	API errors

For list responses, meta.total is the number of matching or returned records, depending on the endpoint. Full lists such as genres and roles use the list envelope even though they do not accept pagination parameters. The health endpoint is the exception. It returns a direct status object rather than a data envelope.

Pagination and filtering

`limit` and `offset`

limit is the number of records to return. The default is 20.
offset is zero-based. The default is 0.
Invalid, negative, or out-of-range values return 400 Bad Request.
The effective maximum depends on the collection:

Collection	Maximum `limit`
Songs and song collections	40
Artists	40
Labels	40
Public contributors at `/v1/users`	24
A member’s contributions	80

Genres and roles return their complete public lists and do not use limit or offset query parameters.

Repeated filters

Array filters accept either comma-separated values or repeated query parameters. These requests are equivalent:

/v1/songs?genre=rock,pop
/v1/songs?genre=rock&genre=pop

The genre and role filters use slugs. Empty values are ignored.

Search and ordering

q is trimmed and accepts up to 200 characters.
order accepts asc or desc where the endpoint supports ordering.
Invalid sort, order, filter, or identifier values return 400 Bad Request.
When stable ordering matters, provide both sort and order instead of relying on a resource’s default.

The supported ordering fields are:

Resource	`sort` values
Songs	`released_at`, `gen_youtube_views`, `gen_youtube_views_rate`, `trend`, `title`, `id`
Artists	`name`, `total_songs`
Labels	`name`, `total_songs`
User directory	`active`, `newest`, `contributions`, `name`

Endpoint reference

Service endpoints

Method and route	Description
`GET /health`	Returns `{ "status": "ok" }` when the API can reach its database. A database failure returns `503` with `{ "status": "error", "detail": "database unreachable" }`.
`GET /v1`	Returns the API version and the list of available public routes.

Songs

Method and route	Description	Parameters
`GET /v1/songs`	Lists published songs.	`q`, `genre`, `role`, `artist_id`, `label_id`, `sort`, `order`, `limit`, `offset`
`GET /v1/songs/{songId}`	Returns one published song and its full credits, genres, labels, and metrics.	`songId` is a positive integer.
`GET /v1/songs/{songId}/similar`	Returns related songs grouped into `by_artist` and `by_others`. Matches can use shared genres, performing artists, or writing credits.	`songId` is a positive integer.
`GET /v1/songs/{songId}/contributors`	Returns the public contributor timeline for a song.	`songId` is a positive integer.
`GET /v1/songs/{songId}/provider-stats`	Returns the stored YouTube, Spotify, and Apple Music stats for a song. The API never calls a provider.	`songId` is a positive integer.

For /v1/songs, q searches song titles and credited artists. artist_id and label_id accept positive integer IDs. Song list responses contain song cards; see Song data.

Artists

Method and route	Description	Parameters
`GET /v1/artists`	Lists artists and groups in the catalogue.	`q`, `letter`, `role`, `status`, `band`, `sort`, `order`, `limit`, `offset`
`GET /v1/artists/{artistId}`	Returns an artist profile, links, roles, genres, and associated acts.	`artistId` is a positive integer.
`GET /v1/artists/{artistId}/songs`	Lists published songs credited to an artist in any role.	`q`, `genre`, `role`, `sort`, `order`, `limit`, `offset`
`GET /v1/artists/namesake-hints?ids=...`	Finds disambiguation hints for artist IDs that share a name.	`ids` is required and accepts 1–200 positive integer IDs, comma-separated or repeated.

Artist-specific routes return 404 when the artist is unknown or not publicly available. For the directory endpoint:

q searches artist names and aliases.
letter filters by the first character. Use # for names that begin with a non-letter.
status accepts user or not-user.
band accepts true or false to filter groups or individuals.

Genres

Method and route	Description	Parameters
`GET /v1/genres`	Returns the complete public genre taxonomy with song counts.	No query parameters.
`GET /v1/genres/{slug}`	Returns one genre’s description and display metadata.	`slug` is the genre slug.
`GET /v1/genres/{slug}/songs`	Lists published songs in a genre.	`q`, `role`, `sort`, `order`, `limit`, `offset`

An unknown genre slug returns 404 rather than an empty collection.

Labels

Method and route	Description	Parameters
`GET /v1/labels`	Lists public labels that have at least one published song.	`q`, `sort`, `order`, `limit`, `offset`
`GET /v1/labels/{labelId}`	Returns a label’s public ID and name.	`labelId` is a positive integer.
`GET /v1/labels/{labelId}/songs`	Lists published songs associated with a label.	`q`, `genre`, `role`, `sort`, `order`, `limit`, `offset`

An unknown label returns 404. The label detail endpoint intentionally returns only public label metadata; internal import metadata is not part of the API.

Albums and curated lists

Method and route	Description	Parameters
`GET /v1/albums`	Lists published albums with at least one visible song.	No query parameters.
`GET /v1/albums/{albumId}`	Returns album metadata, artists, and ordered tracks.	`albumId` is a positive integer.
`GET /v1/songs/{songId}/albums`	Lists published album memberships for one public song.	`songId` is a positive integer.
`GET /v1/curated-lists/{listId}`	Returns one published editorial song list.	`listId` is a positive integer.

An unknown album, song, or curated list returns 404. Album and curated-list responses exclude unpublished and deleted songs.

Public users and contributors

Method and route	Description	Parameters
`GET /v1/users`	Lists public contributor profiles.	`q`, `filter`, `sort`, `limit`, `offset`
`GET /v1/users/overview`	Returns contributor totals and top contributors.	No query parameters.
`GET /v1/users/{username}`	Returns a public member profile and its optional artist link.	`username` is the public handle, not a numeric user ID.
`GET /v1/users/{username}/contributions`	Lists a member’s contribution history, newest first.	`limit`, `offset`
`GET /v1/users/{username}/loves`	Lists the member’s published, non-deleted loved songs.	`limit`, `offset`
`GET /v1/users/{username}/songs`	Lists published songs credited to the member’s claimed artist profile.	`q`, `genre`, `role`, `sort`, `order`, `limit`, `offset`

For /v1/users:

q searches names and usernames.
filter accepts everyone, fans, artists, or contributors.
sort accepts active, newest, contributions, or name.

The contributions endpoint returns 404 for an unavailable username. The songs endpoint also returns 404 when the member does not have a claimed artist profile.

Search and reference data

Method and route	Description	Parameters
`GET /v1/search?q=...`	Searches songs, artists, and labels in one response.	`q` is required and accepts up to 200 characters.
`GET /v1/roles`	Returns the complete public credit-role taxonomy.	No query parameters.
`GET /v1/stats`	Returns public catalogue totals and year ranges.	No query parameters.

Search is not paginated. It currently returns up to 50 songs, 30 artists, and 20 labels in the response.

Resource data

Song data

Song card

Song cards are used by song lists, search results, similar songs, artist and label discographies, and contribution history.

Field	Description
`id`	Numeric song ID.
`title`	Song title.
`slug`	URL-safe title slug. Use `id` with the slug when you need a unique reference.
`released_at`	Release date value.
`artwork_url`	Absolute URL for the song artwork.
`artwork_source`	`Custom`, `Apple Music`, `Spotify`, `YouTube`, or `null`.
`youtube_video_id`	YouTube video ID, or `null`.
`youtube_video_url`	YouTube URL, or `null`.
`artists`	Primary performing artists in credit order. Each item contains `id` and `name`.

Song detail

Song detail adds published_at, views, claps, and the complete credit and classification data:

{
  "data": {
    "id": 123,
    "title": "Example song",
    "slug": "example-song",
    "released_at": "2024-01-01",
    "published_at": "2024-01-02T00:00:00.000Z",
    "views": 0,
    "claps": 0,
    "artwork_url": "https://cdn.diskograf.com/...",
    "artwork_source": null,
    "notes": null,
    "lyrics": null,
    "love_count": 0,
    "media": {
      "youtube_id": null,
      "spotify_id": null,
      "apple_music_id": null,
      "spotify_url": null,
      "apple_music_url": null,
      "date_type": null,
      "duration_ms": null
    },
    "youtube": {
      "duration_seconds": null,
      "views": null,
      "views_per_day": null,
      "last_fetched": null
    },
    "credits": [],
    "genres": [],
    "labels": []
  }
}

Each credit contains order, an artist object, and a role object. A role can be null for an unclassified credit. Each artist includes a resolved avatar_url. Each role includes id, title, slug, tag, and order. Each genre contains id, slug, and title; each label contains id and name. Song detail also includes notes, lyrics, and love_count. The media object contains named YouTube, Spotify, Apple Music, date-type, and duration fields. The youtube object contains duration, views, views-per-day, and last-fetched fields. Raw song and YouTube JSON are not returned.

Song contributors

GET /v1/songs/{songId}/contributors returns:

{
  "data": {
    "song_id": 123,
    "added_by": null,
    "edited_by": null,
    "contributions": []
  }
}

The public user shape inside this response is { "username", "name", "avatar_url" }. The contributions array contains the action name, timestamp, and public user for each event. This is a timeline, not a full historical snapshot of every version of a song.

Song provider stats

GET /v1/songs/{songId}/provider-stats returns the last stored provider snapshots:

{
  "data": {
    "youtube": {
      "video_id": "ZYh2sHzde7A",
      "views": 63173,
      "views_per_day": 99463,
      "views_per_day_current": 76956,
      "video_published_at": "2026-09-25T13:00:11Z",
      "likes": 5627,
      "duration_seconds": 199,
      "last_fetched": "2026-09-26T04:14:47.899Z"
    },
    "spotify": {
      "track_id": "4xvs2J7oe4yB6PwAOd5wCj",
      "popularity": 43,
      "last_fetched": "2026-09-26T01:14:33.867Z"
    },
    "apple_music": {
      "track_id": "6809348393",
      "last_fetched": "2026-09-26T01:17:24.402Z"
    }
  }
}

views_per_day is the lifetime average: total views divided by the days since the video was published.
views_per_day_current is the rate between the last two fetches. It is null until the video has two fetches, and 0 when views did not grow.
video_published_at is the publish time that YouTube reports. It can differ from the song’s released_at.
Any field can be null when the provider has no value. Compare last_fetched to decide how fresh a snapshot is.

Artist data

Artist cards contain:

id, name, slug, prefix_title, is_group, total_songs, total_credits,
disambiguator, first_release_year, last_release_year, avatar_url, username

Nullable values are returned as null. Artist detail adds:

aliases, biodata, country, place, birth and death fields, job, and status.
alias_artists, each with id, name, and prefix_title.
links with website, instagram, twitter, tiktok, youtube, facebook, spotify, and applemusic keys.
roles, each with id, slug, title, and a credit count.
genres, each with id, slug, title, and a song count.
associated_acts, each with id, name, slug, username, and avatar_url.

Genre and label data

Genre list items contain id, slug, title, color, and song_count. A genre detail item also includes description. Label list items contain id, name, slug, and song_count. Label detail contains id and name.

Album and curated-list data

An album summary contains id, title, album_type, artwork_url, song_count, and latest_released_at. Album detail contains id, title, album_type, artwork_url, released_at, an artists array, and a songs array. album_type is album, ep, or single. Its released_at uses the manual album date when set, otherwise the latest release date among visible tracks. Each album artist contains id, name, prefix_title, and is_group. Each album track is a song card plus position, date_type, duration_ms, and youtube_duration_seconds. duration_ms is the manually-entered track length; youtube_duration_seconds is the auto-fetched YouTube length, used as a fallback when duration_ms is null. A song’s album membership (/v1/songs/{songId}/albums) contains id, title, artwork_url, and the track position. A curated list contains id, title, description, and a songs array of song cards.

User data

A public user profile contains:

username, name, avatar_url, created_at, is_fan, profile, artist

profile contains named biography, location, date, job, status, alias, and social-link fields. artist is either null or an object containing the claimed artist’s id, name, slug, prefix_title, aliases, is_group, total_songs, total_credits, first_release_year, last_release_year, avatar_url, and associated_acts. User directory items also include joined_at and contribution_count. The overview endpoint returns:

public_members, contributors, recent_contributions, active, all_time

active represents the recent 30-day window. active and all_time contain the top public contributors and are capped at 10 entries each. Contribution history items contain id, action, action_at, and song. song is either a song card or null when the related song is no longer publicly available. GET /v1/users/{username}/loves returns published, non-deleted song cards in love order. Its list metadata reports the total visible songs.

Search data

GET /v1/search returns one item envelope with three arrays:

songs, artists, labels

The songs array contains song cards. Artist search results contain the public artist card fields needed for discovery. Label search results contain id, name, and slug.

Roles and stats

Role items contain id, slug, title, and order. The stats response contains:

songs, artists, contributors, credits, earliest_year, genres, labels

Errors

Errors use the same JSON shape:

{
  "error": {
    "code": "bad_request",
    "message": "Invalid limit"
  }
}

Common status codes are:

Status	`code`	Meaning
`400`	`bad_request`	A query parameter or path identifier is invalid.
`404`	`not_found`	The route or public resource does not exist.
`429`	`rate_limited`	Too many requests. Retry after the number of seconds in `Retry-After`.
`500`	`internal_error`	An unexpected server error occurred.

Unknown routes return 404 and include a message pointing you to GET /v1. The health endpoint uses 503 for a database connectivity failure and returns its direct health status shape.

Versioning

Use the /v1 prefix in production integrations. Backward-compatible fields and routes may be added. Treat existing fields and route behavior as stable within the version, and handle unknown response fields without failing. The API is intentionally read-only. For contributions, account features, and authenticated workflows, direct users to diskograf.com.

​Quick start

​Access, visibility, and limits

​Access

​Public data rules

​Rate limits

​Caching

​Response format

​Pagination and filtering

​limit and offset

​Repeated filters

​Search and ordering

​Endpoint reference

​Service endpoints

​Songs

​Artists

​Genres

​Labels

​Albums and curated lists

​Public users and contributors

​Search and reference data

​Resource data

​Song data

​Song card

​Song detail

​Song contributors

​Song provider stats

​Artist data

​Genre and label data

​Album and curated-list data

​User data

​Search data

​Roles and stats

​Errors

​Versioning

Quick start

Access, visibility, and limits

Access

Public data rules

Rate limits

Caching

Response format

Pagination and filtering

`limit` and `offset`

Repeated filters

Search and ordering

Endpoint reference

Service endpoints

Songs

Artists

Genres

Labels

Albums and curated lists

Public users and contributors

Search and reference data

Resource data

Song data

Song card

Song detail

Song contributors

Song provider stats

Artist data

Genre and label data

Album and curated-list data

User data

Search data

Roles and stats

Errors

Versioning