Rijksmuseum Collection API — Collection

naftiko: "1.0.0-alpha2"

info:
  label: "Rijksmuseum Collection API — Collection"
  description: >-
    Collection — Collection. 1 operation. Lead operation: Search The Rijksmuseum
    Collection. Self-contained Naftiko capability covering one Rijksmuseum
    business surface.
  tags:
    - Rijksmuseum
    - Collection
    - Search
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      RIJKSMUSEUM_API_KEY: RIJKSMUSEUM_API_KEY

capability:

  consumes:
    - type: http
      namespace: "collection-collection"
      baseUri: "https://www.rijksmuseum.nl/api"
      description: "Rijksmuseum Collection API — Collection business capability. Self-contained, no shared references."
      authentication:
        type: apikey
        key: key
        value: "{{env.RIJKSMUSEUM_API_KEY}}"
        placement: query
      resources:
        - name: "collection"
          path: "/{culture}/collection"
          operations:
            - name: "searchCollection"
              method: GET
              description: "Search the Rijksmuseum collection with filters by maker, type, material, technique, century, colour, image availability, and top-piece flag."
              inputParameters:
                - name: "culture"
                  in: path
                  type: string
                  required: true
                  description: "Locale: `nl` (Dutch) or `en` (English)."
                - name: "format"
                  in: query
                  type: string
                  required: false
                  description: "Response format: json, jsonp, xml."
                - name: "p"
                  in: query
                  type: integer
                  required: false
                  description: "Result page (0-based). p * ps <= 10,000."
                - name: "ps"
                  in: query
                  type: integer
                  required: false
                  description: "Results per page (1-100)."
                - name: "q"
                  in: query
                  type: string
                  required: false
                  description: "Free-text query."
                - name: "involvedMaker"
                  in: query
                  type: string
                  required: false
                  description: "Restrict to objects produced by this maker."
                - name: "type"
                  in: query
                  type: string
                  required: false
                  description: "Object type."
                - name: "material"
                  in: query
                  type: string
                  required: false
                  description: "Material of the object."
                - name: "technique"
                  in: query
                  type: string
                  required: false
                  description: "Production technique."
                - name: "f.dating.period"
                  in: query
                  type: integer
                  required: false
                  description: "Century 0-21."
                - name: "f.normalized32Colors.hex"
                  in: query
                  type: string
                  required: false
                  description: "Dominant colour hex (`#` must be URL-encoded)."
                - name: "imgonly"
                  in: query
                  type: boolean
                  required: false
                  description: "Only return objects with images."
                - name: "toppieces"
                  in: query
                  type: boolean
                  required: false
                  description: "Only return top pieces."
                - name: "s"
                  in: query
                  type: string
                  required: false
                  description: "Sort order."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "collection-collection-rest"
      port: 8080
      description: "REST adapter for Rijksmuseum Collection API — Collection. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/cultures/{culture}/collection"
          name: "collection"
          description: "REST surface for the Rijksmuseum collection search."
          operations:
            - method: GET
              name: "searchCollection"
              description: "Search The Rijksmuseum Collection."
              call: "collection-collection.searchCollection"
              with:
                culture: "rest.culture"
                format: "rest.format"
                p: "rest.p"
                ps: "rest.ps"
                q: "rest.q"
                involvedMaker: "rest.involvedMaker"
                type: "rest.type"
                material: "rest.material"
                technique: "rest.technique"
                f.dating.period: "rest.f.dating.period"
                f.normalized32Colors.hex: "rest.f.normalized32Colors.hex"
                imgonly: "rest.imgonly"
                toppieces: "rest.toppieces"
                s: "rest.s"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "collection-collection-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Rijksmuseum Collection API — Collection. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "search-collection"
          description: "Search The Rijksmuseum Collection."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "collection-collection.searchCollection"
          with:
            culture: "tools.culture"
            format: "tools.format"
            p: "tools.p"
            ps: "tools.ps"
            q: "tools.q"
            involvedMaker: "tools.involvedMaker"
            type: "tools.type"
            material: "tools.material"
            technique: "tools.technique"
            f.dating.period: "tools.f.dating.period"
            f.normalized32Colors.hex: "tools.f.normalized32Colors.hex"
            imgonly: "tools.imgonly"
            toppieces: "tools.toppieces"
            s: "tools.s"
          outputParameters:
            - type: object
              mapping: "$."