Skip to content

docs: tighten /research/track spec — add artist disambiguation + 404 #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 2 commits into from
Apr 16, 2026
Merged

docs: tighten /research/track spec — add artist disambiguation + 404 #138

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c058e90
docs: tighten /research/track spec — add artist disambiguation + 404
sweetmantech Apr 16, 2026
1bd5911
docs: correct /research/track response schema to match actual response
sweetmantech Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 123 additions & 12 deletions api-reference/openapi/research.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2351,13 +2351,22 @@
},
"/api/research/track": {
"get": {
"description": "Get track metadata — title, artist, album, release date, popularity, and platform IDs.",
"description": "Get track metadata — title, artist, album, release date, popularity, and platform IDs.\n\nResolves `q` against Chartmetric's track search and returns details for the top-ranked match. Common track names are ambiguous (e.g. \"Flowers\", \"God's Plan\") — for reliable disambiguation, either pass a Spotify track URL as `q`, or pair `q` with the `artist` query param.",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"description": "Track name or Spotify URL.",
"description": "Track name or Spotify track URL. URLs (e.g. `https://open.spotify.com/track/<id>`) resolve directly without ambiguity. Plain names are searched via Chartmetric's track search; results may not match user intent without an `artist` filter.",
"schema": {
"type": "string"
}
},
{
"name": "artist",
"in": "query",
"required": false,
"description": "Optional artist name used to disambiguate when `q` is a plain track name. Matched case-insensitively against the candidate tracks' artist names; the top-ranked candidate whose artist names contain this value wins. Recommended whenever `q` is not a Spotify URL.",
"schema": {
"type": "string"
}
Expand Down Expand Up @@ -2393,6 +2402,16 @@
}
}
}
},
"404": {
"description": "No track matched the supplied `q` (and `artist`, when present)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResearchErrorResponse"
}
Comment on lines +2406 to +2412
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Align shared error-schema wording with the new 404 usage.

You now return ResearchErrorResponse for 404 here, but Line 5021 describes that schema as only for 400/401. This creates contradictory docs.

Proposed docs fix 
-        "description": "Error response returned by all research endpoints for validation failures (400) and authentication errors (401).",
+        "description": "Error response returned by research endpoints for client errors (for example, 400 validation failures, 401 authentication failures, and 404 not found where documented).",
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi/research.json` around lines 2406 - 2412, The OpenAPI
spec now references ResearchErrorResponse for 404 in the endpoint response block
but the components/schemas description for ResearchErrorResponse currently
states it's only for 400/401; update the ResearchErrorResponse schema
description under components/schemas (symbol: ResearchErrorResponse) to include
404 and align its wording with its usage in responses (or alternatively adjust
the endpoint's 404 response to reference the correct schema). Ensure the schema
description and every response referencing ResearchErrorResponse (including the
endpoint that currently lists 404) consistently reflect the same set of status
codes and error wording.

}
}
}
}
}
Expand Down Expand Up @@ -4713,29 +4732,121 @@
},
"ResearchTrackResponse": {
"type": "object",
"description": "Track metadata — title, artist, album, release date, popularity, and platform IDs.",
"description": "Track metadata — title, artists, albums, release date, genres, popularity, and platform IDs. Only the most commonly-used fields are enumerated here; the upstream Chartmetric response includes additional fields (e.g. `cm_statistics`, `activities`, `moods`) that pass through under `additionalProperties`.",
"properties": {
"status": {
"type": "string"
},
"name": {
"type": "string"
},
"id": {
"type": "integer",
"description": "Chartmetric track ID"
},
"name": {
"type": "string",
"description": "Track title"
},
"isrc": {
"type": "string"
"type": "string",
"nullable": true
},
"album_name": {
"type": "string"
"image_url": {
"type": "string",
"nullable": true
},
"duration_ms": {
"type": "integer",
"nullable": true
},
"release_date": {
"type": "string"
"type": "string",
"description": "ISO date string",
"nullable": true
},
"artist_names": {
"type": "string"
"album_label": {
"type": "string",
"nullable": true
},
"score": {
"type": "integer",
"description": "Chartmetric track score",
"nullable": true
},
"explicit": {
"type": "boolean",
"nullable": true
},
"artists": {
"type": "array",
"description": "Credited artists. Each entry is a Chartmetric artist object; at minimum `id` and `name` are populated.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Chartmetric artist ID"
},
"name": {
"type": "string"
},
"image_url": {
"type": "string",
"nullable": true
}
},
"additionalProperties": true
}
},
"albums": {
"type": "array",
"description": "Albums the track appears on.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Chartmetric album ID"
},
"name": {
"type": "string"
},
"upc": {
"type": "string",
"nullable": true
},
"release_date": {
"type": "string",
"nullable": true
},
"label": {
"type": "string",
"nullable": true
},
"image_url": {
"type": "string",
"nullable": true
},
"popularity": {
"type": "integer",
"nullable": true
}
},
"additionalProperties": true
}
},
"genres": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
Expand Down