# Major League Hacking — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.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.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.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.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.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.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.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.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.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>"}'
```