Genius API — Artists

naftiko: "1.0.0-alpha2"

info:
  label: "Genius API — Artists"
  description: >-
    Artists — artist profiles, discography, followers, activity, and leaderboards. 6 operations.
    Lead operation: Get Artist.
    Self-contained Naftiko capability covering one Genius business surface.
  tags:
    - Genius
    - Music
    - Artists
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      GENIUS_ACCESS_TOKEN: GENIUS_ACCESS_TOKEN

capability:

  consumes:
    - type: http
      namespace: "genius-artists"
      baseUri: "https://api.genius.com"
      description: "Genius API — Artists business capability."
      authentication:
        type: bearer
        token: "{{env.GENIUS_ACCESS_TOKEN}}"
      resources:
        - name: "artist"
          path: "/artists/{id}"
          operations:
            - name: "getArtist"
              method: GET
              description: "Returns artist metadata."
              inputParameters:
                - { name: "id",         in: path,  type: integer, required: true,  description: "Genius artist ID." }
                - { name: "text_format",in: query, type: string,  required: false, description: "Format for textual fields." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "artist-songs"
          path: "/artists/{id}/songs"
          operations:
            - name: "getArtistSongs"
              method: GET
              description: "Returns a paginated list of songs for the artist."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius artist ID." }
                - { name: "sort",     in: query, type: string,  required: false, description: "Sort key (title, popularity, release_date)." }
                - { 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: "artist-albums"
          path: "/artists/{id}/albums"
          operations:
            - name: "getArtistAlbums"
              method: GET
              description: "Returns albums associated with the artist."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius artist 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: "artist-activity"
          path: "/artists/{id}/activity"
          operations:
            - name: "getArtistActivity"
              method: GET
              description: "Activity stream covering all of the artist's songs."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius artist 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: "artist-followers"
          path: "/artists/{id}/followers"
          operations:
            - name: "getArtistFollowers"
              method: GET
              description: "Returns users who follow the artist."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius artist 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: "artist-leaderboard"
          path: "/artists/{id}/leaderboard"
          operations:
            - name: "getArtistLeaderboard"
              method: GET
              description: "Top scholars for an artist."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius artist 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-artists-rest"
      port: 8080
      description: "REST adapter for Genius — Artists."
      resources:
        - path: "/v1/artists/{id}"
          name: "artist"
          description: "Artist detail."
          operations:
            - method: GET
              name: "getArtist"
              description: "Get an artist by ID."
              call: "genius-artists.getArtist"
              with: { "id": "rest.id", "text_format": "rest.text_format" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/artists/{id}/songs"
          name: "artist-songs"
          description: "List artist songs."
          operations:
            - method: GET
              name: "getArtistSongs"
              description: "List artist songs."
              call: "genius-artists.getArtistSongs"
              with: { "id": "rest.id", "sort": "rest.sort", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/artists/{id}/albums"
          name: "artist-albums"
          description: "List artist albums."
          operations:
            - method: GET
              name: "getArtistAlbums"
              description: "List artist albums."
              call: "genius-artists.getArtistAlbums"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/artists/{id}/activity"
          name: "artist-activity"
          description: "Artist activity stream."
          operations:
            - method: GET
              name: "getArtistActivity"
              description: "Artist activity stream."
              call: "genius-artists.getArtistActivity"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/artists/{id}/followers"
          name: "artist-followers"
          description: "Artist followers."
          operations:
            - method: GET
              name: "getArtistFollowers"
              description: "List artist followers."
              call: "genius-artists.getArtistFollowers"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/artists/{id}/leaderboard"
          name: "artist-leaderboard"
          description: "Artist leaderboard."
          operations:
            - method: GET
              name: "getArtistLeaderboard"
              description: "Top scholars for an artist."
              call: "genius-artists.getArtistLeaderboard"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]

    - type: mcp
      namespace: "genius-artists-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Genius — Artists."
      tools:
        - name: "get-artist"
          description: "Get a Genius artist by ID."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-artists.getArtist"
          with: { "id": "tools.id", "text_format": "tools.text_format" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-artist-songs"
          description: "List songs by an artist."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-artists.getArtistSongs"
          with: { "id": "tools.id", "sort": "tools.sort", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-artist-albums"
          description: "List albums by an artist."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-artists.getArtistAlbums"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-artist-activity"
          description: "Get the activity stream for an artist."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-artists.getArtistActivity"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-artist-followers"
          description: "List followers of an artist."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-artists.getArtistFollowers"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-artist-leaderboard"
          description: "Get the leaderboard (top scholars) for an artist."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-artists.getArtistLeaderboard"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]