openapi: 3.2.0
info:
  title: Ginnie Mae Content FAQ 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: FAQ
paths:
  /api/v1/faq:
    get:
      operationId: listFaqs
      summary: List frequently asked questions
      description: 'Paged FAQ rows (question, answer, modified, reference, category). Verified live 2026-09-12: 433 results.'
      tags:
      - FAQ
      parameters:
      - name: keywords
        in: query
        required: false
        description: Exposed filter `keywords`, self-declared by the endpoint in its own `filters` member.
        schema:
          type: string
      - name: category
        in: query
        required: false
        description: Exposed filter `category`, self-declared by the endpoint in its own `filters` member.
        schema:
          type: string
      - name: subcategory
        in: query
        required: false
        description: Exposed filter `subcategory`, self-declared by the endpoint in its own `filters` member.
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Zero-based page index; the response `pager` member reports `current_page`, `items_per_page`, `total_pages` and `total_results`.
        schema:
          type: integer
          minimum: 0
      - name: items_per_page
        in: query
        required: false
        description: Page size.
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: A paged result envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResults'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/faq/categories:
    get:
      operationId: listFaqCategories
      summary: List FAQ categories
      description: FAQ category vocabulary rows (name, category id).
      tags:
      - FAQ
      parameters:
      - name: page
        in: query
        required: false
        description: Zero-based page index; the response `pager` member reports `current_page`, `items_per_page`, `total_pages` and `total_results`.
        schema:
          type: integer
          minimum: 0
      - name: items_per_page
        in: query
        required: false
        description: Page size.
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: A paged result envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResults'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/faq/subcategories:
    get:
      operationId: listFaqSubcategories
      summary: List FAQ subcategories
      description: FAQ subcategory rows (name, subcategory id, parent_name, parent_category).
      tags:
      - FAQ
      parameters:
      - name: page
        in: query
        required: false
        description: Zero-based page index; the response `pager` member reports `current_page`, `items_per_page`, `total_pages` and `total_results`.
        schema:
          type: integer
          minimum: 0
      - name: items_per_page
        in: query
        required: false
        description: Page size.
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: A bare JSON array of rows.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Malformed query — for example an unknown filter field. Returned as a JSON:API error document.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorDocument'
    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
  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
    JsonApiErrorDocument:
      type: object
      required:
      - errors
      properties:
        jsonapi:
          $ref: '#/components/schemas/JsonApiVersion'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiError'
    PagedResults:
      type: object
      properties:
        filters:
          type: array
          items:
            type: string
          description: The exposed filter names this endpoint accepts — the surface self-documents its own query parameters here.
        pager:
          $ref: '#/components/schemas/Pager'
        results:
          type: array
          items:
            type: object
            additionalProperties: true
    Pager:
      type: object
      properties:
        current_page:
          type: integer
        items_per_page:
          type: integer
        total_pages:
          type: integer
        total_results:
          type: integer
    JsonApiVersion:
      type: object
      properties:
        version:
          type: string
          examples:
          - '1.0'
        meta:
          type: object
          additionalProperties: true
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.'