openapi: 3.1.0
info:
  title: FRED API - Federal Reserve Economic Data Categories Series API
  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.
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/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'
components:
  schemas:
    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'
    SeriesResponse:
      type: object
      properties:
        realtime_start:
          type: string
        realtime_end:
          type: string
        seriess:
          type: array
          items:
            $ref: '#/components/schemas/Series'
    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.
    ErrorResponse:
      type: object
      properties:
        error_code:
          type: integer
          description: FRED error code.
        error_message:
          type: string
          description: Human-readable error message.
  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'
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: FRED API key obtained from api.stlouisfed.org/api/key.html