EPA Air Quality System (AQS) API — Lists

naftiko: 1.0.0-alpha2
info:
  label: EPA Air Quality System (AQS) API — Lists
  description: 'Lists. 8 operations. Lead operation: List States. Self-contained Naftiko capability covering one EPA business surface.'
  tags:
    - EPA
    - Lists
  created: '2026-05-29'
  modified: '2026-05-29'
binds:
  - namespace: env
    keys:
      EPA_EMAILKEY_KEY: EPA_EMAILKEY_KEY
capability:
  consumes:
    - type: http
      namespace: aqs-lists
      baseUri: https://aqs.epa.gov/data/api
      description: EPA Air Quality System (AQS) API — Lists business capability. Self-contained, no shared references.
      authentication:
        type: apikey
        key: key
        value: '{{env.EPA_EMAILKEY_KEY}}'
        placement: query
      resources:
        - name: list-states
          path: /list/states
          operations:
            - name: listStates
              method: GET
              description: List States
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: list-countiesbystate
          path: /list/countiesByState
          operations:
            - name: listCountiesByState
              method: GET
              description: List Counties by State
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
                - name: state
                  in: query
                  type: string
                  required: true
                  description: 2-digit state FIPS code.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: list-sitesbycounty
          path: /list/sitesByCounty
          operations:
            - name: listSitesByCounty
              method: GET
              description: List Sites by County
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
                - name: state
                  in: query
                  type: string
                  required: true
                  description: 2-digit state FIPS code.
                - name: county
                  in: query
                  type: string
                  required: true
                  description: 3-digit county code.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: list-cbsas
          path: /list/cbsas
          operations:
            - name: listCbsas
              method: GET
              description: List Core Based Statistical Areas
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: list-classes
          path: /list/classes
          operations:
            - name: listClasses
              method: GET
              description: List Parameter Classes
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: list-parametersbyclass
          path: /list/parametersByClass
          operations:
            - name: listParametersByClass
              method: GET
              description: List Parameters by Class
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
                - name: pc
                  in: query
                  type: string
                  required: true
                  description: pc
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: list-pqaos
          path: /list/pqaos
          operations:
            - name: listPqaos
              method: GET
              description: List Primary Quality Assurance Organizations
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: list-mas
          path: /list/mas
          operations:
            - name: listMas
              method: GET
              description: List Monitoring Agencies
              inputParameters:
                - name: email
                  in: query
                  type: string
                  required: true
                  description: Registered email address.
                - name: key
                  in: query
                  type: string
                  required: true
                  description: Account-specific access key.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
  exposes:
    - type: rest
      namespace: aqs-lists-rest
      port: 8080
      description: REST adapter for EPA Air Quality System (AQS) API — Lists. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/list/states
          name: list-states
          description: REST surface for List States.
          operations:
            - method: GET
              name: listStates
              description: List States
              call: aqs-lists.listStates
              with:
                email: rest.email
                key: rest.key
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/list/countiesbystate
          name: list-countiesbystate
          description: REST surface for List Counties by State.
          operations:
            - method: GET
              name: listCountiesByState
              description: List Counties by State
              call: aqs-lists.listCountiesByState
              with:
                email: rest.email
                key: rest.key
                state: rest.state
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/list/sitesbycounty
          name: list-sitesbycounty
          description: REST surface for List Sites by County.
          operations:
            - method: GET
              name: listSitesByCounty
              description: List Sites by County
              call: aqs-lists.listSitesByCounty
              with:
                email: rest.email
                key: rest.key
                state: rest.state
                county: rest.county
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/list/cbsas
          name: list-cbsas
          description: REST surface for List Core Based Statistical Areas.
          operations:
            - method: GET
              name: listCbsas
              description: List Core Based Statistical Areas
              call: aqs-lists.listCbsas
              with:
                email: rest.email
                key: rest.key
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/list/classes
          name: list-classes
          description: REST surface for List Parameter Classes.
          operations:
            - method: GET
              name: listClasses
              description: List Parameter Classes
              call: aqs-lists.listClasses
              with:
                email: rest.email
                key: rest.key
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/list/parametersbyclass
          name: list-parametersbyclass
          description: REST surface for List Parameters by Class.
          operations:
            - method: GET
              name: listParametersByClass
              description: List Parameters by Class
              call: aqs-lists.listParametersByClass
              with:
                email: rest.email
                key: rest.key
                pc: rest.pc
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/list/pqaos
          name: list-pqaos
          description: REST surface for List Primary Quality Assurance Organizations.
          operations:
            - method: GET
              name: listPqaos
              description: List Primary Quality Assurance Organizations
              call: aqs-lists.listPqaos
              with:
                email: rest.email
                key: rest.key
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/list/mas
          name: list-mas
          description: REST surface for List Monitoring Agencies.
          operations:
            - method: GET
              name: listMas
              description: List Monitoring Agencies
              call: aqs-lists.listMas
              with:
                email: rest.email
                key: rest.key
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      namespace: aqs-lists-mcp
      port: 9090
      transport: http
      description: MCP adapter for EPA Air Quality System (AQS) API — Lists. One tool per consumed operation, routed inline through this capability's consumes block.
      tools:
        - name: list-states
          description: List States
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listStates
          with:
            email: tools.email
            key: tools.key
          outputParameters:
            - type: object
              mapping: $.
        - name: list-counties-state
          description: List Counties by State
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listCountiesByState
          with:
            email: tools.email
            key: tools.key
            state: tools.state
          outputParameters:
            - type: object
              mapping: $.
        - name: list-sites-county
          description: List Sites by County
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listSitesByCounty
          with:
            email: tools.email
            key: tools.key
            state: tools.state
            county: tools.county
          outputParameters:
            - type: object
              mapping: $.
        - name: list-core-based-statistical-areas
          description: List Core Based Statistical Areas
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listCbsas
          with:
            email: tools.email
            key: tools.key
          outputParameters:
            - type: object
              mapping: $.
        - name: list-parameter-classes
          description: List Parameter Classes
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listClasses
          with:
            email: tools.email
            key: tools.key
          outputParameters:
            - type: object
              mapping: $.
        - name: list-parameters-class
          description: List Parameters by Class
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listParametersByClass
          with:
            email: tools.email
            key: tools.key
            pc: tools.pc
          outputParameters:
            - type: object
              mapping: $.
        - name: list-primary-quality-assurance-organizations
          description: List Primary Quality Assurance Organizations
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listPqaos
          with:
            email: tools.email
            key: tools.key
          outputParameters:
            - type: object
              mapping: $.
        - name: list-monitoring-agencies
          description: List Monitoring Agencies
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: aqs-lists.listMas
          with:
            email: tools.email
            key: tools.key
          outputParameters:
            - type: object
              mapping: $.