Documentation

LeagueSolver has a single endpoint: POST /v1/schedules/league. This page covers everything you need to call it.

1. Get an API key

Use the signup form on the home page, or call the key-issuance endpoint directly:

curl -X POST https://leaguesolver-api.fly.dev/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

2. Generate a schedule

Send your teams, venues, and constraints as JSON, with your key as a Bearer token:

curl -X POST https://leaguesolver-api.fly.dev/v1/schedules/league \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "teams": [
    {
      "id": "tigers",
      "home_venue": "venue_a"
    },
    {
      "id": "lions",
      "home_venue": "venue_b"
    },
    {
      "id": "hawks",
      "home_venue": "venue_a"
    }
  ],
  "venues": [
    {
      "id": "venue_a",
      "available_slots": [
        "2026-08-01T10:00",
        "2026-08-01T14:00",
        "2026-08-08T10:00"
      ]
    },
    {
      "id": "venue_b",
      "available_slots": [
        "2026-08-02T10:00",
        "2026-08-09T10:00"
      ]
    }
  ],
  "format": "round_robin",
  "rounds": 1,
  "constraints": {
    "max_games_per_team_per_week": 1,
    "min_rest_days": 5,
    "balance_home_away": true
  },
  "objective": "minimize_schedule_length"
}'

3. Read the response

status is one of optimal, feasible, or infeasible. On success, matches lists every game (home, away, venue, kickoff time) and fairness_report summarizes home/away balance and rest days per team.

When a schedule truly isn't possible, you never get a bare error. status is infeasible and diagnosis explains exactly which constraint is conflicting, so you know what to fix:

{
  "status": "infeasible",
  "matches": [],
  "fairness_report": null,
  "solve_time_ms": 842,
  "diagnosis": "venue_b does not have enough available slots. At least 4 slots are required for its 2 home matches across 2 rounds, but only 2 were provided.",
  "warnings": []
}

Plans, quotas, and limits

Every plan shares the same rate limit; solves/month and max teams per request scale with the plan.

Plan	Solves/month	Max teams/request	Rate limit
Free	50	8	10 req/min
Starter	1,000	32	10 req/min
Pro	10,000	32	10 req/min

Full API reference

The complete OpenAPI schema is generated directly from the API and always up to date: