# generated: 2026-09-12
# method: generated
# source: openapi/ginnie-mae-content-api-openapi.yml
overlay: 1.0.0
info:
  title: API Evangelist enhancements — Ginnie Mae Content API
  version: 1.0.0
extends: ./../openapi/ginnie-mae-content-api-openapi.yml
x-provenance:
  generated: '2026-09-12'
  method: generated
  by: API Evangelist enrichment pipeline (local-v3)
  note: >-
    Ginnie Mae publishes no OpenAPI, so the document this overlay extends is itself
    generated by API Evangelist from the provider's JSON:API entrypoint and live
    probes. This overlay records the annotations we add on top of it — the
    provenance banner, the consumption warnings that are not derivable from the wire
    format, and the cross-links into this repository's other artifacts — so the
    generated description and our editorial layer stay separable.
actions:
  - target: $.info
    description: Stamp the description with an explicit not-published-by-the-provider banner.
    update:
      x-api-evangelist:
        published_by_provider: false
        generated_by: API Evangelist
        generated: '2026-09-12'
        verification: every path fetched anonymously, HTTP 200, 2026-09-12
        profile: https://apis.io/provider/ginnie-mae
  - target: $
    description: >-
      Attach the consumption facts an agent needs that the wire format does not carry —
      the flattened-attributes deviation from vanilla JSON:API, the HTML-404
      inconsistency, the absent rate-limit signal, and the robots.txt directive.
    update:
      x-consumption-notes:
        flattened_attributes: >-
          JSON:API Extras field enhancement is enabled. Resource attributes are flattened
          onto the resource object; there is no data.attributes member. A vanilla JSON:API
          client will read every record as empty.
        html_404: >-
          A request for an unknown resource TYPE returns Drupal's HTML error page, not a
          JSON:API error document. Guard the parse.
        no_rate_limit_signal: >-
          No RateLimit-*, X-RateLimit-* or Retry-After header is returned, and no limit is
          published. A client cannot back off before being cut off.
        robots_disallow: 'https://www.ginniemae.gov/robots.txt carries "Disallow: /api/".'
        read_only: >-
          Only GET is described. No write was attempted against a live U.S. government
          system, so no write semantics are asserted.
  - target: $
    description: Cross-link the derived artifacts that describe this contract's runtime semantics.
    update:
      x-artifacts:
        conventions: ../conventions/ginnie-mae-conventions.yml
        errors: ../errors/ginnie-mae-problem-types.yml
        data_model: ../data-model/ginnie-mae-data-model.yml
        authentication: ../authentication/ginnie-mae-authentication.yml
        conformance: ../conformance/ginnie-mae-conformance.yml
        lifecycle: ../lifecycle/ginnie-mae-lifecycle.yml
        rate_limits: ../rate-limits/ginnie-mae-rate-limits.yml
        skills: ../skills/_index.yml
        discovery_document: ../discovery/ginnie-mae-jsonapi-index.json
  - target: $.paths['/api/v1/search/results'].get
    description: Flag the site-search export as the recommended entry point for an agent.
    update:
      x-recommended-entry-point: true
      x-observed:
        total_results: 10798
        observed: '2026-09-12'
  - target: $.paths['/api/v1/node/data_file_types'].get
    description: >-
      Flag the bridge between the content estate and the MBS disclosure product, which is
      not obvious from the resource type name.
    update:
      x-domain-significance: >-
        Each row resolves through field_file_layout to a media--disclosure_data_file, the
        published record-layout document for one Ginnie Mae bulk disclosure file. This is
        the only machine-navigable path from the website into the disclosure product.