# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/major-league-hacking/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/major-league-hacking/get-diversity-focused-events \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/major-league-hacking/get-events-by-region \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/major-league-hacking/get-events-by-season \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/major-league-hacking/get-events-in-date-range \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/major-league-hacking/get-events-this-month \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/major-league-hacking/get-past-events \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/major-league-hacking/get-season-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/major-league-hacking/get-upcoming-events \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"year":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.