openapi: 3.1.0
info:
  title: FRED API - Federal Reserve Economic Data
  version: 1.0.0
  description: >-
    The Federal Reserve Economic Data (FRED) API provided by the Federal Reserve
    Bank of St. Louis offers programmatic access to over 800,000 economic time
    series including reserve requirement data, monetary base measures, H.6 Money
    Stock Measures, and historical aggregate reserve data from the discontinued
    H.3 release. The API uses API key authentication and returns data in JSON,
    XML, or other formats.
  contact:
    name: Federal Reserve Bank of St. Louis
    url: https://fred.stlouisfed.org/
  license:
    name: Public Domain
    url: https://fred.stlouisfed.org/legal/
servers:
  - url: https://api.stlouisfed.org/fred
    description: FRED API Production
security:
  - apiKeyQuery: []
tags:
  - name: Series
    description: Search and retrieve economic data time series.
  - name: Observations
    description: Retrieve data observations for a series.
  - name: Categories
    description: Browse FRED data categories.
  - name: Releases
    description: Access Federal Reserve statistical releases.
  - name: Tags
    description: Search series by tags.
paths:
  /series:
    get:
      tags:
        - Series
      summary: Get Economic Series
      description: >-
        Retrieve information for a single FRED economic data series.
        Key reserve-related series include: RESBALNS (reserve balances),
        BOGMBASE (monetary base), WRESBAL (weekly reserve balances).
      operationId: getSeries
      parameters:
        - name: series_id
          in: query
          required: true
          schema:
            type: string
          description: The FRED series ID (e.g., RESBALNS, BOGMBASE).
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: Series metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /series/observations:
    get:
      tags:
        - Observations
      summary: Get Series Observations
      description: >-
        Retrieve observations (data values) for an economic data series.
        Supports date filtering, sorting, and multiple output formats.
      operationId: getSeriesObservations
      parameters:
        - name: series_id
          in: query
          required: true
          schema:
            type: string
          description: The FRED series ID.
        - name: observation_start
          in: query
          schema:
            type: string
            format: date
          description: Start date for observations (YYYY-MM-DD).
        - name: observation_end
          in: query
          schema:
            type: string
            format: date
          description: End date for observations (YYYY-MM-DD).
        - name: sort_order
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: asc
          description: Sort order for observations.
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 100000
            default: 100000
          description: Maximum number of observations to return.
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination.
        - name: units
          in: query
          schema:
            type: string
            enum: [lin, chg, ch1, pch, pc1, pca, cch, cca, log]
          description: Units transformation for the data.
        - name: frequency
          in: query
          schema:
            type: string
            enum: [d, w, bw, m, q, sa, a, wef, weth, wew, wetu, wem, wesu, wesa, bwew, bwem]
          description: Frequency of the data.
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: Series observations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /series/search:
    get:
      tags:
        - Series
      summary: Search Series
      description: Search for FRED economic data series by keyword.
      operationId: searchSeries
      parameters:
        - name: search_text
          in: query
          required: true
          schema:
            type: string
          description: Search keywords (e.g., "reserve requirements", "monetary base").
        - name: search_type
          in: query
          schema:
            type: string
            enum: [full_text, series_id]
            default: full_text
          description: Type of search to perform.
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 1000
            default: 1000
          description: Maximum number of results.
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination.
        - name: order_by
          in: query
          schema:
            type: string
            enum: [search_rank, series_id, title, units, frequency, seasonal_adjustment, realtime_start, realtime_end, last_updated, observation_start, observation_end, popularity, group_popularity]
          description: Field to order results by.
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesSearchResponse'
  /category:
    get:
      tags:
        - Categories
      summary: Get Category
      description: Retrieve a FRED category by ID.
      operationId: getCategory
      parameters:
        - name: category_id
          in: query
          required: true
          schema:
            type: integer
          description: The category ID (e.g., 32217 for Reserve Requirements).
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: Category metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
  /category/series:
    get:
      tags:
        - Categories
      summary: Get Category Series
      description: Retrieve all series for a FRED category.
      operationId: getCategorySeries
      parameters:
        - name: category_id
          in: query
          required: true
          schema:
            type: integer
          description: The category ID.
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 1000
            default: 1000
          description: Maximum number of results.
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination.
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: Series in the category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesSearchResponse'
  /releases:
    get:
      tags:
        - Releases
      summary: List Releases
      description: Retrieve all Federal Reserve statistical releases.
      operationId: listReleases
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 1000
            default: 1000
          description: Maximum number of results.
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination.
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: List of releases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleasesResponse'
  /release:
    get:
      tags:
        - Releases
      summary: Get Release
      description: Retrieve a specific Federal Reserve statistical release.
      operationId: getRelease
      parameters:
        - name: release_id
          in: query
          required: true
          schema:
            type: integer
          description: The release ID.
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: Release metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseResponse'
  /release/series:
    get:
      tags:
        - Releases
      summary: Get Release Series
      description: Retrieve all series for a statistical release.
      operationId: getReleaseSeries
      parameters:
        - name: release_id
          in: query
          required: true
          schema:
            type: integer
          description: The release ID.
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 1000
            default: 1000
          description: Maximum number of results.
        - $ref: '#/components/parameters/apiKeyParam'
        - $ref: '#/components/parameters/fileTypeParam'
      responses:
        '200':
          description: Series for the release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesSearchResponse'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: FRED API key obtained from api.stlouisfed.org/api/key.html
  parameters:
    apiKeyParam:
      name: api_key
      in: query
      required: true
      schema:
        type: string
      description: Your FRED API key.
    fileTypeParam:
      name: file_type
      in: query
      schema:
        type: string
        enum: [json, xml]
        default: json
      description: Output file format.
  responses:
    BadRequest:
      description: Bad request - invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Series:
      type: object
      properties:
        id:
          type: string
          description: Series ID (e.g., RESBALNS).
        realtime_start:
          type: string
          format: date
          description: Realtime start date.
        realtime_end:
          type: string
          format: date
          description: Realtime end date.
        title:
          type: string
          description: Series title.
        observation_start:
          type: string
          format: date
          description: Start date of available observations.
        observation_end:
          type: string
          format: date
          description: End date of available observations.
        frequency:
          type: string
          description: Data frequency (e.g., Weekly, Monthly).
        frequency_short:
          type: string
          description: Short frequency code.
        units:
          type: string
          description: Data units (e.g., Millions of Dollars).
        units_short:
          type: string
          description: Short units description.
        seasonal_adjustment:
          type: string
          description: Seasonal adjustment status.
        seasonal_adjustment_short:
          type: string
          description: Short seasonal adjustment code.
        last_updated:
          type: string
          format: date-time
          description: Last update timestamp.
        popularity:
          type: integer
          description: Popularity score (0-100).
        notes:
          type: string
          description: Series notes and descriptions.
    SeriesResponse:
      type: object
      properties:
        realtime_start:
          type: string
        realtime_end:
          type: string
        seriess:
          type: array
          items:
            $ref: '#/components/schemas/Series'
    Observation:
      type: object
      properties:
        realtime_start:
          type: string
          format: date
        realtime_end:
          type: string
          format: date
        date:
          type: string
          format: date
          description: Observation date.
        value:
          type: string
          description: Observation value (period value or "." for missing).
    ObservationsResponse:
      type: object
      properties:
        realtime_start:
          type: string
        realtime_end:
          type: string
        observation_start:
          type: string
        observation_end:
          type: string
        units:
          type: string
        output_type:
          type: integer
        file_type:
          type: string
        order_by:
          type: string
        sort_order:
          type: string
        count:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        observations:
          type: array
          items:
            $ref: '#/components/schemas/Observation'
    SeriesSearchResponse:
      type: object
      properties:
        realtime_start:
          type: string
        realtime_end:
          type: string
        order_by:
          type: string
        sort_order:
          type: string
        count:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        seriess:
          type: array
          items:
            $ref: '#/components/schemas/Series'
    Category:
      type: object
      properties:
        id:
          type: integer
          description: Category ID.
        name:
          type: string
          description: Category name.
        parent_id:
          type: integer
          description: Parent category ID.
    CategoryResponse:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
    Release:
      type: object
      properties:
        id:
          type: integer
        realtime_start:
          type: string
        realtime_end:
          type: string
        name:
          type: string
          description: Release name.
        press_release:
          type: boolean
          description: Whether this is a press release.
        link:
          type: string
          format: uri
          description: Link to the release page.
    ReleasesResponse:
      type: object
      properties:
        realtime_start:
          type: string
        realtime_end:
          type: string
        order_by:
          type: string
        sort_order:
          type: string
        count:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        releases:
          type: array
          items:
            $ref: '#/components/schemas/Release'
    ReleaseResponse:
      type: object
      properties:
        releases:
          type: array
          items:
            $ref: '#/components/schemas/Release'
    ErrorResponse:
      type: object
      properties:
        error_code:
          type: integer
          description: FRED error code.
        error_message:
          type: string
          description: Human-readable error message.