naftiko: 1.0.0-alpha2
info:
  label: Smithsonian Collection Discovery
  description: Workflow capability for discovering and exploring Smithsonian Institution collections. Used by researchers,
    educators, and developers to search across 22 million museum objects, artworks, and natural history specimens, retrieve
    detailed metadata, explore subject categories, and get collection statistics.
  tags:
  - Smithsonian Institution
  - Collections
  - Museums
  - Open Data
  - Cultural Heritage
  - Research
  - Education
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SMITHSONIAN_API_KEY: SMITHSONIAN_API_KEY
capability:
  consumes:
  - type: http
    namespace: smithsonian-open-access
    baseUri: https://edan.si.edu/openaccess
    description: Smithsonian Open Access API for collection data retrieval
    authentication:
      type: apikey
      key: api_key
      value: '{{SMITHSONIAN_API_KEY}}'
      placement: query
    resources:
    - name: content
      path: /api/content
      description: Individual collection item retrieval
      operations:
      - name: get-content
        method: GET
        description: Get detailed metadata for a specific collection item by ID
        inputParameters:
        - name: id
          in: query
          type: string
          required: true
          description: Unique identifier of the collection item
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: search
      path: /api/search/search
      description: Full-text collection search
      operations:
      - name: search-collections
        method: GET
        description: Search across all Smithsonian collections
        inputParameters:
        - name: q
          in: query
          type: string
          required: true
          description: Search query
        - name: start
          in: query
          type: integer
          required: false
          description: Pagination offset
        - name: rows
          in: query
          type: integer
          required: false
          description: Number of results
        - name: sort
          in: query
          type: string
          required: false
          description: Sort order (relevancy, id, newest, updated, random)
        - name: type
          in: query
          type: string
          required: false
          description: Record type filter (edanmdm, ead_collection, all)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: category-search
      path: /api/search/category_search
      description: Category-filtered collection search
      operations:
      - name: search-by-category
        method: GET
        description: Search collections filtered by subject category
        inputParameters:
        - name: q
          in: query
          type: string
          required: true
          description: Search query
        - name: category
          in: query
          type: string
          required: false
          description: Category (art_design, history_culture, science_technology)
        - name: start
          in: query
          type: integer
          required: false
          description: Pagination offset
        - name: rows
          in: query
          type: integer
          required: false
          description: Number of results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: terms
      path: /api/search/terms
      description: Search facet terms
      operations:
      - name: get-search-terms
        method: GET
        description: Get available facet terms for a category
        inputParameters:
        - name: category
          in: query
          type: string
          required: true
          description: Facet category (culture, date, object_type, topic, place, etc.)
        - name: starts_with
          in: query
          type: string
          required: false
          description: Filter terms by starting character
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: metrics
      path: /api/metrics/stats
      description: Collection metrics and statistics
      operations:
      - name: get-metrics-stats
        method: GET
        description: Get aggregate statistics about the Smithsonian collection
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: collection-discovery-api
    description: Unified REST API for Smithsonian collection discovery and exploration.
    resources:
    - path: /v1/search
      name: search
      description: Full-text collection search
      operations:
      - method: GET
        name: search-collections
        description: Search across all Smithsonian collections
        call: smithsonian-open-access.search-collections
        with:
          q: rest.q
          start: rest.start
          rows: rest.rows
          sort: rest.sort
          type: rest.type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/search/category
      name: category-search
      description: Category-filtered search
      operations:
      - method: GET
        name: search-by-category
        description: Search by subject category
        call: smithsonian-open-access.search-by-category
        with:
          q: rest.q
          category: rest.category
          start: rest.start
          rows: rest.rows
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/items/{id}
      name: item
      description: Individual collection item
      operations:
      - method: GET
        name: get-item
        description: Get detailed metadata for a collection item
        call: smithsonian-open-access.get-content
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/search/terms
      name: search-terms
      description: Search facet terms
      operations:
      - method: GET
        name: get-terms
        description: Get available terms for search faceting
        call: smithsonian-open-access.get-search-terms
        with:
          category: rest.category
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/metrics
      name: metrics
      description: Collection statistics
      operations:
      - method: GET
        name: get-metrics
        description: Get collection statistics and metrics
        call: smithsonian-open-access.get-metrics-stats
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9080
    namespace: collection-discovery-mcp
    transport: http
    description: MCP server for AI-assisted Smithsonian collection discovery.
    tools:
    - name: search-collections
      description: Search across all 22 million Smithsonian collection items including artworks, natural history specimens,
        cultural objects, and archival materials
      hints:
        readOnly: true
        openWorld: true
      call: smithsonian-open-access.search-collections
      with:
        q: tools.q
        start: tools.start
        rows: tools.rows
        sort: tools.sort
        type: tools.type
      outputParameters:
      - type: object
        mapping: $.
    - name: search-art-and-design
      description: Search Smithsonian art and design collections specifically
      hints:
        readOnly: true
        openWorld: true
      call: smithsonian-open-access.search-by-category
      with:
        q: tools.q
        category: art_design
        start: tools.start
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: search-history-and-culture
      description: Search Smithsonian history and cultural collections
      hints:
        readOnly: true
        openWorld: true
      call: smithsonian-open-access.search-by-category
      with:
        q: tools.q
        category: history_culture
        start: tools.start
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: search-science-and-technology
      description: Search Smithsonian science and technology collections
      hints:
        readOnly: true
        openWorld: true
      call: smithsonian-open-access.search-by-category
      with:
        q: tools.q
        category: science_technology
        start: tools.start
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: get-collection-item
      description: Get complete metadata for a specific Smithsonian collection item including description, media images, provenance,
        and classification data
      hints:
        readOnly: true
        openWorld: true
      call: smithsonian-open-access.get-content
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: browse-facet-terms
      description: Get available facet values for filtering searches by culture, place, object type, date, topic, or museum
        unit
      hints:
        readOnly: true
        openWorld: true
      call: smithsonian-open-access.get-search-terms
      with:
        category: tools.category
        starts_with: tools.starts_with
      outputParameters:
      - type: object
        mapping: $.
    - name: get-collection-stats
      description: Get aggregate statistics about the Smithsonian collections including total object counts, online media
        counts, and open access availability
      hints:
        readOnly: true
        openWorld: true
      call: smithsonian-open-access.get-metrics-stats
      outputParameters:
      - type: object
        mapping: $.