Genius API — Referents

naftiko: "1.0.0-alpha2"

info:
  label: "Genius API — Referents"
  description: >-
    Referents — lyric fragments and their attached annotations. 2 operations.
    Lead operation: List Referents.
    Self-contained Naftiko capability covering one Genius business surface.
  tags:
    - Genius
    - Music
    - Referents
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      GENIUS_ACCESS_TOKEN: GENIUS_ACCESS_TOKEN

capability:

  consumes:
    - type: http
      namespace: "genius-referents"
      baseUri: "https://api.genius.com"
      description: "Genius API — Referents business capability."
      authentication:
        type: bearer
        token: "{{env.GENIUS_ACCESS_TOKEN}}"
      resources:
        - name: "referents"
          path: "/referents"
          operations:
            - name: "listReferents"
              method: GET
              description: "Returns referents filtered by song, web page, or creator."
              inputParameters:
                - { name: "song_id",       in: query, type: integer, required: false, description: "Filter by song." }
                - { name: "web_page_id",   in: query, type: integer, required: false, description: "Filter by web page." }
                - { name: "created_by_id", in: query, type: integer, required: false, description: "Filter by creator." }
                - { name: "per_page",      in: query, type: integer, required: false, description: "Results per page." }
                - { name: "page",          in: query, type: integer, required: false, description: "Page index." }
                - { name: "text_format",   in: query, type: string,  required: false, description: "Format for textual fields." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "referents-by-ids"
          path: "/referents/{ids}"
          operations:
            - name: "getReferents"
              method: GET
              description: "Returns one or more referents by their IDs."
              inputParameters:
                - { name: "ids",         in: path,  type: string, required: true,  description: "Comma-separated referent IDs." }
                - { name: "text_format", in: query, type: string, required: false, description: "Format for textual fields." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]

  exposes:
    - type: rest
      namespace: "genius-referents-rest"
      port: 8080
      description: "REST adapter for Genius — Referents."
      resources:
        - path: "/v1/referents"
          name: "referents"
          description: "Referent collection."
          operations:
            - method: GET
              name: "listReferents"
              description: "List referents."
              call: "genius-referents.listReferents"
              with:
                "song_id": "rest.song_id"
                "web_page_id": "rest.web_page_id"
                "created_by_id": "rest.created_by_id"
                "per_page": "rest.per_page"
                "page": "rest.page"
                "text_format": "rest.text_format"
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/referents/{ids}"
          name: "referents-by-ids"
          description: "Referent batch lookup."
          operations:
            - method: GET
              name: "getReferents"
              description: "Get referents by IDs."
              call: "genius-referents.getReferents"
              with: { "ids": "rest.ids", "text_format": "rest.text_format" }
              outputParameters: [{ type: object, mapping: "$." }]

    - type: mcp
      namespace: "genius-referents-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Genius — Referents."
      tools:
        - name: "list-referents"
          description: "List Genius referents filtered by song, web page, or creator."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-referents.listReferents"
          with:
            "song_id": "tools.song_id"
            "web_page_id": "tools.web_page_id"
            "created_by_id": "tools.created_by_id"
            "per_page": "tools.per_page"
            "page": "tools.page"
            "text_format": "tools.text_format"
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-referents"
          description: "Get Genius referents by IDs."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-referents.getReferents"
          with: { "ids": "tools.ids", "text_format": "tools.text_format" }
          outputParameters: [{ type: object, mapping: "$." }]