openapi: 3.0.3
info:
  title: OpenFEMA Catalog API
  description: OpenFEMA is FEMA's open data platform. It exposes a read-only RESTful API over individually versioned dataset endpoints (Entities) using OData-style query string parameters. No API key, subscription, or authentication is required. Responses default to JSON; CSV and Parquet are also available via $format. This document models the confirmed public dataset endpoints covering disaster declarations, public assistance, hazard mitigation, NFIP, IPAWS alerts, web disaster summaries, and the self-describing dataset/field catalog. Field lists shown here are representative, not exhaustive - the full data dictionary for any dataset/version is available live from the OpenFemaDataSetFields endpoint modeled below.
  termsOfService: https://www.fema.gov/about/website-information/privacy-policy
  contact:
    name: OpenFEMA
    email: OpenFEMA@fema.dhs.gov
    url: https://www.fema.gov/about/openfema
  license:
    name: Public Domain (U.S. Government Work)
    url: https://www.usa.gov/government-works
  version: '2.1'
servers:
- url: https://www.fema.gov/api/open
  description: OpenFEMA production API (dataset version is part of each path)
tags:
- name: Catalog
  description: Self-describing metadata - dataset list and data dictionaries.
paths:
  /v1/OpenFemaDataSets:
    get:
      operationId: listOpenFemaDataSets
      tags:
      - Catalog
      summary: List the OpenFEMA dataset catalog
      description: Returns metadata describing every dataset and version published on OpenFEMA - name, version, description, last-refresh date, record count, and whether an API endpoint exists for it.
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/Metadata'
      responses:
        '200':
          description: A page of dataset catalog records.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OpenFemaEnvelope'
                - type: object
                  properties:
                    OpenFemaDataSets:
                      type: array
                      items:
                        $ref: '#/components/schemas/OpenFemaDataSet'
        '400':
          $ref: '#/components/responses/BadFilter'
  /v1/OpenFemaDataSetFields:
    get:
      operationId: listOpenFemaDataSetFields
      tags:
      - Catalog
      summary: List the data dictionary for a dataset/version
      description: Returns the field-level data dictionary (name, title, type, description) for a given dataset name and version. Typically called with a $filter such as `openFemaDataSet eq 'DisasterDeclarationsSummaries' and datasetVersion eq 2`.
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/Metadata'
      responses:
        '200':
          description: A page of data dictionary field records.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OpenFemaEnvelope'
                - type: object
                  properties:
                    OpenFemaDataSetFields:
                      type: array
                      items:
                        $ref: '#/components/schemas/OpenFemaDataSetField'
        '400':
          $ref: '#/components/responses/BadFilter'
components:
  parameters:
    Top:
      name: $top
      in: query
      description: Number of records to return. Defaults to 1000 when omitted; maximum of 10000 per call.
      schema:
        type: integer
        default: 1000
        maximum: 10000
        minimum: 1
    Format:
      name: $format
      in: query
      description: Response format. Defaults to json when omitted.
      schema:
        type: string
        enum:
        - json
        - csv
        - parquet
        - jsona
        - xlsx
        default: json
    Filter:
      name: $filter
      in: query
      description: OData-style filter expression, e.g. state eq 'FL' and fyDeclared eq 2024. The parser is strict about spacing, quoting, and capitalization; string literals must be single-quoted.
      schema:
        type: string
    Metadata:
      name: $metadata
      in: query
      description: When false, suppresses the metadata envelope object and returns only the data array. Accepts true/false (the legacy on/off values are deprecated).
      schema:
        type: boolean
        default: true
    Select:
      name: $select
      in: query
      description: Comma-separated list of fields to include in the response.
      schema:
        type: string
    OrderBy:
      name: $orderby
      in: query
      description: Field name to sort results by.
      schema:
        type: string
    Skip:
      name: $skip
      in: query
      description: Number of records to skip, used to page through results beyond $top.
      schema:
        type: integer
        default: 0
        minimum: 0
  schemas:
    OpenFemaDataSet:
      type: object
      description: One catalog entry describing a dataset and version.
      properties:
        name:
          type: string
        title:
          type: string
        version:
          type: integer
        description:
          type: string
        webService:
          type: string
          description: API endpoint path, when the dataset is exposed via the API.
        lastDataSetRefresh:
          type: string
          format: date-time
        recordCount:
          type: integer
        dataDictionary:
          type: string
    OpenFemaEnvelope:
      type: object
      description: Every OpenFEMA response wraps the requested dataset array in a metadata object (unless $metadata=false is passed).
      properties:
        metadata:
          type: object
          properties:
            skip:
              type: integer
            filter:
              type: string
            orderby:
              type: string
            select:
              type: string
            rundate:
              type: string
              format: date-time
            count:
              type: integer
              description: Total matching records, present only when $count=true.
            entityname:
              type: string
            version:
              type: integer
            url:
              type: string
    OpenFemaDataSetField:
      type: object
      description: One data-dictionary field entry for a dataset/version.
      properties:
        openFemaDataSet:
          type: string
        datasetVersion:
          type: integer
        name:
          type: string
        title:
          type: string
        type:
          type: string
        description:
          type: string
  responses:
    BadFilter:
      description: Malformed OData query string (commonly a $filter with incorrect quoting, spacing, or an unknown field name).
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string