naftiko: "1.0.0-alpha2"
info:
label: "Genius API — Albums"
description: >-
Albums — album metadata, tracks, cover arts, comments, and leaderboards. 5 operations.
Lead operation: Get Album.
Self-contained Naftiko capability covering one Genius business surface.
tags:
- Genius
- Music
- Albums
created: "2026-05-29"
modified: "2026-05-29"
binds:
- namespace: env
keys:
GENIUS_ACCESS_TOKEN: GENIUS_ACCESS_TOKEN
capability:
consumes:
- type: http
namespace: "genius-albums"
baseUri: "https://api.genius.com"
description: "Genius API — Albums business capability."
authentication:
type: bearer
token: "{{env.GENIUS_ACCESS_TOKEN}}"
resources:
- name: "album"
path: "/albums/{id}"
operations:
- name: "getAlbum"
method: GET
description: "Returns album metadata."
inputParameters:
- { name: "id", in: path, type: integer, required: true, description: "Genius album ID." }
- { name: "text_format",in: query, type: string, required: false, description: "Format for textual fields." }
outputRawFormat: json
outputParameters: [{ name: result, type: object, value: "$." }]
- name: "album-tracks"
path: "/albums/{id}/tracks"
operations:
- name: "getAlbumTracks"
method: GET
description: "Returns the album tracklist."
inputParameters:
- { name: "id", in: path, type: integer, required: true, description: "Genius album ID." }
- { name: "per_page", in: query, type: integer, required: false, description: "Results per page." }
- { name: "page", in: query, type: integer, required: false, description: "Page index." }
outputRawFormat: json
outputParameters: [{ name: result, type: object, value: "$." }]
- name: "album-comments"
path: "/albums/{id}/comments"
operations:
- name: "getAlbumComments"
method: GET
description: "Returns comments left on the album page."
inputParameters:
- { name: "id", in: path, type: integer, required: true, description: "Genius album ID." }
- { name: "per_page", in: query, type: integer, required: false, description: "Results per page." }
- { name: "page", in: query, type: integer, required: false, description: "Page index." }
outputRawFormat: json
outputParameters: [{ name: result, type: object, value: "$." }]
- name: "album-cover-arts"
path: "/albums/{id}/cover_arts"
operations:
- name: "getAlbumCoverArts"
method: GET
description: "Returns all cover-art images attached to the album."
inputParameters:
- { name: "id", in: path, type: integer, required: true, description: "Genius album ID." }
outputRawFormat: json
outputParameters: [{ name: result, type: object, value: "$." }]
- name: "album-leaderboard"
path: "/albums/{id}/leaderboard"
operations:
- name: "getAlbumLeaderboard"
method: GET
description: "Returns top contributors to the album."
inputParameters:
- { name: "id", in: path, type: integer, required: true, description: "Genius album ID." }
- { name: "per_page", in: query, type: integer, required: false, description: "Results per page." }
- { name: "page", in: query, type: integer, required: false, description: "Page index." }
outputRawFormat: json
outputParameters: [{ name: result, type: object, value: "$." }]
exposes:
- type: rest
namespace: "genius-albums-rest"
port: 8080
description: "REST adapter for Genius — Albums."
resources:
- path: "/v1/albums/{id}"
name: "album"
description: "Album detail."
operations:
- method: GET
name: "getAlbum"
description: "Get an album by ID."
call: "genius-albums.getAlbum"
with: { "id": "rest.id", "text_format": "rest.text_format" }
outputParameters: [{ type: object, mapping: "$." }]
- path: "/v1/albums/{id}/tracks"
name: "album-tracks"
description: "Album tracklist."
operations:
- method: GET
name: "getAlbumTracks"
description: "List tracks on an album."
call: "genius-albums.getAlbumTracks"
with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
outputParameters: [{ type: object, mapping: "$." }]
- path: "/v1/albums/{id}/comments"
name: "album-comments"
description: "Album comments."
operations:
- method: GET
name: "getAlbumComments"
description: "List album comments."
call: "genius-albums.getAlbumComments"
with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
outputParameters: [{ type: object, mapping: "$." }]
- path: "/v1/albums/{id}/cover-arts"
name: "album-cover-arts"
description: "Album cover arts."
operations:
- method: GET
name: "getAlbumCoverArts"
description: "Get album cover arts."
call: "genius-albums.getAlbumCoverArts"
with: { "id": "rest.id" }
outputParameters: [{ type: object, mapping: "$." }]
- path: "/v1/albums/{id}/leaderboard"
name: "album-leaderboard"
description: "Album leaderboard."
operations:
- method: GET
name: "getAlbumLeaderboard"
description: "Get top contributors to the album."
call: "genius-albums.getAlbumLeaderboard"
with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
outputParameters: [{ type: object, mapping: "$." }]
- type: mcp
namespace: "genius-albums-mcp"
port: 9090
transport: http
description: "MCP adapter for Genius — Albums."
tools:
- name: "get-album"
description: "Get a Genius album by ID."
hints: { readOnly: true, destructive: false, idempotent: true }
call: "genius-albums.getAlbum"
with: { "id": "tools.id", "text_format": "tools.text_format" }
outputParameters: [{ type: object, mapping: "$." }]
- name: "list-album-tracks"
description: "List tracks on a Genius album."
hints: { readOnly: true, destructive: false, idempotent: true }
call: "genius-albums.getAlbumTracks"
with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
outputParameters: [{ type: object, mapping: "$." }]
- name: "list-album-comments"
description: "List comments on a Genius album."
hints: { readOnly: true, destructive: false, idempotent: true }
call: "genius-albums.getAlbumComments"
with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
outputParameters: [{ type: object, mapping: "$." }]
- name: "get-album-cover-arts"
description: "Get cover-art images for a Genius album."
hints: { readOnly: true, destructive: false, idempotent: true }
call: "genius-albums.getAlbumCoverArts"
with: { "id": "tools.id" }
outputParameters: [{ type: object, mapping: "$." }]
- name: "get-album-leaderboard"
description: "Get the leaderboard for a Genius album."
hints: { readOnly: true, destructive: false, idempotent: true }
call: "genius-albums.getAlbumLeaderboard"
with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
outputParameters: [{ type: object, mapping: "$." }]