openapi: 3.2.0
info:
  title: Ginnie Mae Content Discovery API
  version: 1.0.0
  summary: The public, unauthenticated JSON:API 1.0 content surface behind ginniemae.gov.
  description: Ginnie Mae serves its public website (www.ginniemae.gov) as an Angular single-page application against a Drupal 10 back end, and that back end exposes a **public, unauthenticated JSON:API 1.0 surface at `https://www.ginniemae.gov/api/v1/`** plus a set of Views REST exports and RFC 9264 linkset documents.
  contact:
    name: Ginnie Mae
    url: https://www.ginniemae.gov/contact-us
  license:
    name: U.S. Government Work (17 U.S.C. § 105)
    url: https://www.ginniemae.gov/site-policies/site-policies/disclaimer
servers:
- url: https://www.ginniemae.gov
  description: Production
tags:
- name: Discovery
paths:
  /api/v1/:
    get:
      operationId: getJsonApiEntrypoint
      summary: JSON:API entrypoint
      description: Returns the JSON:API 1.0 entrypoint document. Its links member enumerates every resource type the site exposes, keyed "--".
      tags:
      - Discovery
      responses:
        '200':
          description: JSON:API entrypoint document.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/JsonApiEntrypoint'
  /system/menu/{menu}/linkset:
    get:
      operationId: getMenuLinkset
      summary: Get a site menu as an RFC 9264 linkset
      description: Returns the named navigation menu as an RFC 9264 `application/linkset+json` document. Verified live 2026-09-12 for `main` and `footer`; the SPA also reads `disclosure-plus-download-data` and `disclosure-plus-resources`.
      tags:
      - Discovery
      parameters:
      - name: menu
        in: path
        required: true
        description: Menu machine name.
        schema:
          type: string
          examples:
          - main
          - footer
          - disclosure-plus-download-data
          - disclosure-plus-resources
      responses:
        '200':
          description: A linkset document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Linkset'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    JsonApiError:
      type: object
      properties:
        title:
          type: string
          examples:
          - Bad Request
        status:
          type: string
          examples:
          - '400'
        detail:
          type: string
          examples:
          - Invalid nested filtering. The field `nope`, given in the path `nope`, does not exist.
        links:
          type: object
          properties:
            via:
              type: object
              properties:
                href:
                  type: string
                  format: uri
            info:
              type: object
              properties:
                href:
                  type: string
                  format: uri
    JsonApiEntrypoint:
      type: object
      description: JSON:API 1.0 entrypoint document.
      properties:
        jsonapi:
          $ref: '#/components/schemas/JsonApiVersion'
        data:
          type: array
          items:
            type: object
        links:
          type: object
          description: One member per exposed resource type, keyed "<entity_type>--<bundle>".
          additionalProperties:
            type: object
            properties:
              href:
                type: string
                format: uri
    JsonApiErrorDocument:
      type: object
      required:
      - errors
      properties:
        jsonapi:
          $ref: '#/components/schemas/JsonApiVersion'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiError'
    Linkset:
      type: object
      description: RFC 9264 linkset document.
      properties:
        linkset:
          type: array
          items:
            type: object
            properties:
              anchor:
                type: string
              item:
                type: array
                items:
                  type: object
                  properties:
                    href:
                      type: string
                    title:
                      type: string
                    hierarchy:
                      type: array
                      items:
                        type: string
                    machine-name:
                      type: array
                      items:
                        type: string
                    is-hidden:
                      type: array
                      items:
                        type: string
                    isProtected:
                      type: boolean
    JsonApiVersion:
      type: object
      properties:
        version:
          type: string
          examples:
          - '1.0'
        meta:
          type: object
          additionalProperties: true
  responses:
    NotFound:
      description: 'No such resource. NOTE: an unknown resource TYPE under /api/v1 is answered by Drupal with an HTML 404 page rather than a JSON:API error document (observed 2026-09-12).'
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorDocument'
        text/html:
          schema:
            type: string
externalDocs:
  description: JSON:API 1.0 specification (the contract this surface conforms to)
  url: https://jsonapi.org/format/1.0/
x-generated-from:
  method: generated
  by: API Evangelist enrichment pipeline (local-v3)
  generated: '2026-09-12'
  sources:
  - https://www.ginniemae.gov/api/v1/ (JSON:API 1.0 entrypoint document, HTTP 200, 120 resource types)
  - https://www.ginniemae.gov/assets/config/config.prod.json (the SPA runtime configuration that names the API base)
  - https://bulk.ginniemae.gov/assets/config/config.prod.json
  - live anonymous GET probes of every path described, 2026-09-12
  not_published_by_provider: true
  verification: Every path carries a 2026-09-12 anonymous HTTP 200. Query parameters are either JSON:API 1.0 members verified against the live surface (page[limit], page[offset], sort, filter, fields) or exposed-filter names the endpoint declares about itself in its own response `filters` member.
  caveat: 'robots.txt on www.ginniemae.gov carries "Disallow: /api/" for crawlers. The surface is not authenticated and not rate-limited in any advertised way, but it is also not an advertised developer product.'