{
  "openapi": "3.1.0",
  "info": {
    "title": "Earnings API",
    "version": "1.0.0",
    "description": "Structured JSON endpoints for earnings calendars, company earnings, reactions, movers, macro events, profiles, and market schedule utilities."
  },
  "servers": [
    {
      "url": "https://api.earningsapi.com"
    }
  ],
  "security": [
    {
      "ApiKeyQuery": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "apikey"
      }
    },
    "schemas": {
      "GenericJson": {
        "description": "JSON response. See endpoint documentation for field-level examples.",
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": true
          },
          {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        ]
      }
    },
    "parameters": {
      "Date": {
        "name": "date",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Date in YYYY-MM-DD format, or today, yesterday, or tomorrow when supported."
      },
      "Symbol": {
        "name": "symbol",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Stock ticker symbol such as AAPL."
      },
      "SymbolPath": {
        "name": "symbol",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Stock ticker symbol in the URL path."
      },
      "UsMajor": {
        "name": "usmajor",
        "in": "query",
        "required": false,
        "schema": {
          "type": "boolean"
        },
        "description": "When true, returns U.S. major indicators only."
      }
    },
    "responses": {
      "Ok": {
        "description": "Successful JSON response.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenericJson"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/calendar/earnings": {
      "get": {
        "operationId": "getEarningsCalendar",
        "summary": "Get earnings calendar by date",
        "description": "Returns earnings schedules for a specific date. Use this for date-based calendar backfills, daily sync, and all companies reporting on a day.",
        "tags": ["Calendar"],
        "parameters": [
          {
            "$ref": "#/components/parameters/Date"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/calendar/economic": {
      "get": {
        "operationId": "getEconomicCalendar",
        "summary": "Get economic calendar by date",
        "description": "Returns economic events for a date. Use usmajor=true for U.S. major indicators only.",
        "tags": ["Calendar"],
        "parameters": [
          {
            "$ref": "#/components/parameters/Date"
          },
          {
            "$ref": "#/components/parameters/UsMajor"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/calendar/ipo": {
      "get": {
        "operationId": "getUpcomingIpos",
        "summary": "Get upcoming IPO calendar",
        "description": "Returns upcoming IPO events only.",
        "tags": ["Calendar"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/calendar/dividends": {
      "get": {
        "operationId": "getUpcomingDividends",
        "summary": "Get upcoming dividends calendar",
        "description": "Returns upcoming dividend events only.",
        "tags": ["Calendar"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/earnings": {
      "get": {
        "operationId": "getCompanyEarnings",
        "summary": "Get company earnings by symbol",
        "description": "Returns historical and upcoming earnings data for a specific symbol. Use this for one company or watchlist loops.",
        "tags": ["Earnings"],
        "parameters": [
          {
            "$ref": "#/components/parameters/Symbol"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/earnings-reactions": {
      "get": {
        "operationId": "getEarningsReactions",
        "summary": "Get earnings reactions by symbol",
        "description": "Returns EPS/revenue surprise metrics and post-earnings price and volume reactions for a symbol.",
        "tags": ["Earnings"],
        "parameters": [
          {
            "$ref": "#/components/parameters/Symbol"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/earnings-movers": {
      "get": {
        "operationId": "getEarningsMovers",
        "summary": "Get earnings movers by date",
        "description": "Returns first-trading-day post-earnings movers filtered to moves of at least 5 percent up or down.",
        "tags": ["Earnings"],
        "parameters": [
          {
            "$ref": "#/components/parameters/Date"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/unusual-volume": {
      "get": {
        "operationId": "getUnusualVolume",
        "summary": "Get unusual volume movers",
        "description": "Returns stocks with unusually high trading volume split into positive and negative price movers.",
        "tags": ["Market"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/profile/{symbol}": {
      "get": {
        "operationId": "getCompanyProfile",
        "summary": "Get company profile by symbol",
        "description": "Returns company profile fields such as sector, industry, country, type, price, outstanding shares, and market cap.",
        "tags": ["Company"],
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/market-status": {
      "get": {
        "operationId": "getMarketStatus",
        "summary": "Get current market status",
        "description": "Returns current U.S. market session state plus today, tomorrow, and next-open signals.",
        "tags": ["Market"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    },
    "/v1/market-holidays": {
      "get": {
        "operationId": "getMarketHolidays",
        "summary": "Get market holiday schedule",
        "description": "Returns the official market holiday schedule, including early close days.",
        "tags": ["Market"],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          }
        }
      }
    }
  }
}