# Earnings API

> Earnings API provides structured JSON endpoints for earnings calendars, company earnings, post-earnings reactions, market movers, macro events, company profiles, and market schedule utilities.

## Agent Entry Points

- [Agent guide](https://www.earningsapi.com/docs/agent.md): compact rules for auth, endpoint selection, parameters, examples, and common mistakes.
- [OpenAPI contract](https://www.earningsapi.com/openapi.json): machine-readable HTTP API contract with stable operation IDs.
- [API catalog](https://www.earningsapi.com/api-catalog.json): lightweight endpoint and workflow metadata for agent tool selection.
- [Human docs](https://www.earningsapi.com/docs): Explorer, Dev, and Agent mode documentation.

## Core Endpoints

- [Earnings Calendar](https://www.earningsapi.com/docs/calendar-earnings): use for earnings by date.
- [Company Earnings](https://www.earningsapi.com/docs/earnings): use for earnings history or upcoming dates by symbol.
- [Earnings Reactions](https://www.earningsapi.com/docs/earnings-reactions): use for EPS/revenue beat or miss and post-event price/volume reaction.
- [Earnings Movers](https://www.earningsapi.com/docs/earnings-movers): use for first-trading-day post-earnings movers.
- [Economic Calendar](https://www.earningsapi.com/docs/calendar-economic): use for macro events.
- [Profile](https://www.earningsapi.com/docs/profile): use to enrich symbols with sector, industry, type, country, shares, price, and market cap.
- [Market Status](https://www.earningsapi.com/docs/market-status): use before scheduled jobs that depend on market session state.
- [Market Holidays](https://www.earningsapi.com/docs/market-holidays): use for holiday-aware scheduling.

## Critical Rules

- Base URL: `https://api.earningsapi.com`
- Authentication: append `apikey=YOUR_API_KEY` as a query parameter.
- If the URL already contains query parameters, append the API key with `&apikey=...`; otherwise use `?apikey=...`.
- Calendar dates accept `YYYY-MM-DD`, `today`, `yesterday`, and `tomorrow`; relative dates are resolved in New York time.
- Use calendar endpoints for date-based questions. Use symbol endpoints for one company or a watchlist loop.