# Josaa — 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.

> Access JoSAA (Joint Seat Allocation Authority) admission data for IITs, NITs, IIITs, and GFTIs. Retrieve opening and closing ranks by institute, program, category, quota, and round for the current counselling session as well as historical data from 2016 onwards. Also query seat matrices and full institute details.

**Category:** Education | **Website:** [josaa.nic.in/](https://josaa.nic.in/) | **Docs:** [parse.bot/marketplace/81ec43e8-d011-4b27-afd9-8edf4e18d77d/josaa-nic-in-api](https://parse.bot/marketplace/81ec43e8-d011-4b27-afd9-8edf4e18d77d/josaa-nic-in-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-josaa-nic-in-api-81ec43e8/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_institute_list

Get the full list of participating institutes including codes, names, addresses, and contact information. No parameters required. Returns all IITs, NITs, IIITs, and GFTIs.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-josaa-nic-in-api-81ec43e8/get_institute_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_opening_closing_ranks

Fetch opening and closing rank data for the current admission session based on round, institute type, and category. Returns an array of rank entries. Data availability depends on the current counselling session progress; some institute types may not have data populated yet. Empty results are normal when the session has not started.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `branch` | string | No | Branch/program code or 'ALL'. |
| `inst_type` | string | Yes | Institute type. |
| `institute` | string | No | Institute code (numeric, from get_institute_list) or 'ALL'. |
| `round_no` | string | Yes | Round number. |
| `seat_type` | string | No | Seat type or 'ALL'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-josaa-nic-in-api-81ec43e8/get_opening_closing_ranks \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch":"<string>","inst_type":"<string>","institute":"<string>","round_no":"<string>","seat_type":"<string>"}'
```

### get_previous_years_ranks

Fetch historical opening and closing ranks from previous years (2016-2024). Returns an array of rank entries including institute name, program, quota, seat type, gender, and opening/closing ranks. Some combinations of year, inst_type, and seat_type may return empty results if data is unavailable for that period.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `branch` | string | No | Branch/program code or 'ALL'. |
| `inst_type` | string | Yes | Institute type. |
| `institute` | string | No | Institute code (numeric, from get_institute_list) or 'ALL'. |
| `round_no` | string | Yes | Round number. |
| `seat_type` | string | No | Seat type or 'ALL'. |
| `year` | string | Yes | Year from 2016 to 2024. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-josaa-nic-in-api-81ec43e8/get_previous_years_ranks \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch":"<string>","inst_type":"<string>","institute":"<string>","round_no":"<string>","seat_type":"<string>","year":"<string>"}'
```

### get_seat_matrix

Fetch the seat matrix showing seat availability per institute, program, seat pool, and category for the current session. Returns counts for each reservation category (OPEN, EWS, SC, ST, OBC-NCL and PwD variants). The inst_type parameter is required; 'ALL' is not supported due to server-side timeout.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `branch` | string | No | Branch/program code or 'ALL'. |
| `inst_type` | string | Yes | Institute type. |
| `institute` | string | No | Institute code (numeric, from get_institute_list) or 'ALL'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-josaa-nic-in-api-81ec43e8/get_seat_matrix \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch":"<string>","inst_type":"<string>","institute":"<string>"}'
```