# HAYAA Athletics Public Directory API

Base URL: https://hayaaeagles.com/api/v1

The HAYAA Athletics hub is the public directory for HAYAA program websites. It exposes discovery metadata for agents and apps, a combined public schedule, and links to the individual Basketball, Baseball/Softball, Football, and Cheer/Pom web properties.

## Discovery

- API catalog: `/.well-known/api-catalog`
- OpenAPI: `/openapi.json`
- API health: `/api/v1/health`
- OAuth authorization metadata: `/.well-known/oauth-authorization-server`
- OAuth protected resource metadata: `/.well-known/oauth-protected-resource`
- Agent authorization guide: `/auth.md`
- MCP server card: `/.well-known/mcp/server-card.json`
- Agent skills: `/.well-known/agent-skills/index.json`

## Hub Resources

- `/api/v1/health` - confirms the hub discovery API is available
- `/api/v1/calendar` - combines games, practices, and special events from the Basketball, Baseball/Softball, and Football databases
- `/` - human-facing HAYAA Athletics landing page
- `/llms.txt` - concise machine-readable site summary
- `/docs/api` - this public API documentation

## Combined Calendar

`GET /api/v1/calendar`

The calendar endpoint is public and read-only. Its JSON response contains an `events` array compatible with FullCalendar and a `meta` object describing the selected range and source status.

Query parameters:

- `start` - inclusive date in `YYYY-MM-DD` format; defaults to the first day of the current month
- `end` - exclusive date in `YYYY-MM-DD` format; defaults to one month after `start`
- `sports` - comma-separated subset of `basketball,baseball,football`
- `types` - comma-separated subset of `game,practice,special`

Date ranges are limited to 370 days. If one league source is temporarily unavailable, the response remains successful when another source is available and reports `meta.partial: true`.

## Program Sites

- Basketball: https://hayaabasketball.com/
- Baseball and Softball: https://hayaabaseball.com/
- Football: https://hayaafootball.com/
- Cheer and Pom: https://sites.google.com/view/hayaacheerpom/home

For registration, schedules, teams, FAQs, documents, and contact workflows, use the sport-specific public site and API metadata.