CFPB HMDA Institutions API — Institutions

naftiko: 1.0.0-alpha2
info:
  label: CFPB HMDA Institutions API — Institutions
  description: 'CFPB HMDA Institutions API — Institutions. 2 operations. Lead operation: List all institutions that filed
    HMDA data for a year. Self-contained Naftiko capability covering one Consumer Financial Protection Bureau business surface.'
  tags:
  - Consumer Financial Protection Bureau
  - Institutions
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    CONSUMER_FINANCIAL_PROTECTION_BUREAU_API_KEY: CONSUMER_FINANCIAL_PROTECTION_BUREAU_API_KEY
capability:
  consumes:
  - type: http
    namespace: cfpb-hmda-institutions-institutions
    baseUri: https://ffiec.cfpb.gov/v2
    description: CFPB HMDA Institutions API — Institutions business capability. Self-contained, no shared references.
    resources:
    - name: public-filers-year
      path: /public/filers/{year}
      operations:
      - name: listinstitutionsbyyear
        method: GET
        description: List all institutions that filed HMDA data for a year
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: year
          in: path
          type: integer
          required: true
    - name: public-institutions-year-lei
      path: /public/institutions/{year}/{lei}
      operations:
      - name: getinstitution
        method: GET
        description: Get a single institution by year and LEI
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: year
          in: path
          type: integer
          required: true
        - name: lei
          in: path
          type: string
          required: true
  exposes:
  - type: rest
    namespace: cfpb-hmda-institutions-institutions-rest
    port: 8080
    description: REST adapter for CFPB HMDA Institutions API — Institutions. One Spectral-compliant resource per consumed
      operation, prefixed with /v1.
    resources:
    - path: /v1/public/filers/{year}
      name: public-filers-year
      description: REST surface for public-filers-year.
      operations:
      - method: GET
        name: listinstitutionsbyyear
        description: List all institutions that filed HMDA data for a year
        call: cfpb-hmda-institutions-institutions.listinstitutionsbyyear
        with:
          year: rest.year
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/public/institutions/{year}/{lei}
      name: public-institutions-year-lei
      description: REST surface for public-institutions-year-lei.
      operations:
      - method: GET
        name: getinstitution
        description: Get a single institution by year and LEI
        call: cfpb-hmda-institutions-institutions.getinstitution
        with:
          year: rest.year
          lei: rest.lei
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: cfpb-hmda-institutions-institutions-mcp
    port: 9090
    transport: http
    description: MCP adapter for CFPB HMDA Institutions API — Institutions. One tool per consumed operation, routed inline
      through this capability's consumes block.
    tools:
    - name: list-all-institutions-that-filed
      description: List all institutions that filed HMDA data for a year
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: cfpb-hmda-institutions-institutions.listinstitutionsbyyear
      with:
        year: tools.year
      outputParameters:
      - type: object
        mapping: $.
    - name: get-single-institution-year-and
      description: Get a single institution by year and LEI
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: cfpb-hmda-institutions-institutions.getinstitution
      with:
        year: tools.year
        lei: tools.lei
      outputParameters:
      - type: object
        mapping: $.