Genius API — Web Pages

naftiko: "1.0.0-alpha2"

info:
  label: "Genius API — Web Pages"
  description: >-
    Web Pages — lookup of web page records used by the Genius annotation network. 1 operation.
    Lead operation: Lookup Web Page.
    Self-contained Naftiko capability covering one Genius business surface.
  tags:
    - Genius
    - Music
    - WebPages
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      GENIUS_ACCESS_TOKEN: GENIUS_ACCESS_TOKEN

capability:

  consumes:
    - type: http
      namespace: "genius-web-pages"
      baseUri: "https://api.genius.com"
      description: "Genius API — Web Pages business capability."
      authentication:
        type: bearer
        token: "{{env.GENIUS_ACCESS_TOKEN}}"
      resources:
        - name: "web-pages-lookup"
          path: "/web_pages/lookup"
          operations:
            - name: "lookupWebPage"
              method: GET
              description: "Looks up a web page by canonical, og, or raw URL."
              inputParameters:
                - { name: "raw_annotatable_url", in: query, type: string, required: false, description: "Untransformed page URL." }
                - { name: "canonical_url",       in: query, type: string, required: false, description: "Canonical page URL." }
                - { name: "og_url",              in: query, type: string, required: false, description: "Open Graph URL." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]

  exposes:
    - type: rest
      namespace: "genius-web-pages-rest"
      port: 8080
      description: "REST adapter for Genius — Web Pages."
      resources:
        - path: "/v1/web-pages/lookup"
          name: "web-pages-lookup"
          description: "Web page lookup."
          operations:
            - method: GET
              name: "lookupWebPage"
              description: "Look up a Genius web page record."
              call: "genius-web-pages.lookupWebPage"
              with:
                "raw_annotatable_url": "rest.raw_annotatable_url"
                "canonical_url": "rest.canonical_url"
                "og_url": "rest.og_url"
              outputParameters: [{ type: object, mapping: "$." }]

    - type: mcp
      namespace: "genius-web-pages-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Genius — Web Pages."
      tools:
        - name: "lookup-web-page"
          description: "Look up a Genius web page record by URL."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-web-pages.lookupWebPage"
          with:
            "raw_annotatable_url": "tools.raw_annotatable_url"
            "canonical_url": "tools.canonical_url"
            "og_url": "tools.og_url"
          outputParameters: [{ type: object, mapping: "$." }]