# Major League Hacking — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and discover hackathons by season, region, country, and date range, including filters for diversity-focused events and real-time listings of upcoming competitions. Find hackathons happening this month, in a specific country, or across any custom date range.

**Category:** Education | **Website:** [mlh.io/](https://mlh.io/) | **Docs:** [parse.bot/marketplace/ba747a40-a590-4835-9c40-17db05128981/mlh-io-api](https://parse.bot/marketplace/ba747a40-a590-4835-9c40-17db05128981/mlh-io-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### Get diversity focused events

Get hackathon events that have diversity focus tags (non-empty underserved_types) for a given MLH season year. Returns events targeting underrepresented groups.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | No | MLH season year (e.g. 2025, 2026). Defaults to current year. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_diversity_focused_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

### Get events by region

Filter hackathon events by geographic region for a given MLH season year. Accepts human-readable region names (mapped to internal codes) or the codes directly. Returns all events (upcoming and past) matching that region.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `region` | string | Yes | Region filter. |
| `year` | integer | No | MLH season year (e.g. 2025, 2026). Defaults to current year. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_events_by_region \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region":"<string>","year":"<integer>"}'
```

### Get events by season

Get all hackathon events (upcoming and past) for a specific MLH season year. Returns the full list of events for that season. Each season spans an academic year (e.g. 2025 covers roughly Aug 2024–Jun 2025). Paginates as a single page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | No | MLH season year (e.g. 2025, 2026). Defaults to current year. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_events_by_season \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

### Get events in date range

Filter hackathon events by date range and optional country code. Returns events whose time span overlaps the specified range. Default range is next 7 days from now.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Two-letter ISO country code filter (e.g. 'US', 'IN', 'CA'). Omitting returns all countries. |
| `end_date` | string | No | End date in ISO format YYYY-MM-DD. Defaults to 7 days after start_date. |
| `start_date` | string | No | Start date in ISO format YYYY-MM-DD. Defaults to today (UTC). |
| `year` | integer | No | MLH season year to search within. Defaults to the start date's year. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_events_in_date_range \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","end_date":"<string>","start_date":"<string>","year":"<integer>"}'
```

### Get events this month

Get hackathon events occurring in the current calendar month. Searches the given season's data and returns events whose start date falls within the current UTC month and year.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | No | MLH season year to search within (e.g. 2025, 2026). Defaults to current year. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_events_this_month \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

### Get past events

Get past (ended) hackathon events for a given MLH season year. Returns only events whose status is ended.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | No | MLH season year (e.g. 2025, 2026). Defaults to current year. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_past_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

### Get season list

List available MLH season years that have event pages. Probes years from 2020 to next year and returns those with valid event listings.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_season_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get upcoming events

Get upcoming (not yet ended) hackathon events for a given MLH season year. Returns only events with a pending or active status.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `year` | integer | No | MLH season year (e.g. 2025, 2026). Defaults to current year. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-mlh-io-api-ba747a40/get_upcoming_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```